API reference

Primary-source verification for licenses, NPI, exclusions, certifications, education and employment. JSON, camelCase, ISO-8601 UTC timestamps, ISO-3166-2 states. Async by default: create returns 201 with claims pending; long-poll with ?wait=25 or subscribe to signed webhooks. One error shape everywhere. Every response carries Request-Id, PrimaryCheck-Version, X-RateLimit-Limit and X-RateLimit-Remaining.

https://api.primarycheck.com · Live (pc_live_… keys)https://sandbox.primarycheck.com · Sandbox (pc_test_… keys; deterministic sources, webhooks fire)openapi.jsonversion 2026-11-03

Verifications Evidence Monitors Consents Webhooks Coverage and sources Account API keys Sign-up and sessions Disputes Adverse action FCRA program Health

Verifications

Create a verification with one to fifty claims, read it (long-poll with ?wait=), list, cancel, and fetch the consumer report.

post/v1/verifications

Create a verification

Async by default: 201 with every claim pending; work runs on the queue; webhooks fire on completion. ?wait= long-polls up to 25 s so fast checks (boards, datasets) return complete in one call.

Parameters

Parameter	In	Type	Description
`wait`	query	integer = 0
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyVerificationRequest

personobjectrequired

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimsarray of one ofrequired

items: one of 7 shapes

LicenseClaim

claimIdstring | null

type"license"

statestringrequired

professionstringrequired

numberstring | null

deaNumberstring | null

NpiClaim

claimIdstring | null

type"npi"

numberstringrequired

pattern ^\d{10}$

ExclusionScreen

claimIdstring | null

type"exclusion_screen"

npistring | null

HealthcareScreenClaim

claimIdstring | null

type"healthcare_screen"

statestringrequired

professionstringrequired

licenseNumberstring | null

npistring | null

pattern ^\d{10}$

CertificationClaim

claimIdstring | null

type"certification"

issuerstringrequired

credentialIdstring | null

EducationClaim

claimIdstring | null

type"education"

schoolstringrequired

schoolStatestring | null

degreestring | null

majorstring | null

graduatedYearinteger | null

attendedFromstring | null

attendedTostring | null

EmploymentClaim

claimIdstring | null

type"employment"

employerstringrequired

employerCitystring | null

employerStatestring | null

startstring | null

endstring | null

suppliedContactPhonestring | null

suppliedContactEmailstring | null

purposeenumrequired

employmentcurrent_staff_monitoringnetwork_credentialing

see Purpose

consentConsent | null

see Consent

optionsVerificationOptions | null

maxAge (ISO-8601 duration, default PT0S = always live), allowPaidThirdParty, deadline.

see VerificationOptions

allowPaidThirdPartybooleandeprecated

Deprecated top-level alias of options.allowPaidThirdParty; options wins when both are sent.

maxAgestring | nulldeprecated

Deprecated top-level alias of options.maxAge; options wins when both are sent.

referencestring | null

metadataobject

Responses

201Successful Response

ResponseVerification

idstringrequired

statusenumrequired

pendingcompletecancelled

purposeenumrequired

employmentcurrent_staff_monitoringnetwork_credentialing

see Purpose

personobjectrequired

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimsarray of ClaimResultrequired

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

items: 11 fields

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

items: 5 fields

fieldstringrequired

claimedany

foundany

matchboolean | null

notestring | null

evidencearray of Evidence

items: 8 fields

idstring | null

kindenumrequired

api_responsepage_capturedataset_rowdocumentrendered_recordoutreach_logcall_transcriptpartner_response

sourceCodestringrequired

sourceUrlstring | null

capturedAtstring (date-time)

sha256string | null

contentany | null

refstring | null

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

partsarray of ClaimResult

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

items: 11 fields

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

evidencearray of Evidence

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

partsarray of ClaimResult

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

partsarray of ClaimResult

createdAtstring (date-time)

completedAtstring (date-time) | null

referencestring | null

metadataobject

allowPaidThirdPartyboolean

maxAgestring | null

Errors: 400, 401, 403, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/verifications \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "person": {
      "firstName": "Amy",
      "middleName": "E",
      "lastName": "Kowalski",
      "dob": "1976-02-14",
      "email": "amy@example.com",
      "phone": "+1 412 555 0147"
    },
    "claims": [
      {
        "claimId": "c1",
        "type": "license",
        "state": "PA",
        "profession": "rn",
        "number": "RN353077L"
      }
    ],
    "purpose": "employment",
    "consent": {
      "consentId": "cons_8f1…"
    },
    "options": {
      "maxAge": "P1D",
      "deadline": "P7D"
    },
    "reference": "ATS-48213",
    "metadata": {
      "key": "value"
    }
  }'

get/v1/verifications

List verifications

Cursor-paginated. Filters: status, reference, createdAfter, personLastName.

Parameters

Parameter	In	Type	Description
`status`	query	string \| null	pending \| complete \| cancelled
`reference`	query	string \| null	Your reference, exact match.
`limit`	query	integer = 25	1–100, default 25.
`startingAfter`	query	string \| null	Cursor: the last id of the previous page.
`createdAfter`	query	string	ISO-8601 timestamp.
`personLastName`	query	string	Exact last name.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200A page of results.

Responseobject

dataarray of Verificationrequired

items: 11 fields

idstringrequired

statusenumrequired

pendingcompletecancelled

purposeenumrequired

employmentcurrent_staff_monitoringnetwork_credentialing

see Purpose

personobjectrequired

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimsarray of ClaimResultrequired

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

items: 11 fields

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

evidencearray of Evidence

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

partsarray of ClaimResult

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

partsarray of ClaimResult

createdAtstring (date-time)

completedAtstring (date-time) | null

referencestring | null

metadataobject

allowPaidThirdPartyboolean

maxAgestring | null

hasMoreboolean

Errors: 401, 403, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/verifications \
  -H "Authorization: Bearer pc_live_…"

get/v1/verifications/{id}

Retrieve a verification

?wait= long-polls up to 25 s for a pending verification to complete.

Parameters

Parameter	In	Type	Description
`id`req	path	string	The verification id.
`wait`	query	integer = 0
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful Response

ResponseVerification

idstringrequired

statusenumrequired

pendingcompletecancelled

purposeenumrequired

employmentcurrent_staff_monitoringnetwork_credentialing

see Purpose

personobjectrequired

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimsarray of ClaimResultrequired

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

items: 11 fields

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

items: 5 fields

fieldstringrequired

claimedany

foundany

matchboolean | null

notestring | null

evidencearray of Evidence

items: 8 fields

idstring | null

kindenumrequired

api_responsepage_capturedataset_rowdocumentrendered_recordoutreach_logcall_transcriptpartner_response

sourceCodestringrequired

