Developers
Developers
One call starts a check. Webhooks tell you when it moves. Live in an afternoon.
Request
POST /v1/checks
{
"provider": { "email": "maya@example.com" },
"package": "care_standard"
}Response201 Created
{
"id": "chk_8Rq2",
"status": "consent_sent"
}An example check. Names are made up.
One call starts a check.
Send the provider’s email and a package. Roster does the rest.
The response carries the check id and a hosted consent link. Roster sends the link to the provider in your brand; you can also open it in your own onboarding flow.
Sandbox access is opening soon. The shape below is what the sandbox will serve.
Request
curl -X POST https://api.rosterchecks.com/v1/checks \
-H "Authorization: Bearer sk_test_…" \
-H "Content-Type: application/json" \
-d '{ "provider": { "email": "maya@example.com",
"first_name": "Maya" },
"package": "care_standard" }'Response201 Created
{
"id": "chk_8Rq2",
"status": "consent_sent",
"consent_url": "https://checks.yourmarketplace.com/c/8Rq2"
}Keys and scopes.
A bearer key per service, each with only the scopes it needs.
Send the key in the Authorization header. Sandbox keys start with sk_test_; live keys with sk_live_.
Scopes keep each caller to its job: checks:write starts checks, checks:read reads status, reports:read opens reports. Give agents a status-only key. How agent keys work.
| Scope | Lets the key |
|---|---|
| checks:write | Start a check and resend consent |
| checks:read | Read status and explain_status |
| reports:read | Open the report and PDF |
| webhooks:manage | Add and rotate webhook endpoints |
The endpoints.
Six calls cover the whole check, start to finish.
Scroll through each call and its response. The last one is a status-only key turned away from a report: the scope does its job.
POST/v1/checks
Start a check. Consent goes to the provider’s phone.
Request
curl -X POST https://api.rosterchecks.com/v1/checks \ -H "Authorization: Bearer sk_test_…" \ -d '{ "provider": { "email": "maya@example.com" }, "package": "care_standard" }'Response201 Created
{ "id": "chk_8Rq2", "status": "consent_sent", "consent_url": "https://checks.yourmarketplace.com/c/8Rq2" }POST/v1/checks/{id}/resend_consent
Send the consent link again, for a provider who hasn’t signed.
Request
curl -X POST https://api.rosterchecks.com/v1/checks/chk_8Rq2/resend_consent \ -H "Authorization: Bearer sk_test_…"Response200 OK
{ "id": "chk_8Rq2", "status": "consent_sent", "sent_to": "maya@example.com" }GET/v1/checks/{id}
Status by court, with an ETA.
Request
curl https://api.rosterchecks.com/v1/checks/chk_8Rq2 \ -H "Authorization: Bearer sk_test_status_…"Response200 OK
{ "id": "chk_8Rq2", "status": "in_progress", "searches": [ { "name": "national_criminal", "state": "confirmed" }, { "name": "county_criminal", "court": "Hamilton County, OH", "state": "searching", "eta": "2026-10-19" } ] }GET/v1/checks/{id}/explain
Plain English for the provider.
Request
curl https://api.rosterchecks.com/v1/checks/chk_8Rq2/explain \ -H "Authorization: Bearer sk_test_status_…"Response200 OK
{ "text": "Maya, your check is waiting on Hamilton County court. That usually takes one more business day." }GET/v1/checks?status=open
Every open check, and what each one is waiting on.
Request
curl "https://api.rosterchecks.com/v1/checks?status=open" \ -H "Authorization: Bearer sk_test_status_…"Response200 OK
{ "data": [ { "id": "chk_8Rq2", "status": "in_progress", "waiting_on": "Hamilton County, OH" }, { "id": "chk_3Lm9", "status": "consent_sent", "waiting_on": "provider" } ] }GET/v1/reports/{id}
The full report. Needs reports:read.
Request
curl https://api.rosterchecks.com/v1/reports/chk_8Rq2 \ -H "Authorization: Bearer sk_test_status_…"Response403 Forbidden
{ "error": "insufficient_scope", "message": "This key is status-only. Use a key with reports:read, or open the report page." }
Request
curl -X POST https://api.rosterchecks.com/v1/checks \
-H "Authorization: Bearer sk_test_…" \
-d '{ "provider": { "email": "maya@example.com" },
"package": "care_standard" }'Response201 Created
{
"id": "chk_8Rq2",
"status": "consent_sent",
"consent_url": "https://checks.yourmarketplace.com/c/8Rq2"
}Request
curl -X POST https://api.rosterchecks.com/v1/checks/chk_8Rq2/resend_consent \
-H "Authorization: Bearer sk_test_…"Response200 OK
{
"id": "chk_8Rq2",
"status": "consent_sent",
"sent_to": "maya@example.com"
}Request
curl https://api.rosterchecks.com/v1/checks/chk_8Rq2 \
-H "Authorization: Bearer sk_test_status_…"Response200 OK
{
"id": "chk_8Rq2",
"status": "in_progress",
"searches": [
{ "name": "national_criminal", "state": "confirmed" },
{ "name": "county_criminal", "court": "Hamilton County, OH",
"state": "searching", "eta": "2026-10-19" }
]
}Request
curl https://api.rosterchecks.com/v1/checks/chk_8Rq2/explain \
-H "Authorization: Bearer sk_test_status_…"Response200 OK
{
"text": "Maya, your check is waiting on Hamilton County court. That usually takes one more business day."
}Request
curl "https://api.rosterchecks.com/v1/checks?status=open" \
-H "Authorization: Bearer sk_test_status_…"Response200 OK
{
"data": [
{ "id": "chk_8Rq2", "status": "in_progress", "waiting_on": "Hamilton County, OH" },
{ "id": "chk_3Lm9", "status": "consent_sent", "waiting_on": "provider" }
]
}Request
curl https://api.rosterchecks.com/v1/reports/chk_8Rq2 \
-H "Authorization: Bearer sk_test_status_…"Response403 Forbidden
{
"error": "insufficient_scope",
"message": "This key is status-only. Use a key with reports:read, or open the report page."
}Webhooks tell you when it moves.
Three events cover a check: consent signed, updated, completed.
check.consent_signed fires when the provider signs and confirms their ID. check.updated fires as each search moves. check.completed fires when the analyst who confirmed each record at the court signs the report.
Each delivery is signed with your endpoint’s secret in the Roster-Signature header. Webhooks carry status, never record details. When a notice or letter is due, the check carries it ready to send, with the dates filled in; you send it and decide.
Request
POST https://yourmarketplace.com/webhooks/roster
Roster-Signature: t=1760620800,v1=5f2b…Response200 OK
{
"type": "check.completed",
"check": {
"id": "chk_8Rq2",
"status": "cleared",
"report_url": "https://reports.rosterchecks.com/chk_8Rq2"
}
}Sandbox first, then production.
The same API against made-up people, with clear results.
Sandbox keys come without a sales call. The sandbox runs every endpoint, webhook and hosted screen with test providers, so you can build the whole flow before you’re credentialed.
Live keys come after a short credentialing call: consumer reporting rules mean we confirm who you are and why you screen people. Then swap sk_test_ for sk_live_; nothing else changes. Get sandbox keys.
An MCP server for your agents.
Your agents order checks and explain delays. People decide.
The roster MCP server gives agents the same API with a status-only key. Each tool description says what it does and what it can’t.
An agent can never sign consent for a provider, read a full report on a status-only key, or start adverse action. What agents can and can’t do.
create_checkStarts a check and sends the provider the consent link.Agent canget_statusStatus by search, with the court each one is waiting on.Agent canexplain_statusOne plain sentence to pass to the provider.Agent canlist_checksOpen checks and what each is waiting on.Agent canresend_consentSends the consent link again.Agent canSign consentOnly the provider can sign.Agent can’tRead a reportNeeds a key with reports:read.Agent can’tAdverse actionA person on your team approves it.Agent can’t
Set it up with your coding agent.
Paste one prompt into Claude Code or Cursor.
The prompt points your coding agent at llms.txt, uses your sandbox key from the environment, and runs a test check end to end.
Read the diff before you merge it. The agent can wire up the calls and the webhook handler; your team still decides who gets onboarded.
Paste into your coding agent
Set up Roster in sandbox and run a test check.
Read https://www.rosterchecks.com/llms.txt first.
Use the sandbox key in ROSTER_API_KEY.
Create a check for a test provider, listen for
check.completed on /webhooks/roster, and show me
the report_url when it arrives.Docs your agents can read.
llms.txt and Markdown twins, in the same voice as the pages.
/llms.txt lists the site’s pages and every guide with its Markdown twin: the same URL plus .md, plain text with no layout to strip. When a developer asks a coding agent how to add background checks, this is what it reads.
The API reference will ship as an OpenAPI spec alongside it.
What Roster handles
Sandbox keys right away, no sales call. Live keys after a short credentialing call.
- One call starts a check. Hosted consent and live ID in your brand; a webhook when it’s done. Sandbox keys without a sales call.
- Status by API, webhook and MCP. explain_status says which court it’s waiting on and when to expect it.
- A named analyst matches every possible record to the provider and confirms it at the court before it’s reported. A signed report page and PDF your team can open.
- Every notice and letter prepared, with the waiting-period dates filled in, and a human approval gate before adverse action.
- You send the notices and make the final call. Contractors covered the same way as employees.
Reviewed November 5, 2026 by Dennis Drellishak, Owner.