https://api.certo.bio/v1openapi.json

An application

GET/v1/applications/{id}scope candidates:readLogged

One 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

NameTypeRequiredDescription
iduuidYesThe 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