Access & end users
How access is switched on, the permissible purposes, and registering your end users.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appFCRA 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
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
The account's FCRA status.
| Field | Type | Description |
|---|---|---|
| enabled | boolean | true 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 | boolean | true 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 null | The reference of your signed partner agreement. null without access. |
| enabledAt | string (date-time) or null | When FCRA Partner Access was enabled for this account. null without access. |
| webhookConfigured | boolean | true when a webhook endpoint is set with PUT /v1/fcra/webhook-endpoint. |
| trial | boolean | true 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 null | Your branding, when set. |
| agencyLegalName | string | The consumer reporting agency named on every disclosure. Example "OffenderSearch LLC" |
| application | object or null | Your latest partner application, in brief. |
| application.id | string | The 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 null | When it was approved or declined. null while it is still under review. |
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
Three modes
| Mode | Who you are | Who prepares the report | What you get |
|---|---|---|---|
direct | An employer, landlord or organization screening for itself | We are the consumer reporting agency | Hosted consent, notices, adverse action, continuous checks — the full service |
platform | A platform, staffing firm or property manager screening for its clients | We are the consumer reporting agency; your clients are end users; your branding is on the consumer-facing surfaces | Everything direct gets, for every client you register |
cra | A consumer reporting agency | You are | The 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
Request
Response
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.
| Status | Code | When |
|---|---|---|
| 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.
| Field | Type | Description |
|---|---|---|
| agreementVersion | string | The version of the partner agreement an application signs today. Send it back in ApplicationCreate. |
| agency | object | Who the applicant is contracting with. |
| agency.legalName | string | Our legal name as it appears on the agreement. |
| agency.email | string | Where to reach us about the application. |
| certifications | array of object | The certifications the signer must accept, in order. |
| certifications[].id | string | The certification's id, the key to send in ApplicationCreate.certifications. |
| certifications[].text | string | The certification's full text. |
| kinds | array of object | The ways of using the FCRA API an applicant can choose from. |
| kinds[].id | string | direct, platform or cra. |
| kinds[].label | string | The way, in plain words. |
Apply for FCRA Partner Access — POST /v1/fcra/application
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
| Field | Type | Description |
|---|---|---|
| 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 | Company | Who is applying. |
| compliance required | Compliance | The 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 | object | Every certification id from the form, each true. |
| signerName required | string | The name of the officer signing the certifications. |
| signerTitle required | string | Their title, for example Chief Compliance Officer. |
Response
The application, received.
The body is the Application object. Your partner application and its decision.
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key or session. |
| 409 | already_enabled | The account already has access. |
| 409 | application_pending | One 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.
| Field | Type | Description |
|---|---|---|
| legalName required | string | The applicant's legal name as registered. Example "Applicant Co LLC" |
| dba optional | string or null | Trading name, when different. null otherwise. |
| ein required | string | Nine digits, any punctuation. Example "12-3456789" |
| stateOfIncorporation required | string | Two-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 | object | line1, line2, city, state, postalCode, country. |
| website optional | string or null | The company's website. null when none. |
| phone optional | string or null | A main phone number. null when none. |
| yearsInBusiness optional | integer or null | How 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.
| Field | Type | Description |
|---|---|---|
| contactName required | string | Who answers compliance questions. |
| contactEmail required | string | The e-mail of the person responsible for FCRA compliance at the applicant. |
| contactPhone optional | string or null | That person's phone. null when none. |
| isConsumerReportingAgency optional · default false | boolean | true when the applicant is itself a consumer reporting agency (the cra way of using the API). |
| resellsToEndUsers optional · default false | boolean | Whether you furnish reports to end users of your own (a platform or a CRA). |
| expectedMonthlyOrders optional | integer or null | How many orders a month the applicant expects. null when unknown. |
| description optional | string or null | What 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.
| Field | Type | Description |
|---|---|---|
| id | string | The 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 | Company | The company details as submitted (the EIN is withheld). |
| compliance | Compliance or null | The compliance details as submitted. null when withheld. |
| purposes | array of string | The permissible purposes the applicant certified it will use. |
| endUserTypes | array of string | Who the applicant's end users are, for example employers or landlords. |
| certifications | object | Each certification id and whether it was accepted (all must be true). |
| signerName | string | Name and title, as signed. |
| signedAt | string (date-time) | When the applicant signed. |
| agreementVersion | string | The version of the partner agreement that was signed. |
| decidedAt | string (date-time) or null | When it was approved or declined. null while under review. |
| decisionNotes | string or null | A note from us about the decision, when there is one. null otherwise. |
| agreementRef | string or null | The 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
Request
Response
| Field | Type | Description |
|---|---|---|
| application | Application or null | |
| enabled | boolean | Whether the account has access today. |
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key or session. |
Permissible purposes
| Purpose | Meaning |
|---|---|
employment | Employment purposes, with your end user’s § 1681b(b) certifications in place. |
tenant_screening | A rental application the consumer initiated. |
consumer_written_instructions | The consumer’s written instructions (§ 1681b(a)(2)). |
legitimate_business_need | Another 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.
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
Registers the employer, landlord or other business a report is for, once, with the permissible purposes it holds and your certification.
Request
| Field | Type | Description |
|---|---|---|
| name required | string | The end user's legal name, 1 to 200 characters. |
| externalId optional | string or null | Your own id for the end user, up to 200 characters. Returned as sent. |
| address optional | Address or null | The 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 | Certification | Your record of the end user's certification. |
| scopePolicy optional | ScopePolicy or null | The end user's search-scope policy; the default for every order placed for it. |
Response
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.
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
| 403 | fcra_purpose_not_allowed | A 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}.
| Field | Type | Description |
|---|---|---|
| id | string | The end user's id. Send it as endUserId on every order for this business.Example "eu_0b44acbeefeaa7d7" |
| name | string | The end user's legal name. |
| externalId | string or null | Your own id for the end user. null when you did not send one. |
| address | Address or null | The 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 | Certification | The 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 null | The 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}.
| Field | Type | Description |
|---|---|---|
| line1 optional | string or null | Street line, up to 200 characters. |
| city optional | string or null | City, up to 100 characters. |
| state optional | string or null | Two-letter state code, any case; returned upper-cased. Anything else is a 422. |
| postalCode optional | string or null | Postal 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}.
| Field | Type | Description |
|---|---|---|
| text required | string | The certification as the end user gave it to you, 10 to 8,000 characters. |
| version required | string | Your 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 null | Who at your company recorded it, up to 200 characters. |
List FCRA end users — GET /v1/fcra/end-users response
Every end user on this account.
Request
No parameters and no body beyond the X-API-Key header.
Response
The end users.
| Field | Type | Description |
|---|---|---|
| endUsers | array of EndUser | Every end user on the account. |
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
Retrieve an FCRA end user — GET /v1/fcra/end-users/{end_user_id}
One end user.
Request
| Field | Type | Description |
|---|---|---|
| end_user_id required | string | The end user id (eu_…).Example "eu_0b44acbeefeaa7d7" |
Response
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.
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
| 404 | not_found | No such end user on this account. |
Update or suspend an FCRA end user — PATCH /v1/fcra/end-users/{end_user_id}
Changes an end user's purposes, or suspends or reinstates it.
Request
| Field | Type | Description |
|---|---|---|
| end_user_id required | string | The end user id (eu_…).Example "eu_0b44acbeefeaa7d7" |
| Field | Type | Description |
|---|---|---|
| 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 null | The end user's search-scope policy; the default for every order placed for it. Send {} to reset it to the defaults. |
Response
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.
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
| 403 | fcra_purpose_not_allowed | A purpose is not covered by your partner agreement. |
| 404 | not_found | No 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
cramode, 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.