The certo API

Do with a program what your team does in the console: invite candidates, follow their checklists, read approved passports, issue records.

2 minute read

The certo API lets an employer, a university or a learning provider work with certo from its own systems: an ATS, an HR system, a student records system, a script, or an AI agent.

What you can do with it

You are	Through the API you can
An employer	create positions, invite candidates, ask to read a passport, follow each candidate's checklist, read what a candidate approved, export
A university	issue verified degrees to a graduating class and follow who claimed them
A learning provider	issue certificates to learners and follow who claimed them
Any of them	read your organisation, your verifications, and manage your webhook

The full list of calls is in the API reference.

What it never does

The API does what your team can do in the console, and nothing more.

It reads only what a candidate approved. There is no search over passports and no bulk read. Every read of a passport goes through the same approval as in the console, is logged, and the candidate sees it.
Contact details and the date of birth stay separate permissions. They are in an answer only when the candidate shared them with you.
It never signs a claim. It issues records your organisation confirms about a person; the person still claims them.
It never changes who your organisation is. Members, roles, your company details, buying verifications and making API keys stay in the console.

How it works

Address: https://api.certo.bio/v1. The version is in the address; /v1 keeps working for at least twelve months after a /v2 exists.
Format: JSON in and out, times in UTC (ISO 8601), countries as two-letter codes, money as { "amount_cents": 990, "currency": "EUR" }.
Credentials: an API key made by an owner or an admin, sent as Authorization: Bearer certo_sk_live_....
Description: an OpenAPI 3.1 document at https://api.certo.bio/v1/openapi.json, generated from the same table the API runs on.
Errors, limits and retries are one set of rules for every call: see Errors, limits and retries.

A first call

curl https://api.certo.bio/v1/organisation \
  -H "Authorization: Bearer $CERTO_API_KEY"

{
  "id": "6f1c...",
  "name": "Northwind Ltd",
  "kinds": ["employer"],
  "state": "active",
  "profile_complete": true,
  "scopes": ["organisation:read", "hiring:read", "hiring:invite"]
}

Test and live

Keys made on certo's test environment start certo_sk_test_ and work only there; live keys start certo_sk_live_ and work only on certo.bio. A test key sent to the live API is refused, and the other way round.