sourceUrlstring | null

capturedAtstring (date-time)

sha256string | null

contentany | null

refstring | null

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

partsarray of ClaimResult

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

items: 11 fields

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

evidencearray of Evidence

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

partsarray of ClaimResult

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

partsarray of ClaimResult

createdAtstring (date-time)

completedAtstring (date-time) | null

referencestring | null

metadataobject

allowPaidThirdPartyboolean

maxAgestring | null

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/verifications/ver_7c1e0b1f2a9d \
  -H "Authorization: Bearer pc_live_…"

post/v1/verifications/{id}/cancel

Cancel a verification

Pending claims become unable_to_verify(cancelled); final claims keep their verdicts. Open outreach jobs are closed and a verification.updated webhook fires. 409 already_complete when nothing is pending.

Parameters

Parameter	In	Type	Description
`id`req	path	string	The verification id.
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful Response

ResponseVerification

idstringrequired

statusenumrequired

pendingcompletecancelled

purposeenumrequired

employmentcurrent_staff_monitoringnetwork_credentialing

see Purpose

personobjectrequired

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimsarray of ClaimResultrequired

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

items: 11 fields

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

items: 5 fields

fieldstringrequired

claimedany

foundany

matchboolean | null

notestring | null

evidencearray of Evidence

items: 8 fields

idstring | null

kindenumrequired

api_responsepage_capturedataset_rowdocumentrendered_recordoutreach_logcall_transcriptpartner_response

sourceCodestringrequired

sourceUrlstring | null

capturedAtstring (date-time)

sha256string | null

contentany | null

refstring | null

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

partsarray of ClaimResult

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

items: 11 fields

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

evidencearray of Evidence

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

partsarray of ClaimResult

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

partsarray of ClaimResult

createdAtstring (date-time)

completedAtstring (date-time) | null

referencestring | null

metadataobject

allowPaidThirdPartyboolean

maxAgestring | null

Errors: 400, 401, 403, 404, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/verifications/ver_7c1e0b1f2a9d/cancel \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)"

get/v1/verifications/{id}/evidence

List evidence for a verification

The evidence index across every claim and source. Use GET /v1/evidence/{id} for a signed download URL.

Parameters

Parameter	In	Type	Description
`id`req	path	string	The verification id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200A page of results.

Responseobject

dataarray of EvidenceIndexRowrequired

items: 10 fields

idstring | null

claimIndexinteger

sourcestring

kindstring

sha256string | null

capturedAtstring (date-time)

sourceUrlstring | null

refstring | null

inlineboolean

indexinteger

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/verifications/ver_7c1e0b1f2a9d/evidence \
  -H "Authorization: Bearer pc_live_…"

get/v1/verifications/{id}/report.pdf

Download the consumer report PDF

Every claim with its field checks and an evidence index; the FCRA Summary of Rights is appended. Response is application/pdf.

Parameters

Parameter	In	Type	Description
`id`req	path	string	The verification id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200The consumer report. · application/pdf

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/verifications/ver_7c1e0b1f2a9d/report.pdf \
  -H "Authorization: Bearer pc_live_…" \
  -o report.pdf

Evidence

Every source result carries evidence ids. Fetch metadata, hashes and a 15-minute signed download URL.

get/v1/evidence/{id}

Retrieve evidence

Metadata, sha256, and a signed url that expires at expiresAt (about 15 minutes).

Parameters

Parameter	In	Type	Description
`id`req	path	string	The object id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful response

ResponseEvidenceObject

idstring

objectenum

evidence

verificationIdstring

sourceCodestring

kindenum

api_responsepage_capturedataset_rowdocumentrendered_recordoutreach_logcall_transcriptpartner_response

sourceUrlstring | null

contentTypestring

sha256string

bytesinteger

capturedAtstring (date-time)

urlstring

Signed download URL; no API key needed.

expiresAtstring (date-time)

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/evidence/evd_… \
  -H "Authorization: Bearer pc_live_…"

get/v1/evidence/{id}/contentno auth

Download evidence content

The bytes behind an evidence record. Reachable through the signed url (?exp=&sig=, no API key) or with the owning account's key.

Parameters

