The management API
Read jobs, applications, candidates and stages, and move, reject and tag candidates, add notes and publish or close jobs, from your own scripts and systems with a management token.
Reference3 min read
The management API is for your own scripts and other systems, such as an HR system that picks up new hires. It lives at https://app.bifrostorbit.com/careers/api/v1 and needs a management token from API keys. For showing jobs on your website, use the delivery API instead.
The management API is in the Growth and Enterprise plans. The delivery API is in every plan. See Plans and the trial.
curl -H "Authorization: Bearer careers_mt_..." \ "https://app.bifrostorbit.com/careers/api/v1/applications?status=hired&limit=20"A token acts as the person who created it, with their current role and permissions. GET/me shows who that is. A read-only token gets 403 on every change.
Endpoints
/me/jobsstatus=open, or one of draft, inReview, published, internal, closed or archived/jobs/{jobId}translations holding only what differs in each other language/jobs/{jobId}/status{ "status": "closed" }, one of published, internal, closed, archived or draft/stagesrejectionReasons/applicationsjobId, status (active, rejected, withdrawn or hired), stageId and updatedSince/applications/{applicationId}/applications/{applicationId}/move{ "stageId": "interview" }/applications/{applicationId}/reject{ "reasonId": "experience", "note": "…" }; the note is optional and for the team/candidatesq (name or email), email (one exact address) or tag/candidates/{candidateId}/candidates/{candidateId}/tags{ "tag": "Glacier certified" }. Add "remove": true to take it off/candidates/{candidateId}/notes{ "body": "Strong on glacier safety", "applicationId": "…" }. 201. Mentions notify colleagues| Method and path | What it does |
|---|---|
GET/me | The organisation, the person the token acts as, their role and their permissions |
GET/jobs | Every job, drafts and closed ones too. status=open, or one of draft, inReview, published, internal, closed or archived |
GET/jobs/{jobId} | One job with its text in the main language, and translations holding only what differs in each other language |
POST/jobs/{jobId}/status | Publish or close a job. Body: { "status": "closed" }, one of published, internal, closed, archived or draft |
GET/stages | Pipelines with their stages and stage types, and rejectionReasons |
GET/applications | Applications, newest first, without answers. Filter with jobId, status (active, rejected, withdrawn or hired), stageId and updatedSince |
GET/applications/{applicationId} | One application with the candidate's answers and file ids |
POST/applications/{applicationId}/move | Move to a stage. Body: { "stageId": "interview" } |
POST/applications/{applicationId}/reject | Reject with a reason. Body: { "reasonId": "experience", "note": "…" }; the note is optional and for the team |
GET/candidates | Candidates, newest first. Filter with q (name or email), email (one exact address) or tag |
GET/candidates/{candidateId} | One candidate with the applications you may read |
POST/candidates/{candidateId}/tags | Add a tag: { "tag": "Glacier certified" }. Add "remove": true to take it off |
POST/candidates/{candidateId}/notes | Add a note: { "body": "Strong on glacier safety", "applicationId": "…" }. 201. Mentions notify colleagues |
Changes follow the same rules as Careers Orbit itself:
- Publishing checks reviews, the job's required details and your plan's limit on live jobs.
- Moving runs the stage's automations, which may email the candidate. Moving to the rejected stage is refused: use
/rejectwith a reason. - After a trial or plan has ended, jobs can't be published or changed, but candidates can still be read and moved.
There is no endpoint to erase candidates or send emails; those stay with a person in Careers Orbit.
Pages
Lists return 50 items, or limit up to 100. When there are more, meta.next holds a cursor: send it back as cursor for the next page.
{ "data": [ … ], "meta": { "limit": 50, "next": "6a1f…" } }Privacy
Reading a candidate, a list of candidates or an application's answers is recorded in the audit trail, naming the token and its person, as opening a profile is. Lists of applications carry only ids, stages and sources. Contact details stay out of webhooks unless you mark one as trusted; read them here when you need them.
Errors and limits
Errors have the same shape everywhere: { "error": { "code": "forbidden", "message": "…" } }. Codes are unauthorized (401: a missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit), forbidden (403), not_found (404), invalid (400 or 422), conflict (409), rate_limited (429) and server_error (500). See Troubleshooting for each message.
A token may send about 120 requests a minute from one network. Answers are never cached.
Try it
The API playground runs every read with your token, and describes the changes without running them.
Was this page helpful?