{"openapi":"3.1.0","info":{"title":"PeppyJobs employer API","version":"1.0.0","description":"Manage your company's jobs and applicants on PeppyJobs. Needs the Pro plan and an API key made at https://peppyjobs.com/hire/developers (owners and admins). Every request is limited to the key's own company. The same actions are available to AI assistants through the MCP server at https://peppyjobs.com/mcp.","contact":{"name":"PeppyJobs support","email":"support@peppyjobs.com","url":"https://peppyjobs.com/contact"},"termsOfService":"https://peppyjobs.com/legal/terms"},"servers":[{"url":"https://peppyjobs.com/api/v1"}],"security":[{"apiKey":[]}],"paths":{"/jobs":{"get":{"operationId":"listJobs","summary":"List your jobs","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","review","live","paused","closed","expired","rejected"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"perPage","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"page":{"type":"integer"},"perPage":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company blocked, or not on the Pro plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests a minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createJob","summary":"Create a job","description":"With publish=true (default) the job goes through the same genuine-job and quality checks as the website. Jobs that ask candidates for money are blocked.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Job"},"check":{"type":["object","null"],"properties":{"status":{"type":"string"},"message":{"type":"string"},"tips":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"string"}}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company blocked, or not on the Pro plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests a minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{id}":{"get":{"operationId":"getJob","summary":"Get one job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Job"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company blocked, or not on the Pro plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests a minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{id}/applications":{"get":{"operationId":"listApplications","summary":"Applicants for a job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"stage","in":"query","schema":{"type":"string","enum":["applied","viewed","shortlisted","interview","offer","hired","not_selected","withdrawn"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"perPage","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Application"}},"page":{"type":"integer"},"perPage":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company blocked, or not on the Pro plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests a minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/applications/{id}":{"get":{"operationId":"getApplication","summary":"Get one application","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Application"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company blocked, or not on the Pro plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests a minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/applications/{id}/stage":{"post":{"operationId":"moveApplication","summary":"Move an applicant to another stage","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["stage"],"properties":{"stage":{"type":"string","enum":["viewed","shortlisted","interview","offer","hired","not_selected"]},"reason":{"type":"string","maxLength":300}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Application"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Company blocked, or not on the Pro plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in your company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The candidate withdrew","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 requests a minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"pj_live_...","description":"Authorization: Bearer pj_live_... (Pro plan key from /hire/developers)."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}}}}},"JobInput":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"roleSlug":{"type":"string","description":"Job type id, e.g. accountant."},"summary":{"type":"string"},"responsibilities":{"type":"array","items":{"type":"string","maxLength":500},"maxItems":20},"requirements":{"type":"array","items":{"type":"string","maxLength":500},"maxItems":20},"benefits":{"type":"array","items":{"type":"string","maxLength":500},"maxItems":20},"skills":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":20},"languages":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":20},"experienceMinYears":{"type":"number"},"experienceMaxYears":{"type":["number","null"]},"salaryMin":{"type":["integer","null"],"description":"Monthly rupees."},"salaryMax":{"type":["integer","null"],"description":"Monthly rupees."},"areaId":{"type":"string","description":"Area id, e.g. mumbai-andheri-east."},"address":{"type":"string"},"workMode":{"type":"string","enum":["office","hybrid","remote","field"],"default":"office"},"jobType":{"type":"string","enum":["full_time","part_time","contract","internship"],"default":"full_time"},"shift":{"type":"string","enum":["day","night","rotational","flexible"],"default":"day"},"openings":{"type":"integer","default":1},"urgent":{"type":"boolean","default":false},"screening":{"type":"array","maxItems":10,"items":{"type":"object","required":["question","type"],"properties":{"question":{"type":"string","maxLength":200},"type":{"type":"string","enum":["yesno","text","number"]},"knockout":{"type":["string","null"],"enum":["yes","no",null]},"min":{"type":["number","null"]},"max":{"type":["number","null"]}}}},"publish":{"type":"boolean","default":true,"description":"false = save as a draft only."}}},"Job":{"type":"object","description":"A job of your company, as returned by the API.","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"url":{"type":"string","description":"Public job page."},"publishedAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"statusNote":{"type":["string","null"]},"salaryMin":{"type":["integer","null"]},"salaryMax":{"type":["integer","null"]},"areaId":{"type":["string","null"]}},"additionalProperties":true},"Application":{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"stage":{"type":"string"},"fit":{"type":["number","null"]},"createdAt":{"type":"string","format":"date-time"},"candidate":{"type":"object","description":"Name and headline; phone and email only after the candidate accepted your contact request.","properties":{"id":{"type":"string"},"name":{"type":"string"},"headline":{"type":"string"},"phone":{"type":["string","null"]},"email":{"type":["string","null"]}}}},"additionalProperties":true}}}}