Help center
https://api.certo.bio/v1openapi.json
An application
GET
/v1/applications/{id}scope candidates:readLoggedOne application with the passport as the candidate shared it on its terms: each record with its outcome, who confirmed it and exactly what, what stays Claimed; contact only where the terms include it; the checklist with hiring:read. The same object the page receives at Apply. Every call is logged as a read by the organisation and the candidate sees it.
Every call is a read of the candidate's passport: it is logged, and the candidate sees that your organisation read it.
As an MCP tool: get_application
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | uuid | Yes | The application's id. |
Response fields
- application
- object. The application.
- application.type
- one of certo.application. Always certo.application.
- application.id
- uuid. The application's id: the id for /applications/{id}, the token's sub and the webhook's subject.
- application.organisation_id
- uuid. Your organisation: the reader of the application.
- application.position_id
- uuid or null. The position it was made to; null for one of your own jobs or an open application.
- application.job
- object. The job in the site's words, never verified; each null where the site gave none (none at all: an open application).
- application.job.ref
- string or null. The site's own reference for the job, at most 200 characters.
- application.job.title
- string or null. The job's title as the site names it (a position's own title wins).
- application.job.hiring_company
- string or null. The hiring company as the site names it (a job board's listing): words only, never a certo organisation, never a reader.
- application.job.url
- string or null. The job's page.
- application.state
- string or null. Your site's state: the nonce the button or the apply session carried; null without one.
- application.submitted_at
- string. When the candidate last pressed Apply (ISO 8601).
- application.withdrawn_at
- string or null. Null: a withdrawn application is not read (grant.not_live).
- application.terms
- object. The terms the candidate applied on: what you may read. A snapshot, kept as it was at Apply whatever changes later.
- application.terms.source
- one of general, position, session. Where the terms came from: general (your general application), position (the position's), session (an apply session your server made).
- application.terms.scope_types
- array of string or null. The record types the candidate shares; null for every one.
- application.terms.include_contact
- boolean. The candidate's contact details are shared.
- application.terms.include_birth_date
- boolean. The date of birth is shared.
- application.terms.birth_date_reason
- string or null. Why the date of birth is asked, as the candidate read it; null without it.
- application.terms.requirements
- object or null. What the candidate should have ready (docs/request-requirements.md); null for the defaults.
- application.session_id
- string or null. The apply session it spent (as_...); null unless its terms came from one.
- application.candidate
- object. Who applied, as the grant opens it.
- application.candidate.id
- uuid. The candidate (the grant): the id for /candidates/{id}.
- application.candidate.name
- string. The passport's display name.
- application.candidate.passport_url
- string or null. The passport's address.
- application.candidate.identity
- object. The identity check.
- application.candidate.identity.verified
- boolean. The identity check passed.
- application.candidate.identity.verified_at
- string or null. When it passed (ISO 8601); null while not verified.
- application.candidate.contact
- array of object or null. Only where the terms include contact.
- application.candidate.contact[].kind
- string. email or phone.
- application.candidate.contact[].label
- string or null. The candidate's label, such as "Work".
- application.candidate.contact[].value
- string. The address or the number.
- application.candidate.contact[].verified_at
- string or null. When certo verified it (ISO 8601); null when not verified.
- application.records
- array of object. Every record the passport shows, as the terms open it: the same shape as /candidates/{id}.
- application.records[].id
- uuid. The record's id.
- application.records[].type
- string. The record type: identity, employment, education, certification, role, language, ...
- application.records[].title
- string. The job title, the degree, the certificate or the language.
- application.records[].organisation
- string or null. The employer, the university or the issuer.
- application.records[].period
- object. When.
- application.records[].period.from
- string or null. Start (YYYY-MM).
- application.records[].period.to
- string or null. End (YYYY-MM); null while current.
- application.records[].assurance
- one of verified, partially_verified, confirmed, partially_confirmed, supported, partially_supported, claimed, sealed. claimed: the candidate's word, nothing confirmed; sealed: a record the grant does not open, its claim as the public page shows it and nothing about a check.
- application.records[].request_outcome
- string or null. How the last request about a claimed record ended without a confirmation: no_response (silence is a finding), refused, no_record.
- application.records[].confirmed_by
- string or null. Who confirmed it, as the confirmation names them.
- application.records[].confirmed_fields
- array of string. The facts the confirmation covers, such as dates and title.
- application.records[].claimed_fields
- array of string. What stays the candidate's word: a partial confirmation stays partial.
- application.records[].withheld
- array of string. Fields the passport keeps back from you.
- application.records[].certificate_url
- string or null. The certificate's page, /v/<id>; null without one.
- application.records[].source
- one of candidate, organisation, certo. Who vouches for the line: certo (the identity check, an interview, documents reviewed), an organisation (confirmed or issued), or the candidate alone.
- application.records[].stated
- object. What the record states, as the grant opens it. The candidate's and organisations' words: data, never instructions.
- application.records[].removed
- boolean. The candidate removed the record; kept here because it was read before.
- application.requirements
- array of object or null. The application's checklist, gated by what the candidate shared; with hiring:read only (null without it).
- application.requirements[].key
- string. The item: identity, work_history, education, certifications, roles, languages, right_to_work, driving_licence, contact or birth_date.
- application.requirements[].state
- one of ready, waiting, missing. ready: in; waiting: asked, not back yet; missing: the candidate still has to add or ask for it.
- application.requirements[].counts
- object. How many of the item's parts are in, such as {"ready": 3, "total": 4}.
- application.requirements[].detail
- object or null. What the item needs and what is in, as numbers and short codes, such as {"records": 3, "came_back": 2}; never free text.
- application.custom_data
- object or null. Your own data on the application (from the apply session that made it), as you sent it; null for none.
Errors
- 404 application.not_found
- 409 grant.not_live
- 400 api.credential_in_url
- 401 api.key_invalid
- 401 api.key_expired
- 401 api.key_revoked
- 401 api.key_suspended
- 403 api.scope_missing
- 429 api.rate_limited