FCRA Partner API · v1.0.0 · approved partners

Access & end users

How access is switched on, the permissible purposes, and registering your end users.

Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.app

FCRA Partner Access

The FCRA API has no plan or key setting that turns it on. You apply; our team reviews the application and enables the account after the written FCRA agreement is signed, with the permissible purposes it names and the mode you asked for. Trial accounts cannot use it. Every call is authenticated with the same X-API-Key header as the other APIs.

Without access, every /v1/fcra/* call except GET /v1/fcra/partner, the application routes and the public receipt returns 403 fcra_not_enabled; an account that has access but is still on a trial gets 403 fcra_not_on_trial. GET /v1/fcra/partner never returns 403: it reports enabled: false (with trial: true on a trial account, and your application’s status) so your integration can tell.

FCRA Partner Access status API — GET /v1/fcra/partner

GET/v1/fcra/partnerAuth: X-API-Key

Whether this account can place FCRA orders, the purposes its agreement covers, and whether a webhook endpoint is set. Never 403: an account without access gets enabled: false.

Request

No parameters and no body beyond the X-API-Key header.

Response

200 · application/json

The account's FCRA status.

FieldTypeDescription
enabled
booleantrue when this account can place FCRA orders now: an active FCRA partner agreement and not a trial account. false otherwise — show the request-access path.
sandbox
booleantrue when the partner account is in sandbox: orders return deterministic test answers, make no live calls and are never metered. false without access.
allowedPurposes
array of string
one of "employment", "tenant_screening", "consumer_written_instructions", "legitimate_business_need"
The permissible purposes your partner agreement covers. An end user and an order may use only these. [] without access.
agreementRef
string or nullThe reference of your signed partner agreement. null without access.
enabledAt
string (date-time) or nullWhen FCRA Partner Access was enabled for this account. null without access.
webhookConfigured
booleantrue when a webhook endpoint is set with PUT /v1/fcra/webhook-endpoint.
trial
booleantrue on a trial account. FCRA orders are not available on a trial account.
role
string
one of "admin", "user"
Who is calling: admin for an API key and for an account admin's dashboard session, user for a team member's session. Only admin can change the webhook endpoint.
kind
string or null
one of "cra", "direct", "platform"
cra, direct or platform (see hosted consent). null when not a partner.
branding
Branding or nullYour branding, when set.
agencyLegalName
stringThe consumer reporting agency named on every disclosure.
Example "OffenderSearch LLC"
application
object or nullYour latest partner application, in brief.
application.id
stringThe application's id (app_…).
application.status
string
one of "received", "approved", "declined"
received while we review it, then approved or declined.
application.kind
string
one of "cra", "direct", "platform"
The way you asked to use the FCRA API: cra (you are the CRA), direct (we are your CRA) or platform (we are the CRA for your clients, under your brand).
application.submittedAt
string (date-time)When the application was submitted.
application.decidedAt
string (date-time) or nullWhen it was approved or declined. null while it is still under review.
Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).

Three modes

ModeWho you areWho prepares the reportWhat you get
directAn employer, landlord or organization screening for itselfWe are the consumer reporting agencyHosted consent, notices, adverse action, continuous checks — the full service
platformA platform, staffing firm or property manager screening for its clientsWe are the consumer reporting agency; your clients are end users; your branding is on the consumer-facing surfacesEverything direct gets, for every client you register
craA consumer reporting agencyYou areThe records, the controls, the evidence, the signed report and the dispute channel; consent and notices stay with you

Apply for access

POST /v1/fcra/application takes your company, your compliance contact, the purposes and mode you ask for, and the certifications every partner makes, signed with a name and title. GET /v1/fcra/application/form lists the certifications and modes. One application can be under review at a time; a declined application may be followed by another. The same form is in the dashboard under FCRA → Settings.

What the partner application asks for — GET /v1/fcra/application/form

GET/v1/fcra/application/formAuth: X-API-Key

Request

Response

200 · application/json

The body is the ApplicationForm object. What the application asks: the certifications to make, the modes, the agreement version, and the agency you are contracting with.

Errors
StatusCodeWhen
401—No valid X-API-Key or session.

The ApplicationForm object

What the application asks: the certifications to make, the modes, the agreement version, and the agency you are contracting with.

Returned or accepted by GET /v1/fcra/application/form.

FieldTypeDescription
agreementVersion
stringThe version of the partner agreement an application signs today. Send it back in ApplicationCreate.
agency
objectWho the applicant is contracting with.
agency.legalName
stringOur legal name as it appears on the agreement.
agency.email
stringWhere to reach us about the application.
certifications
array of objectThe certifications the signer must accept, in order.
certifications[].id
stringThe certification's id, the key to send in ApplicationCreate.certifications.
certifications[].text
stringThe certification's full text.
kinds
array of objectThe ways of using the FCRA API an applicant can choose from.
kinds[].id
stringdirect, platform or cra.
kinds[].label
stringThe way, in plain words.

Apply for FCRA Partner Access — POST /v1/fcra/application

POST/v1/fcra/applicationAuth: X-API-Key

Any account may apply. Our team reviews it; approval enables the account with the purposes and mode requested, and GET /v1/fcra/partner reports it.

Request

Body · application/json
FieldTypeDescription
kind
required
string
one of "direct", "platform", "cra"
direct (you screen for yourself), platform (you screen for your clients under your brand) or cra (you are a consumer reporting agency wanting the data).
company
required
CompanyWho is applying.
compliance
required
ComplianceThe compliance contact and how the reports will be used.
purposes
required
array of string
one of "employment", "tenant_screening", "consumer_written_instructions", "legitimate_business_need"
The purposes you ask for.
endUserTypes
optional
array of string or null
one of "employers", "landlords", "volunteer_organizations", "gig_platforms", "healthcare_facilities", "staffing_firms", "other"
Who the reports are for.
certifications
required
objectEvery certification id from the form, each true.
signerName
required
stringThe name of the officer signing the certifications.
signerTitle
required
stringTheir title, for example Chief Compliance Officer.

Response

201 · application/json

The application, received.

The body is the Application object. Your partner application and its decision.

Errors
StatusCodeWhen
401—No valid X-API-Key or session.
409already_enabledThe account already has access.
409application_pendingOne is already under review.
422—A certification is missing or a field failed validation.

The Company object

Who is applying, as the credentialing review needs it.

Returned or accepted by POST /v1/fcra/application, GET /v1/fcra/application.

FieldTypeDescription
legalName
required
stringThe applicant's legal name as registered.
Example "Applicant Co LLC"
dba
optional
string or nullTrading name, when different. null otherwise.
ein
required
stringNine digits, any punctuation.
Example "12-3456789"
stateOfIncorporation
required
stringTwo-letter state the company is registered in.
Example "TX"
incorporationType
required
string
one of "llc", "corporation", "s_corporation", "partnership", "llp", "sole_proprietor", "non_profit", "government", "other"
llc, corporation, s_corporation, partnership, llp, sole_proprietor, non_profit, government or other.
address
required
objectline1, line2, city, state, postalCode, country.
website
optional
string or nullThe company's website. null when none.
phone
optional
string or nullA main phone number. null when none.
yearsInBusiness
optional
integer or nullHow long the company has operated, in whole years. null when not given.

The Compliance object

Your compliance contact and how you will use reports.

Returned or accepted by POST /v1/fcra/application, GET /v1/fcra/application.

FieldTypeDescription
contactName
required
stringWho answers compliance questions.
contactEmail
required
stringThe e-mail of the person responsible for FCRA compliance at the applicant.
contactPhone
optional
string or nullThat person's phone. null when none.
isConsumerReportingAgency
optional · default false
booleantrue when the applicant is itself a consumer reporting agency (the cra way of using the API).
resellsToEndUsers
optional · default false
booleanWhether you furnish reports to end users of your own (a platform or a CRA).
expectedMonthlyOrders
optional
integer or nullHow many orders a month the applicant expects. null when unknown.
description
optional
string or nullWhat you screen and why.

The Application object

Your partner application and its decision.

Returned or accepted by POST /v1/fcra/application, GET /v1/fcra/application.

FieldTypeDescription
id
stringThe application's id (app_…).
Example "fpa_3c9d1e2f4a5b6c7d"
status
string
one of "received", "approved", "declined"
received while under review, then approved or declined.
kind
string
one of "direct", "platform", "cra"
direct, platform or cra: the way the applicant will use the FCRA API.
company
CompanyThe company details as submitted (the EIN is withheld).
compliance
Compliance or nullThe compliance details as submitted. null when withheld.
purposes
array of stringThe permissible purposes the applicant certified it will use.
endUserTypes
array of stringWho the applicant's end users are, for example employers or landlords.
certifications
objectEach certification id and whether it was accepted (all must be true).
signerName
stringName and title, as signed.
signedAt
string (date-time)When the applicant signed.
agreementVersion
stringThe version of the partner agreement that was signed.
decidedAt
string (date-time) or nullWhen it was approved or declined. null while under review.
decisionNotes
string or nullA note from us about the decision, when there is one. null otherwise.
agreementRef
string or nullThe agreement reference, once approved.
createdAt
string (date-time)When the application was received.
updatedAt
string (date-time)When it last changed.

Your latest partner application — GET /v1/fcra/application

GET/v1/fcra/applicationAuth: X-API-Key

Request

Response

200 · application/json

FieldTypeDescription
application
Application or null
enabled
booleanWhether the account has access today.
Errors
StatusCodeWhen
401—No valid X-API-Key or session.

Permissible purposes

PurposeMeaning
employmentEmployment purposes, with your end user’s § 1681b(b) certifications in place.
tenant_screeningA rental application the consumer initiated.
consumer_written_instructionsThe consumer’s written instructions (§ 1681b(a)(2)).
legitimate_business_needAnother business transaction the consumer initiated.

An end user may hold only purposes your agreement allows, and an order may state only a purpose its end user holds and your agreement still allows.

End users

An end user is the employer, landlord or other business the report is for. Register each one once, with your certification that it holds the stated purposes, and reference it by id on every order.

POST /v1/fcra/end-users
curl -X POST https://api.offendersearch.app/v1/fcra/end-users \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northwind Staffing LLC",
    "externalId": "EU-4821",
    "permissiblePurposes": ["employment"],
    "certification": {
      "text": "End user certifies it will use reports only for employment purposes …",
      "version": "v3",
      "certifiedAt": "2026-10-02T14:00:00Z",
      "certifiedBy": "compliance@your-cra.example"
    }
  }'

GET /v1/fcra/end-users lists them; GET /v1/fcra/end-users/{id} returns one; PATCH /v1/fcra/end-users/{id} changes its purposes, or sets status to suspended or back to active. A suspended end user cannot be used on a new order (422 end_user_suspended). Every field each of these calls takes and returns is in the end user API reference below.

Register an FCRA end user — POST /v1/fcra/end-users request and response

POST/v1/fcra/end-usersAuth: X-API-Key

Registers the employer, landlord or other business a report is for, once, with the permissible purposes it holds and your certification.

Request

Body · application/json
FieldTypeDescription
name
required
stringThe end user's legal name, 1 to 200 characters.
externalId
optional
string or nullYour own id for the end user, up to 200 characters. Returned as sent.
address
optional
Address or nullThe end user's business address.
permissiblePurposes
required
array of string
one of "employment", "tenant_screening", "consumer_written_instructions", "legitimate_business_need"
One or more purposes the end user holds, every one within your partner agreement — otherwise 403 fcra_purpose_not_allowed.
certification
required
CertificationYour record of the end user's certification.
scopePolicy
optional
ScopePolicy or nullThe end user's search-scope policy; the default for every order placed for it.

Response

201 · application/json

The end user, status active.

The body is the EndUser object. An employer, landlord or other business your orders are for. Every order names one by id.

Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA orders are not available on a trial account.
403fcra_purpose_not_allowedA purpose is not covered by your partner agreement.
422—A field failed validation (the standard validation body).

The EndUser object — FCRA end user fields

An employer, landlord or other business your orders are for. Every order names one by id.

Returned or accepted by POST /v1/fcra/end-users, GET /v1/fcra/end-users, GET /v1/fcra/end-users/{end_user_id}, PATCH /v1/fcra/end-users/{end_user_id}.

FieldTypeDescription
id
stringThe end user's id. Send it as endUserId on every order for this business.
Example "eu_0b44acbeefeaa7d7"
name
stringThe end user's legal name.
externalId
string or nullYour own id for the end user. null when you did not send one.
address
Address or nullThe business address. null when you did not send one.
permissiblePurposes
array of string
one of "employment", "tenant_screening", "consumer_written_instructions", "legitimate_business_need"
The purposes this end user holds. An order may state only one of these.
certification
CertificationThe certification you recorded.
status
string
one of "active", "suspended"
active, or suspended — a suspended end user cannot be named on a new order (422 end_user_suspended).
createdAt
string (date-time)When the end user was registered.
updatedAt
string (date-time)When it last changed.
scopePolicy
ScopePolicy or nullThe end user's search-scope policy, as set. null when the defaults apply.

The Address object — end user address fields

An end user's business address. Every field is optional; state is a two-letter code and is returned upper-cased.

Returned or accepted by POST /v1/fcra/end-users, GET /v1/fcra/end-users, GET /v1/fcra/end-users/{end_user_id}, PATCH /v1/fcra/end-users/{end_user_id}.

FieldTypeDescription
line1
optional
string or nullStreet line, up to 200 characters.
city
optional
string or nullCity, up to 100 characters.
state
optional
string or nullTwo-letter state code, any case; returned upper-cased. Anything else is a 422.
postalCode
optional
string or nullPostal code, up to 20 characters.

The Certification object — end user certification fields

The certification the end user gave you that it holds the stated purposes, recorded as you hold it.

Returned or accepted by POST /v1/fcra/end-users, GET /v1/fcra/end-users, GET /v1/fcra/end-users/{end_user_id}, PATCH /v1/fcra/end-users/{end_user_id}.

FieldTypeDescription
text
required
stringThe certification as the end user gave it to you, 10 to 8,000 characters.
version
required
stringYour version label for that certification text, 1 to 50 characters.
certifiedAt
required
string (date-time)When the certification was given, ISO 8601. A time more than five minutes in the future is a 422. Returned normalised with a UTC offset.
certifiedBy
optional
string or nullWho at your company recorded it, up to 200 characters.

List FCRA end users — GET /v1/fcra/end-users response

GET/v1/fcra/end-usersAuth: X-API-Key

Every end user on this account.

Request

No parameters and no body beyond the X-API-Key header.

Response

200 · application/json

The end users.

FieldTypeDescription
endUsers
array of EndUserEvery end user on the account.
Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA orders are not available on a trial account.

Retrieve an FCRA end user — GET /v1/fcra/end-users/{end_user_id}

GET/v1/fcra/end-users/{end_user_id}Auth: X-API-Key

One end user.

Request

Path parameters
FieldTypeDescription
end_user_id
required
stringThe end user id (eu_…).
Example "eu_0b44acbeefeaa7d7"

Response

200 · application/json

The end user.

The body is the EndUser object. An employer, landlord or other business your orders are for. Every order names one by id.

Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA orders are not available on a trial account.
404not_foundNo such end user on this account.

Update or suspend an FCRA end user — PATCH /v1/fcra/end-users/{end_user_id}

PATCH/v1/fcra/end-users/{end_user_id}Auth: X-API-Key

Changes an end user's purposes, or suspends or reinstates it.

Request

Path parameters
FieldTypeDescription
end_user_id
required
stringThe end user id (eu_…).
Example "eu_0b44acbeefeaa7d7"
Body · application/json
FieldTypeDescription
permissiblePurposes
optional
array of string or null
one of "employment", "tenant_screening", "consumer_written_instructions", "legitimate_business_need"
Replaces the end user's purposes. At least one; every one within your partner agreement.
status
optional
string or null
one of "active", "suspended"
suspended stops the end user being named on new orders; active reinstates it. Existing orders are unaffected.
scopePolicy
optional
ScopePolicy or nullThe end user's search-scope policy; the default for every order placed for it. Send {} to reset it to the defaults.

Response

200 · application/json

The updated end user.

The body is the EndUser object. An employer, landlord or other business your orders are for. Every order names one by id.

Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA orders are not available on a trial account.
403fcra_purpose_not_allowedA purpose is not covered by your partner agreement.
404not_foundNo such end user on this account.

What stays with you

In cra mode, all of this. In direct and platform mode, the hosted consent flow, the consumer’s copy and the adverse-action notices are ours to run; the decision itself, and the vetting of your end users, remain yours.

  • Disclosure, authorization and consent from the consumer — you attest to it on each order, or the hosted flow collects it for you.
  • Vetting your end users and holding their certifications.
  • The decision. Adjudication and, in cra mode, the pre-adverse and adverse-action notices and the consumer’s copy of the report.

Integrating this API does not by itself make your workflow compliant. It gives you the records, the controls that ran, the evidence and the dispute channel; whether a given use is permitted, and every notice and certification around it, is governed by your agreement and your own compliance review.

Product overview