API reference · v1

One endpoint. Three results. Honest webhooks.

The Sunlight Verified API runs three orchestrated checks for any applicant in a single request. Sample code and responses below — run them right here in the sandbox.

Overview

Every Sunlight Verified screening runs through POST /v1/checks. You supply the applicant and which sub-checks to run; we handle consent, document collection, state-by-state routing, and webhook delivery.

Base URL

https://api.sunlightverified.com

Auth

Bearer sk_live_… / sk_test_…

Content type

application/json

POST/v1/checks

Create a check

Creates a screening and emails or texts the applicant a secure consent link.

Field	Type	Description
applicant.full_name	string	Legal name as it will appear on the report.
applicant.email	string	Required if SMS not provided.
applicant.phone	string	Required if email not provided.
checks	string[]	Any of "network", "can_registry", "criminal".
callback_url	string	We POST progress updates here.

curl https://api.sunlightverified.com/v1/checks \
  -H "Authorization: Bearer sk_test_sandbox_42a9b" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant": {
      "full_name": "Jordan Rivera",
      "email": "jordan@example.com"
    },
    "checks": ["network", "can_registry", "criminal"],
    "callback_url": "https://yourapp.org/webhooks/sunlight"
  }'

Response— idle

// Click ▶ Run to send this request to the sandbox.

GET/v1/checks/:id

Retrieve a check

Returns the full status and result tree for a screening.

curl https://api.sunlightverified.com/v1/checks/chk_8aF92xK \
  -H "Authorization: Bearer sk_test_sandbox_42a9b"

Response— idle

// Click ▶ Run to send this request to the sandbox.

Webhooks

Subscribe to status updates. We sign every payload with HMAC-SHA256.

Field	Type	Description
check.created	event	Issued immediately on POST /v1/checks.
check.applicant_invited	event	Applicant received their consent link.
check.consent_signed	event	Applicant signed FCRA consent.
check.in_progress	event	All sub-checks have been dispatched.
check.completed	event	Final result is available.

POST https://yourapp.org/webhooks/sunlight
x-sunlight-signature: t=1717... v1=9c4f...

{
  "id": "evt_4Lk31Pm",
  "type": "check.completed",
  "data": {
    "id": "chk_8aF92xK",
    "result": "clear",
    "checks": { "network": "clear", "can_registry": "clear", "criminal": "clear" }
  }
}

Errors

Standard HTTP status codes with a stable, machine-readable error type.

Field	Type	Description
400 invalid_request	error	Missing or malformed parameters.
401 unauthorized	error	Invalid or missing API key.
409 applicant_conflict	error	Applicant has an active check in the last 24h.
422 unverifiable_state	error	A required CAN state cannot be reached right now.
429 rate_limited	error	Slow down. Retry-After header included.