Parameter	In	Type	Description
`id`req	path	string	The object id.
`exp`	query	string \| null
`sig`	query	string \| null
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200The evidence bytes (JSON, PDF, PNG or HTML). · */*

Errors: 404, 429, default — one shape, Error

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/evidence/evd_…/content

Monitors

Re-check a claim on a cadence and receive monitor.changed webhooks.

post/v1/monitors

Create a monitor

Parameters

Parameter	In	Type	Description
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyMonitorIn

personobjectrequired

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimone ofrequired

one of 7 shapes

LicenseClaim

claimIdstring | null

type"license"

statestringrequired

professionstringrequired

numberstring | null

deaNumberstring | null

NpiClaim

claimIdstring | null

type"npi"

numberstringrequired

pattern ^\d{10}$

ExclusionScreen

claimIdstring | null

type"exclusion_screen"

npistring | null

HealthcareScreenClaim

claimIdstring | null

type"healthcare_screen"

statestringrequired

professionstringrequired

licenseNumberstring | null

npistring | null

pattern ^\d{10}$

CertificationClaim

claimIdstring | null

type"certification"

issuerstringrequired

credentialIdstring | null

EducationClaim

claimIdstring | null

type"education"

schoolstringrequired

schoolStatestring | null

degreestring | null

majorstring | null

graduatedYearinteger | null

attendedFromstring | null

attendedTostring | null

EmploymentClaim

claimIdstring | null

type"employment"

employerstringrequired

employerCitystring | null

employerStatestring | null

startstring | null

endstring | null

suppliedContactPhonestring | null

suppliedContactEmailstring | null

cadenceenum

dailyweeklymonthly

consentConsent | null

Required on live accounts (consentId, or disclosureVersion + signedAt).

see Consent

Responses

201Successful response

ResponseMonitor

idstring

objectenum

monitor

statusenum

activestopped

cadenceenum

dailyweeklymonthly

personobject

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimobject

The claim exactly as sent.

snapshotobject | null

verdict, reason, watched record fields, actions count, checkedAt

lastCheckedAtstring (date-time) | null

nextCheckAtstring (date-time) | null

createdAtstring (date-time)

stoppedAtstring (date-time) | null

Errors: 400, 401, 403, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/monitors \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "person": {
      "firstName": "Amy",
      "middleName": "E",
      "lastName": "Kowalski",
      "dob": "1976-02-14",
      "email": "amy@example.com",
      "phone": "+1 412 555 0147"
    },
    "claim": {
      "claimId": "c1",
      "type": "license",
      "state": "PA",
      "profession": "rn",
      "number": "RN353077L"
    },
    "consent": {
      "consentId": "cons_8f1…"
    }
  }'

get/v1/monitors

List monitors

Parameters

Parameter	In	Type	Description
`status`	query	string \| null
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200A page of results.

Responseobject

dataarray of Monitorrequired

items: 11 fields

idstring

objectenum

monitor

statusenum

activestopped

cadenceenum

dailyweeklymonthly

personobject

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimobject

The claim exactly as sent.

snapshotobject | null

verdict, reason, watched record fields, actions count, checkedAt

lastCheckedAtstring (date-time) | null

nextCheckAtstring (date-time) | null

createdAtstring (date-time)

stoppedAtstring (date-time) | null

hasMoreboolean

Errors: 401, 403, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/monitors \
  -H "Authorization: Bearer pc_live_…"

get/v1/monitors/{id}

Retrieve a monitor

Parameters

Parameter	In	Type	Description
`id`req	path	string	The monitor id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful response

ResponseMonitor

idstring

objectenum

monitor

statusenum

activestopped

cadenceenum

dailyweeklymonthly

personobject

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimobject

The claim exactly as sent.

snapshotobject | null

verdict, reason, watched record fields, actions count, checkedAt

lastCheckedAtstring (date-time) | null

nextCheckAtstring (date-time) | null

createdAtstring (date-time)

stoppedAtstring (date-time) | null

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/monitors/mon_… \
  -H "Authorization: Bearer pc_live_…"

delete/v1/monitors/{id}

Stop a monitor

Billing stops at the end of the current period.

Parameters

Parameter	In	Type	Description
`id`req	path	string	The monitor id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful response

ResponseMonitorStopped

idstring

statusenum

stopped

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X DELETE https://api.primarycheck.com/v1/monitors/mon_… \
  -H "Authorization: Bearer pc_live_…"

get/v1/monitors/{id}/events

List monitor change events

Parameters

Parameter	In	Type	Description
`id`req	path	string	The monitor id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200A page of results.

Responseobject

dataarray of MonitorEventrequired

items: 5 fields

idstring

kindenum

verdictstatusexpiresactionrecord

diffobject

webhookEventIdstring | null

createdAtstring (date-time)

hasMoreboolean

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/monitors/mon_…/events \
  -H "Authorization: Bearer pc_live_…"

Consents

Hosted FCRA disclosure and authorization: create a link, read its status.

post/v1/consents

Create a hosted consent

Returns a url to send the candidate to. The signed disclosure is stored as evidence.

Parameters

Parameter	In	Type	Description
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyConsentIn

personobjectrequired

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

purposeenum

employmentcurrent_staff_monitoringnetwork_credentialing

customerNamestring | null

Shown on the hosted page as the party ordering the report.

statestring | null

Consumer's state for state-specific disclosure add-ons (CA, NY, …).

Responses

201Successful response

ResponseConsentRecord

idstring

objectenum

consent

statusenum

pendingsignedexpired

purposestring

personobject

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

disclosureVersionstring

stateAddonsarray of string

urlstring | null

Hosted consent page; null once signed.

signedAtstring (date-time) | null

signerIpstring | null

evidenceIdstring | null

expiresAtstring (date-time) | null

createdAtstring (date-time)

Errors: 400, 401, 403, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/consents \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "person": {
      "firstName": "Amy",
      "middleName": "E",
      "lastName": "Kowalski",
      "dob": "1976-02-14",
      "email": "amy@example.com",
      "phone": "+1 412 555 0147"
    },
    "customerName": "Mercy Staffing",
    "state": "PA"
  }'

get/v1/consents/{id}

Retrieve a consent

Parameters

Parameter	In	Type	Description
`id`req	path	string	The consent id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful response

ResponseConsentRecord

idstring

objectenum

consent

statusenum

pendingsignedexpired

purposestring

personobject

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

disclosureVersionstring

stateAddonsarray of string

urlstring | null

Hosted consent page; null once signed.

signedAtstring (date-time) | null

signerIpstring | null

evidenceIdstring | null

expiresAtstring (date-time) | null

createdAtstring (date-time)

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/consents/cons_… \
  -H "Authorization: Bearer pc_live_…"

Webhooks

Endpoints, signed deliveries, retries and replay.

post/v1/webhook_endpoints

Create a webhook endpoint

The signing secret is returned once.

Parameters

Parameter	In	Type	Description
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyWebhookEndpointIn

urlstringrequired

pattern ^https?://

eventsarray of enumrequired

Responses

201Successful response

ResponseWebhookEndpointCreated

idstringrequired

objectenum

webhook_endpoint

urlstringrequired

eventsarray of stringrequired

modeenum

livetest

statusstring

createdAtstring (date-time)

secretstringrequired

Shown once. HMAC key for PrimaryCheck-Signature.

Errors: 400, 401, 403, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/webhook_endpoints \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ats.example.com/primarycheck",
    "events": [
      "verification.completed"
    ]
  }'

get/v1/webhook_endpoints

List webhook endpoints

Parameters

Parameter	In	Type	Description
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200A page of results.

Responseobject

dataarray of WebhookEndpointrequired

items: 7 fields

idstringrequired

objectenum

webhook_endpoint

urlstringrequired

eventsarray of stringrequired

modeenum

livetest

statusstring

createdAtstring (date-time)

hasMoreboolean

Errors: 401, 403, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/webhook_endpoints \
  -H "Authorization: Bearer pc_live_…"

delete/v1/webhook_endpoints/{id}

Delete a webhook endpoint

Parameters

Parameter	In	Type	Description
`id`req	path	string	The webhook id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful response

ResponseDeleted

idstring

deletedenum

true

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X DELETE https://api.primarycheck.com/v1/webhook_endpoints/we_… \
  -H "Authorization: Bearer pc_live_…"

get/v1/webhook_endpoints/{id}/deliveries

List deliveries

Most recent first, with status code, latency and the next retry time.

Parameters

Parameter	In	Type	Description
`id`req	path	string	The webhook id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200A page of results.

Responseobject

dataarray of WebhookDeliveryrequired

items: 9 fields

idstring

eventIdstring

eventTypestring

attemptinteger

statusCodeinteger | null

responseMsinteger | null

deliveredAtstring (date-time) | null

nextRetryAtstring (date-time) | null

createdAtstring (date-time)

hasMoreboolean

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/webhook_endpoints/we_…/deliveries \
  -H "Authorization: Bearer pc_live_…"

post/v1/webhook_endpoints/{id}/deliveries/{deliveryId}/retry

Retry a delivery

Parameters

Parameter	In	Type	Description
`id`req	path	string	The webhook id.
`deliveryId`req	path	string	The webhook id.
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful response

ResponseQueued

idstring

queuedenum

true

Errors: 400, 401, 403, 404, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/webhook_endpoints/we_…/deliveries/dlv_…/retry \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)"

Coverage and sources

What can be verified where, the profession taxonomy, and every connector's status. Unauthenticated.

get/v1/coverageno auth

Coverage by state and profession

Without filters, every (state, profession) row.

Parameters

Parameter	In	Type	Description
`state`	query	string \| null	ISO-3166-2 code, e.g. PA.
`profession`	query	string \| null	Taxonomy key from GET /v1/professions.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200A page of results.

Responseobject

dataarray of CoverageRowrequired

items: 11 fields

statestring

professionstring

labelstring

boardstring

boardTypestring

sourcestring | null

statusenum

livedegradedbuildingblocked

searchByarray of string

fieldsarray of string

compactstring | null

lookupUrlstring | null

Errors: 429, default — one shape, Error

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/coverage

get/v1/professionsno auth

Profession taxonomy

Parameters

Parameter	In	Type	Description
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200A page of results.

Responseobject

dataarray of Professionrequired

items: 5 fields

keystring

labelstring

categorystring

boardTypestring

compactstring | null

Errors: 429, default — one shape, Error

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/professions

get/v1/sourcesno auth

Sources

Every connector with mode, role, status, last canary and 24-hour error rate.

Parameters

Parameter	In	Type	Description
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200A page of results.

Responseobject

dataarray of Sourcerequired

items: 14 fields

codestring

namestring

claimTypesarray of string

modestring

rolestring

statusstring

rungstring | null

lastCanaryAtstring (date-time) | null

lastCanaryOkboolean | null

errorRate24hnumber | null

calls24hinteger

dataAsOfstring (date-time) | null

datasetFreshboolean | null

datasetsarray of object

items: 4 fields

codestring

dataAsOfstring (date-time) | null

rowsinteger

maxAgeDaysinteger

Errors: 429, default — one shape, Error

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/sources

Account

Account settings, usage and spend, team members and invites.

get/v1/account

Retrieve the account

Parameters

Parameter	In	Type	Description
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful response

ResponseAccount

idstring

namestring | null

fcraStatusenum

not_appliedpendingenabled

certifiedPurposesarray of string

versionstring

controlsVersionstring

planstring | null

limitsobject

authenum

keysession

rolestring | null

userobject | null

3 fields

idstring

emailstring

namestring | null

Errors: 401, 403, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/account \
  -H "Authorization: Bearer pc_live_…"

patch/v1/account

Update the account

Owner or admin session.

Parameters

Parameter	In	Type	Description
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyAccountPatch

namestring | null

Responses

200Successful response

ResponseAccountUpdated

idstring

namestring

planstring | null

fcraStatusstring

Errors: 400, 401, 403, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X PATCH https://api.primarycheck.com/v1/account \
  -H "Authorization: Bearer pc_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ATS production"
  }'

get/v1/account/audit

Export the audit log

Every key, user and consumer action on this account, newest first.

Parameters

Parameter	In	Type	Description
`since`	query	string (date-time) \| null
`limit`	query	integer = 1000
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful Response

Responseobject

object

Errors: 401, 403, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/account/audit \
  -H "Authorization: Bearer pc_live_…"

get/v1/account/members

List team members

Parameters

Parameter	In	Type	Description
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200A page of results.

Responseobject

dataarray of Memberrequired

items: 6 fields

idstring

userIdstring

emailstring

namestring | null

roleenum

owneradminmemberviewerops

createdAtstring (date-time)

Errors: 401, 403, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/account/members \
  -H "Authorization: Bearer pc_live_…"

post/v1/account/members/invites

Invite a team member

Owner or admin session. The invite is mailed; valid for 7 days.

Parameters

Parameter	In	Type	Description
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyInviteIn

emailstringrequired

rolestring

Responses

201Successful response

ResponseInvite

idstring

emailstring

rolestring

expiresAtstring (date-time)

acceptUrlstring

Non-production only.

Errors: 400, 401, 403, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/account/members/invites \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "amy@example.com"
  }'

patch/v1/account/members/{id}

Change a member's role

Parameters

Parameter	In	Type	Description
`id`req	path	string	The object id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyRolePatch

rolestringrequired

Responses

200Successful response

ResponseMember

idstring

userIdstring

emailstring

namestring | null

roleenum

owneradminmemberviewerops

createdAtstring (date-time)

Errors: 400, 401, 403, 404, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X PATCH https://api.primarycheck.com/v1/account/members/mem_… \
  -H "Authorization: Bearer pc_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "member"
  }'

delete/v1/account/members/{id}

Remove a member

Parameters

Parameter	In	Type	Description
`id`req	path	string	The object id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

204Successful Response

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X DELETE https://api.primarycheck.com/v1/account/members/mem_… \
  -H "Authorization: Bearer pc_live_…"

get/v1/usage

Usage and spend

Counts and spend by claim type for a date range, split by channel (API vs dashboard). groupBy=day (default) or type.

Parameters

Parameter	In	Type	Description
`from`	query	string \| null	YYYY-MM-DD or ISO-8601; default 30 days before `to`.
`to`	query	string \| null	YYYY-MM-DD (inclusive) or ISO-8601; default now.
`groupBy`	query	string = day	`day` (default) or `type`.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful response

ResponseUsage

fromstring (date-time)

tostring (date-time)

groupByenum

daytype

countsobject

Claims by type (license, healthcare_screen, …, monitor).

spendCentsinteger

byChannelobject

2 fields

apiobject

2 fields

countinteger

spendCentsinteger

dashboardobject

2 fields

countinteger

spendCentsinteger

seriesarray of object

items: 4 fields

datestring

YYYY-MM-DD when groupBy=day

typestring

claim type when groupBy=type

countinteger

spendCentsinteger

Errors: 401, 403, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/usage \
  -H "Authorization: Bearer pc_live_…"

API keys

Create, list and revoke keys (dashboard session required).

post/v1/api_keys

Create an API key

Session required. The full key is returned once. Live keys need owner or admin.

Parameters

Parameter	In	Type	Description
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyKeyIn

namestringrequired

modestringrequired

pattern ^(live|test)$

Responses

201Successful response

ResponseApiKeyCreated

idstring

namestring

modeenum

livetest

prefixstring

createdAtstring (date-time)

lastUsedAtstring (date-time) | null

revokedAtstring (date-time) | null

keystringrequired

The full key. Shown once.

Errors: 400, 401, 403, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/api_keys \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ATS production",
    "mode": "live"
  }'

get/v1/api_keys

List API keys

Parameters

Parameter	In	Type	Description
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200A page of results.

Responseobject

dataarray of ApiKeyrequired

items: 7 fields

idstring

namestring

modeenum

livetest

prefixstring

createdAtstring (date-time)

lastUsedAtstring (date-time) | null

revokedAtstring (date-time) | null

Errors: 401, 403, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/api_keys \
  -H "Authorization: Bearer pc_live_…"

delete/v1/api_keys/{id}

Revoke an API key

Parameters

Parameter	In	Type	Description
`id`req	path	string	The api key id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

204Successful Response

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X DELETE https://api.primarycheck.com/v1/api_keys/key_… \
  -H "Authorization: Bearer pc_live_…"

Sign-up and sessions

Self-serve sign-up and magic-link sessions used by the dashboard.

post/v1/invites/{token}/acceptno auth

Accept an invite

Returns a session.

Parameters

Parameter	In	Type	Description
`token`req	path	string	The sign-up and session id.
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyAcceptIn

namestring | null

Responses

200Successful response

ResponseSession

sessionTokenstring

userobject

3 fields

idstring

emailstring

namestring | null

accountobject

5 fields

idstring

namestring

planstring | null

fcraStatusstring

isStaffboolean

roleenum

owneradminmemberviewerops

expiresAtstring (date-time)

Errors: 400, 404, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

404No such object on this account.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/invites/…/accept \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ATS production"
  }'

post/v1/sessionsno auth

Request a magic link

Always 202; never reveals whether the email exists.

Parameters

Parameter	In	Type	Description
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodySessionIn

emailstringrequired

Responses

202Successful response

ResponseMagicLinkRequested

sentenum

true

Errors: 400, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/sessions \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "amy@example.com"
  }'

delete/v1/sessions/current

Sign out

Parameters

Parameter	In	Type	Description
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

204Successful Response

Errors: 401, 403, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X DELETE https://api.primarycheck.com/v1/sessions/current \
  -H "Authorization: Bearer pc_live_…"

post/v1/sessions/exchangeno auth

Exchange a login token for a session

Parameters

Parameter	In	Type	Description
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyExchangeIn

tokenstringrequired

Responses

200Successful response

ResponseSession

sessionTokenstring

userobject

3 fields

idstring

emailstring

namestring | null

accountobject

5 fields

idstring

namestring

planstring | null

fcraStatusstring

isStaffboolean

roleenum

owneradminmemberviewerops

expiresAtstring (date-time)

Errors: 400, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/sessions/exchange \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "…"
  }'

post/v1/signupno auth

Sign up

Creates the account, the owner user and a default test key; mails a sign-in link.

Parameters

Parameter	In	Type	Description
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodySignupIn

emailstringrequired

namestringrequired

companystringrequired

Responses

201Successful response

ResponseSignupResult

accountobject

2 fields

idstring

namestring

userobject

3 fields

idstring

emailstring

namestring | null

loginUrlstring

Non-production only.

Errors: 400, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/signup \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "amy@example.com",
    "name": "ATS production",
    "company": "Mercy Staffing"
  }'

Disputes

Consumer-initiated disputes touching this account's reports.

get/v1/disputes

List disputes

Disputes consumers opened against this account's reports, with status and due dates.

Parameters

Parameter	In	Type	Description
`status`	query	string \| null
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful Response

Responseobject

object

Errors: 401, 403, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/disputes \
  -H "Authorization: Bearer pc_live_…"

get/v1/disputes/{id}

Retrieve a dispute

Status, dueAt, outcome and the corrected verification id when resolved.

Parameters

Parameter	In	Type	Description
`id`req	path	string	The dispute id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful Response

Responseobject

object

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/disputes/dsp_… \
  -H "Authorization: Bearer pc_live_…"

Adverse action

Pre-adverse and final adverse-action notices with the waiting period enforced.

post/v1/verifications/{id}/adverse_action

Start adverse action

Sends the pre-adverse notice with the report copy and Summary of Rights; starts the waiting period.

Parameters

Parameter	In	Type	Description
`id`req	path	string	The object id.
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyAdverseIn

reasonSummarystring | null

deliverToEmailstring | null

Responses

201Successful Response

Responseobject

object

Errors: 400, 401, 403, 404, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/verifications/ver_7c1e0b1f2a9d/adverse_action \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

get/v1/verifications/{id}/adverse_action

Retrieve adverse-action status

Parameters

Parameter	In	Type	Description
`id`req	path	string	The object id.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful Response

Responseobject

object

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/verifications/ver_7c1e0b1f2a9d/adverse_action \
  -H "Authorization: Bearer pc_live_…"

post/v1/verifications/{id}/adverse_action/final

Send the final adverse-action notice

Refused until the waiting period has passed.

Parameters

Parameter	In	Type	Description
`id`req	path	string	The object id.
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyAdverseIn

reasonSummarystring | null

deliverToEmailstring | null

Responses

200Successful Response

Responseobject

object

Errors: 400, 401, 403, 404, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/verifications/ver_7c1e0b1f2a9d/adverse_action/final \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

get/v1/verifications/{id}/adverse_action/notice.{fmt}

Download an adverse-action notice

fmt is pdf or html.

Parameters

Parameter	In	Type	Description
`id`req	path	string	The object id.
`fmt`req	path	string	The object id.
`stage`	query	string = pre_adverse
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful Response

Responseobject

object

Errors: 401, 403, 404, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/verifications/ver_7c1e0b1f2a9d/adverse_action/notice.pdf \
  -H "Authorization: Bearer pc_live_…"

post/v1/verifications/{id}/adverse_action/withdraw

Withdraw adverse action

Parameters

Parameter	In	Type	Description
`id`req	path	string	The object id.
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful Response

Responseobject

object

Errors: 400, 401, 403, 404, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

404No such object on this account.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/verifications/ver_7c1e0b1f2a9d/adverse_action/withdraw \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)"

FCRA program

Customer vetting application, notices, and the account's FCRA status.

get/v1/account/fcra

FCRA status

fcraStatus, certified purposes and the vetting application.

Parameters

Parameter	In	Type	Description
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful Response

Responseobject

object

Errors: 401, 403, 429, default — one shape, Error

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/account/fcra \
  -H "Authorization: Bearer pc_live_…"

post/v1/account/fcra/application

Apply for FCRA access

Customer vetting (§607(a)). Live keys are issued after approval.

Parameters

Parameter	In	Type	Description
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyFcraApplication

legalNamestringrequired

einstringrequired

pattern ^\d{2}-?\d{7}$

addressstringrequired

websitestringrequired

pattern ^https?://

natureOfBusinessstringrequired

intendedPurposesarray of stringrequired

expectedMonthlyVolumeintegerrequired

signerNamestringrequired

signerTitlestringrequired

agreementAcceptedbooleanrequired

agreementVersionstringrequired

certificationsobject

Responses

201Successful Response

Responseobject

object

Errors: 400, 401, 403, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/account/fcra/application \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "…",
    "ein": "…",
    "address": "…",
    "website": "…",
    "natureOfBusiness": "…",
    "intendedPurposes": [
      "…"
    ],
    "expectedMonthlyVolume": 1,
    "signerName": "…",
    "signerTitle": "…",
    "agreementAccepted": true,
    "agreementVersion": "…",
    "certifications": {
      "key": "value"
    }
  }'

post/v1/account/fcra/notices/accept

Accept the FCRA notices

Records acceptance of the Notice to Users and related notices.

Parameters

Parameter	In	Type	Description
`Idempotency-Key`	header	string (uuid)	UUID. For 24 hours the same key returns the original response without re-running sources or billing. Same key with a different body → `409 idempotency_conflict`. The SDKs send one on every POST.
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Request body application/json, required

BodyNoticesAccept

acceptedBystringrequired

Responses

200Successful Response

Responseobject

object

Errors: 400, 401, 403, 409, 429, default — one shape, Error

400Validation failed (validation_error, param names the field) or a domain rule (profession_unknown, cadence_invalid, …).

401Missing, unknown or revoked key (missing_api_key, invalid_api_key, invalid_session).

403fcra_not_enabled, purpose_not_certified, consent_required, read_only_role, session_required.

409idempotency_conflict, already_complete, already_cancelled, consent_already_signed.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl -X POST https://api.primarycheck.com/v1/account/fcra/notices/accept \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "acceptedBy": "…"
  }'

get/v1/noticesno auth

List FCRA notice documents

Parameters

Parameter	In	Type	Description
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful Response

Responseobject

object

Errors: 429, default — one shape, Error

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/notices

get/v1/notices/{name}no auth

Retrieve an FCRA notice document

Parameters

Parameter	In	Type	Description
`name`req	path	string	The object id.
`format`	query	string = json
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful Response

Responseobject

object

Errors: 404, 429, default — one shape, Error

404No such object on this account.

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/notices/summary_of_rights

Health

Liveness.

get/v1/healthno auth

Health

Parameters

Parameter	In	Type	Description
`PrimaryCheck-Version`	header	string	Pin behavior to an API version date. Defaults to the version pinned on the account. Additive changes never bump it.

Responses

200Successful response

ResponseHealth

okboolean

controlsstring

versionstring

Errors: 429, default — one shape, Error

429Rate limited (rate_limited). Wait Retry-After seconds.

defaultAny other error, in the one error shape.

curl

curl https://api.primarycheck.com/v1/health

Schemas

Every object the API sends or accepts. Click a name from any operation to jump here.

AcceptIn

namestring | null

Account

idstring

namestring | null

fcraStatusenum

not_appliedpendingenabled

certifiedPurposesarray of string

versionstring

controlsVersionstring

planstring | null

limitsobject

authenum

keysession

rolestring | null

userobject | null

3 fields

idstring

emailstring

namestring | null

AccountPatch

namestring | null

AccountUpdated

idstring

namestring

planstring | null

fcraStatusstring

AccuracyOutcome

outcomestringrequired

pattern ^(correct|wrong_verified|wrong_discrepancy|wrong_other)$

notesstring | null

AdverseIn

reasonSummarystring | null

deliverToEmailstring | null

ApiKey

idstring

namestring

modeenum

livetest

prefixstring

createdAtstring (date-time)

lastUsedAtstring (date-time) | null

revokedAtstring (date-time) | null

ApiKeyCreated

idstring

namestring

modeenum

livetest

prefixstring

createdAtstring (date-time)

lastUsedAtstring (date-time) | null

revokedAtstring (date-time) | null

keystringrequired

The full key. Shown once.

ApproveIn

certifiedPurposesarray of string | null

adverseActionWaitDaysinteger | null

CertificationClaim

claimIdstring | null

type"certification"

issuerstringrequired

credentialIdstring | null

ChannelUsage

countinteger

spendCentsinteger

ChecklistIn

itemstringrequired

doneboolean

notestring | null

ClaimResult

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

items: 11 fields

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

items: 5 fields

fieldstringrequired

claimedany

foundany

matchboolean | null

notestring | null

evidencearray of Evidence

items: 8 fields

idstring | null

kindenumrequired

api_responsepage_capturedataset_rowdocumentrendered_recordoutreach_logcall_transcriptpartner_response

sourceCodestringrequired

sourceUrlstring | null

capturedAtstring (date-time)

sha256string | null

contentany | null

refstring | null

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

partsarray of ClaimResult

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

items: 11 fields

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

items: 5 fields

fieldstringrequired

claimedany

foundany

matchboolean | null

notestring | null

evidencearray of Evidence

items: 8 fields

idstring | null

kindenumrequired

api_responsepage_capturedataset_rowdocumentrendered_recordoutreach_logcall_transcriptpartner_response

sourceCodestringrequired

sourceUrlstring | null

capturedAtstring (date-time)

sha256string | null

contentany | null

refstring | null

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

partsarray of ClaimResult

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

items: 11 fields

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

evidencearray of Evidence

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

partsarray of ClaimResult

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

partsarray of ClaimResult

ConnectorResult

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

items: 5 fields

fieldstringrequired

claimedany

foundany

matchboolean | null

notestring | null

evidencearray of Evidence

items: 8 fields

idstring | null

kindenumrequired

api_responsepage_capturedataset_rowdocumentrendered_recordoutreach_logcall_transcriptpartner_response

sourceCodestringrequired

sourceUrlstring | null

capturedAtstring (date-time)

sha256string | null

contentany | null

refstring | null

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

ConsentIn

personobjectrequired

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

purposeenum

employmentcurrent_staff_monitoringnetwork_credentialing

customerNamestring | null

Shown on the hosted page as the party ordering the report.

statestring | null

Consumer's state for state-specific disclosure add-ons (CA, NY, …).

ConsentRecord

idstring

objectenum

consent

statusenum

pendingsignedexpired

purposestring

personobject

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

disclosureVersionstring

stateAddonsarray of string

urlstring | null

Hosted consent page; null once signed.

signedAtstring (date-time) | null

signerIpstring | null

evidenceIdstring | null

expiresAtstring (date-time) | null

createdAtstring (date-time)

CoverageRow

statestring

professionstring

labelstring

boardstring

boardTypestring

sourcestring | null

statusenum

livedegradedbuildingblocked

searchByarray of string

fieldsarray of string

compactstring | null

lookupUrlstring | null

Deleted

idstring

deletedenum

true

DenyIn

reasonstringrequired

DisputeIn

verificationIdstringrequired

claimIndexinteger | null

statementstringrequired

documentsarray of object

EducationClaim

claimIdstring | null

type"education"

schoolstringrequired

schoolStatestring | null

degreestring | null

majorstring | null

graduatedYearinteger | null

attendedFromstring | null

attendedTostring | null

EmploymentClaim

claimIdstring | null

type"employment"

employerstringrequired

employerCitystring | null

employerStatestring | null

startstring | null

endstring | null

suppliedContactPhonestring | null

suppliedContactEmailstring | null

Error

errorobjectrequired

6 fields

typeenumrequired

authenticationpermissioninvalid_requestfcrarate_limit_errorconflictnot_foundapi_error

codestringrequired

messagestringrequired

paramstring | null

requestIdstring

docUrlstring

Evidence

idstring | null

kindenumrequired

api_responsepage_capturedataset_rowdocumentrendered_recordoutreach_logcall_transcriptpartner_response

sourceCodestringrequired

sourceUrlstring | null

capturedAtstring (date-time)

sha256string | null

contentany | null

refstring | null

EvidenceIndexRow

idstring | null

claimIndexinteger

sourcestring

kindstring

sha256string | null

capturedAtstring (date-time)

sourceUrlstring | null

refstring | null

inlineboolean

indexinteger

EvidenceObject

idstring

objectenum

evidence

verificationIdstring

sourceCodestring

kindenum

api_responsepage_capturedataset_rowdocumentrendered_recordoutreach_logcall_transcriptpartner_response

sourceUrlstring | null

contentTypestring

sha256string

bytesinteger

capturedAtstring (date-time)

urlstring

Signed download URL; no API key needed.

expiresAtstring (date-time)

ExchangeIn

tokenstringrequired

ExclusionScreenNot a claim the person makes; a screen the customer asks for (healthcare bundle).

claimIdstring | null

type"exclusion_screen"

npistring | null

FcraApplication

legalNamestringrequired

einstringrequired

pattern ^\d{2}-?\d{7}$

addressstringrequired

websitestringrequired

pattern ^https?://

natureOfBusinessstringrequired

intendedPurposesarray of stringrequired

expectedMonthlyVolumeintegerrequired

signerNamestringrequired

signerTitlestringrequired

agreementAcceptedbooleanrequired

agreementVersionstringrequired

certificationsobject

FieldCheck

fieldstringrequired

claimedany

foundany

matchboolean | null

notestring | null

FileRequest

firstNamestringrequired

lastNamestringrequired

dobstringrequired

pattern ^\d{4}-\d{2}-\d{2}$

emailstringrequired

pattern ^[^@\s]+@[^@\s]+\.[^@\s]+$

last4string | null

verificationIdstring | null

Health

okboolean

controlsstring

versionstring

HealthcareScreenClaimBundle: expands server-side into license + npi + exclusion_screen (docs/CHECK-TYPES.md §E).

claimIdstring | null

type"healthcare_screen"

statestringrequired

professionstringrequired

licenseNumberstring | null

npistring | null

pattern ^\d{10}$

InboundEmail

jobIdstring | null

tostring | null

fromstring | null

subjectstring | null

textstring

InboundFax

jobIdstring | null

fromNumberstring | null

documentUrlstring | null

pagesinteger | null

InboundPayroll

event_typestring | null

tracking_infostring | null

payloadobject

InboundVoice

jobIdstringrequired

transcriptstring

outcomestring | null

recordingUrlstring | null

Invite

idstring

emailstring

rolestring

expiresAtstring (date-time)

acceptUrlstring

Non-production only.

InviteIn

emailstringrequired

rolestring

KeyIn

namestringrequired

modestringrequired

pattern ^(live|test)$

LicenseClaim

claimIdstring | null

type"license"

statestringrequired

professionstringrequired

numberstring | null

deaNumberstring | null

MagicLinkRequested

sentenum

true

Member

idstring

userIdstring

emailstring

namestring | null

roleenum

owneradminmemberviewerops

createdAtstring (date-time)

Monitor

idstring

objectenum

monitor

statusenum

activestopped

cadenceenum

dailyweeklymonthly

personobject

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimobject

The claim exactly as sent.

snapshotobject | null

verdict, reason, watched record fields, actions count, checkedAt

lastCheckedAtstring (date-time) | null

nextCheckAtstring (date-time) | null

createdAtstring (date-time)

stoppedAtstring (date-time) | null

MonitorEvent

idstring

kindenum

verdictstatusexpiresactionrecord

diffobject

webhookEventIdstring | null

createdAtstring (date-time)

MonitorIn

personobjectrequired

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimone ofrequired

one of 7 shapes

LicenseClaim

claimIdstring | null

type"license"

statestringrequired

professionstringrequired

numberstring | null

deaNumberstring | null

NpiClaim

claimIdstring | null

type"npi"

numberstringrequired

pattern ^\d{10}$

ExclusionScreen

claimIdstring | null

type"exclusion_screen"

npistring | null

HealthcareScreenClaim

claimIdstring | null

type"healthcare_screen"

statestringrequired

professionstringrequired

licenseNumberstring | null

npistring | null

pattern ^\d{10}$

CertificationClaim

claimIdstring | null

type"certification"

issuerstringrequired

credentialIdstring | null

EducationClaim

claimIdstring | null

type"education"

schoolstringrequired

schoolStatestring | null

degreestring | null

majorstring | null

graduatedYearinteger | null

attendedFromstring | null

attendedTostring | null

EmploymentClaim

claimIdstring | null

type"employment"

employerstringrequired

employerCitystring | null

employerStatestring | null

startstring | null

endstring | null

suppliedContactPhonestring | null

suppliedContactEmailstring | null

cadenceenum

dailyweeklymonthly

consentConsent | null

Required on live accounts (consentId, or disclosureVersion + signedAt).

see Consent

MonitorStopped

idstring

statusenum

stopped

MoreInfo

statementstringrequired

documentsarray of object

NoticesAccept

acceptedBystringrequired

NpiClaim

claimIdstring | null

type"npi"

numberstringrequired

pattern ^\d{10}$

Person

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

Profession

keystring

labelstring

categorystring

boardTypestring

compactstring | null

Purpose

enum: employmentcurrent_staff_monitoringnetwork_credentialing

Queued

idstring

queuedenum

true

Reason

enum: no_coveragesource_errorsource_timeoutemployer_policyemployer_uses_third_partyemployer_closedemployer_not_foundno_responseinsufficient_identifiersambiguous_matchsource_not_builtsource_stalesource_degradedcancelled

ReplyIn

responderNamestringrequired

responderRolestring | null

confirmedbooleanrequired

startstring | null

endstring | null

degreestring | null

graduatedYearinteger | null

notesstring | null

refusedboolean

thirdPartystring | null

Resolve

outcomestringrequired

answerobject | null

thirdPartystring | null

notestring | null

operatorstringrequired

ResolveIn

outcomestringrequired

notesstring | null

RolePatch

rolestringrequired

Session

sessionTokenstring

userobject

3 fields

idstring

emailstring

namestring | null

accountobject

5 fields

idstring

namestring

planstring | null

fcraStatusstring

isStaffboolean

roleenum

owneradminmemberviewerops

expiresAtstring (date-time)

SessionIn

emailstringrequired

SignupIn

emailstringrequired

namestringrequired

companystringrequired

SignupResult

accountobject

2 fields

idstring

namestring

userobject

3 fields

idstring

emailstring

namestring | null

loginUrlstring

Non-production only.

Source

codestring

namestring

claimTypesarray of string

modestring

rolestring

statusstring

rungstring | null

lastCanaryAtstring (date-time) | null

lastCanaryOkboolean | null

errorRate24hnumber | null

calls24hinteger

dataAsOfstring (date-time) | null

datasetFreshboolean | null

datasetsarray of object

items: 4 fields

codestring

dataAsOfstring (date-time) | null

rowsinteger

maxAgeDaysinteger

SourcePatch

statusstring | null

concurrencyinteger | null

ratePerSnumber | null

notesstring | null

reasonstring | null

SourceStatus

enum: okerrortimeoutno_coveragependingnot_built

Usage

fromstring (date-time)

tostring (date-time)

groupByenum

daytype

countsobject

Claims by type (license, healthcare_screen, …, monitor).

spendCentsinteger

byChannelobject

2 fields

apiobject

2 fields

countinteger

spendCentsinteger

dashboardobject

2 fields

countinteger

spendCentsinteger

seriesarray of object

items: 4 fields

datestring

YYYY-MM-DD when groupBy=day

typestring

claim type when groupBy=type

countinteger

spendCentsinteger

Verdict

enum: verifieddiscrepancynot_foundunable_to_verifypending

Verification

idstringrequired

statusenumrequired

pendingcompletecancelled

purposeenumrequired

employmentcurrent_staff_monitoringnetwork_credentialing

see Purpose

personobjectrequired

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimsarray of ClaimResultrequired

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

items: 11 fields

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

items: 5 fields

fieldstringrequired

claimedany

foundany

matchboolean | null

notestring | null

evidencearray of Evidence

items: 8 fields

idstring | null

kindenumrequired

api_responsepage_capturedataset_rowdocumentrendered_recordoutreach_logcall_transcriptpartner_response

sourceCodestringrequired

sourceUrlstring | null

capturedAtstring (date-time)

sha256string | null

contentany | null

refstring | null

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

partsarray of ClaimResult

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

items: 11 fields

sourceCodestringrequired

statusenumrequired

okerrortimeoutno_coveragependingnot_built

see SourceStatus

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

fieldChecksarray of FieldCheck

evidencearray of Evidence

recordobject | null

checkedAtstring (date-time)

dataAsOfstring (date-time) | null

jobIdstring | null

reusedFromstring | null

partsarray of ClaimResult

items: 8 fields

claimIndexintegerrequired

claimIdstring | null

typestringrequired

verdictenumrequired

verifieddiscrepancynot_foundunable_to_verifypending

see Verdict

reasonReason | null

see Reason

inputobject | null

resultsarray of ConnectorResult

partsarray of ClaimResult

createdAtstring (date-time)

completedAtstring (date-time) | null

referencestring | null

metadataobject

allowPaidThirdPartyboolean

maxAgestring | null

VerificationOptions`options` on create (docs/API-V1.md). `maxAge`: ISO-8601 duration; accept a result we produced for the same claim + person within this window (docs/MASTER-PLAN.md §4 result reuse). Default PT0S = always live.

maxAgestring | null

ISO-8601 duration; reuse a result we produced within this window. Default PT0S.

allowPaidThirdPartyboolean | null

Route to The Work Number when an employer redirects there.

deadlinestring | null

ISO-8601 duration for employer/registrar outreach (default P7D).

VerificationRequest

personobjectrequired

8 fields

firstNamestringrequired

middleNamestring | null

lastNamestringrequired

suffixstring | null

dobstring (date) | null

aliasesarray of string

emailstring | null

phonestring | null

claimsarray of one ofrequired

items: one of 7 shapes

LicenseClaim

claimIdstring | null

type"license"

statestringrequired

professionstringrequired

numberstring | null

deaNumberstring | null

NpiClaim

claimIdstring | null

type"npi"

numberstringrequired

pattern ^\d{10}$

ExclusionScreen

claimIdstring | null

type"exclusion_screen"

npistring | null

HealthcareScreenClaim

claimIdstring | null

type"healthcare_screen"

statestringrequired

professionstringrequired

licenseNumberstring | null

npistring | null

pattern ^\d{10}$

CertificationClaim

claimIdstring | null

type"certification"

issuerstringrequired

credentialIdstring | null

EducationClaim

claimIdstring | null

type"education"

schoolstringrequired

schoolStatestring | null

degreestring | null

majorstring | null

graduatedYearinteger | null

attendedFromstring | null

attendedTostring | null

EmploymentClaim

claimIdstring | null

type"employment"

employerstringrequired

employerCitystring | null

employerStatestring | null

startstring | null

endstring | null

suppliedContactPhonestring | null

suppliedContactEmailstring | null

purposeenumrequired

employmentcurrent_staff_monitoringnetwork_credentialing

see Purpose

consentConsent | null

see Consent

optionsVerificationOptions | null

maxAge (ISO-8601 duration, default PT0S = always live), allowPaidThirdParty, deadline.

see VerificationOptions

allowPaidThirdPartybooleandeprecated

Deprecated top-level alias of options.allowPaidThirdParty; options wins when both are sent.

maxAgestring | nulldeprecated

Deprecated top-level alias of options.maxAge; options wins when both are sent.

referencestring | null

metadataobject

WebhookDelivery

idstring

eventIdstring

eventTypestring

attemptinteger

statusCodeinteger | null

responseMsinteger | null

deliveredAtstring (date-time) | null

nextRetryAtstring (date-time) | null

createdAtstring (date-time)

WebhookEndpoint

idstringrequired

objectenum

webhook_endpoint

urlstringrequired

eventsarray of stringrequired

modeenum

livetest

statusstring

createdAtstring (date-time)

WebhookEndpointCreated

idstringrequired

objectenum

webhook_endpoint

urlstringrequired

eventsarray of stringrequired

modeenum

livetest

statusstring

createdAtstring (date-time)

secretstringrequired

Shown once. HMAC key for PrimaryCheck-Signature.

WebhookEndpointIn

urlstringrequired

pattern ^https?://

eventsarray of enumrequired