Hosted consent

How it works

For partners we act as the consumer reporting agency for — direct (you are the end user) and platform (you order for your own clients) — the consent step can be ours to run. You invite the consumer; we e-mail them a link in your branding; they read a summary of their rights and the standalone disclosure, the notices their state adds, give their name, date of birth, other names and address history, and sign the authorization by typing their name. Completing the flow places the order with source: "invitation" and stores the signed consent as a PDF with the order’s evidence.

• Your branding is on the page and the e-mails: your name, logo and colour. The consumer reporting agency’s legal name is on the disclosure, the authorization and the footer, because the consumer must know who prepares the report and who to dispute with.
• No Social Security number is asked for anywhere, and one sent is refused. Identity verification is coming soon; until then the order is matched on the name, the full date of birth and the addresses the consumer gives.
• The link lives seven days by default (1 to 30), with one reminder after 48 hours. A resend issues a fresh link and the previous one stops working.
• A cra partner collects consent in its own flow and places orders directly; POST /v1/fcra/invitations answers 403 managed_tier_required.

Invite a consumer

POST /v1/fcra/invitations takes the end user and purpose, what you know of the consumer (name and e-mail), the searches, and where the job or housing is — its state picks the state notices the consumer sees. The response carries applyUrl once; it never appears on a read. Set sendEmail: false to present the link yourself inside your own product; we then send nothing. liveScope (relevant, all, or matches once enabled for your account — see Orders) is carried onto the order the consumer’s signature places; asking for matches before it is enabled is refused 422 live_scope_not_enabled.

curl -X POST "https://api.offendersearch.app/v1/fcra/invitations" \
  -H "X-API-Key: $OFFENDERSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endUserId": "eu_0b44acbeefeaa7d7",
    "permissiblePurpose": "employment",
    "subject": { "firstName": "Jordan", "lastName": "Rivera", "email": "jordan@example.test" },
    "searches": [{ "type": "sex_offender" }, { "type": "criminal" }],
    "useLocation": { "state": "CA", "city": "Fresno" },
    "clientReference": "req-2026-1187",
    "expiresInDays": 7
  }'

The InviteSubject object — who you are inviting

What you know about the consumer. They confirm their name and give their date of birth, other names and address history in the flow. No Social Security number is asked for, here or there.

Returned or accepted by POST /v1/fcra/invitations, GET /v1/fcra/invitations, GET /v1/fcra/invitations/{invitation_id}, DELETE /v1/fcra/invitations/{invitation_id}, POST /v1/fcra/invitations/{invitation_id}/resend.

The Invitation object

An invitation to the hosted consent flow and what came of it. applyUrl is present on the create and resend responses only.

Returned or accepted by POST /v1/fcra/invitations, GET /v1/fcra/invitations, GET /v1/fcra/invitations/{invitation_id}, DELETE /v1/fcra/invitations/{invitation_id}, POST /v1/fcra/invitations/{invitation_id}/resend.

What the consumer sees

The apply page is at the link. It is public, rate-limited, and shows exactly what GET /v1/apply/{token} returns: who is asking, who prepares the report, every form in reading order, and the prefilled name. The page is ours to host; a platform that wants the flow inside its own product calls the same three routes from its own pages.

1. Summary of rights and the standalone disclosure — each acknowledged.
2. State notices for the use location (California, New York, Washington, Minnesota, Oklahoma, Maine, Massachusetts, New Jersey today) and the offer of a free copy of the report.
3. Their details: legal name, date of birth, other names used, where they have lived in the last seven years (a ZIP is enough to place the county), and how to reach them.
4. The authorization, signed by typing their full name. The signature must match the name entered.

The ApplyView object — the hosted flow as the consumer sees it

Everything the apply page renders: who is asking, who prepares the report, the forms, and the prefilled name. Never an order id or an access code.

Returned or accepted by GET /v1/apply/{token}.

The ApplyForm object — one text the consumer reads

A form in the hosted flow: the summary of rights, the standalone disclosure, a state notice, or the authorization.

Returned or accepted by GET /v1/apply/{token}.

The Agency object — the consumer reporting agency

Who prepares the report: the legal name and contact that appear on the disclosure, the report and every notice, whatever the branding.

Returned or accepted by GET /v1/consumer/portal/report, GET /v1/fcra/branding, PUT /v1/fcra/branding, GET /v1/apply/{token}.

The ApplySubject object

The consumer's identity details. No Social Security number field exists; one sent is refused.

Returned or accepted by POST /v1/apply/{token}/complete.

The ApplyAddress object

One address the consumer has lived at. Everything they type is a declared address.

Returned or accepted by POST /v1/apply/{token}/complete.

The ApplyAlias object

Another name the consumer has used.

Returned or accepted by POST /v1/apply/{token}/complete.

The ApplyContact object

Where the consumer's notices go.

Returned or accepted by POST /v1/apply/{token}/complete.

The ApplyResult object

What the consumer is told after signing. Nothing about the order.

Returned or accepted by POST /v1/apply/{token}/complete.

Consent documents

The hosted flow generates a PDF of everything the consumer read and signed — each text with its version, each acknowledgement, the typed signature, the time, the IP address and browser — and stores it with the order. For an order you place through the API you can attach the consent you collected yourself. Every document is listed with its SHA-256 and downloadable byte for byte.

The ConsentDocument object

A signed disclosure and authorization behind an order: generated by the hosted flow, or uploaded by you for an API order. Kept with the order's evidence.

Returned or accepted by GET /v1/fcra/orders/{order_id}/consent-documents, POST /v1/fcra/orders/{order_id}/consent-documents.

Notices

Every e-mail we send a consumer is recorded before it is sent — the kind, the recipient, the subject, the template version — and updated with the provider’s answer. GET /v1/fcra/invitations/{id}/notices lists them. With no mail provider configured a notice is recorded as skipped, the flow continues, and the dashboard shows the message as not sent.

The Notice object — a message we sent the consumer

One consumer-facing e-mail: what kind, to whom, and whether the provider took it. Bodies are not stored; the template version says what was said.

Returned or accepted by GET /v1/fcra/invitations/{invitation_id}/notices, GET /v1/fcra/adverse-actions/{aa_id}/notices, GET /v1/fcra/orders/{order_id}/notices.

Test FCRA orders on the sandbox server

With a test key (os_test_…) every account is a sandbox FCRA partner on the sandbox server, with the same last-name rules. Register an end user, then place orders against it; nothing is billed. An order finishes right after the 202: read it once with GET /v1/fcra/orders/{orderId}.

Base URL

https://sandbox.offendersearch.app Not https://api.offendersearch.app, which takes live keys only.

Test key

In the dashboard, Developers → API keys → Create test key. Test keys begin os_test_; send yours in the X-API-Key header.

curl -X POST "https://sandbox.offendersearch.app/v1/fcra/end-users" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "Sample Staffing LLC",
      "permissiblePurposes": [
        "employment"
      ],
      "certification": {
        "text": "End user certifies it will use reports only for employment purposes.",
        "version": "v1",
        "certifiedAt": "2026-10-01T12:00:00Z"
      }
    }'

curl -X POST "https://sandbox.offendersearch.app/v1/fcra/orders" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "endUserId": "{endUserId}",
      "permissiblePurpose": "employment",
      "consent": {
        "obtainedAt": "2026-10-01T12:00:00Z",
        "method": "esign"
      },
      "subject": {
        "firstName": "Pat",
        "lastName": "Records",
        "dob": "1980-01-01"
      },
      "searches": [
        {
          "type": "sex_offender"
        },
        {
          "type": "criminal"
        }
      ]
    }'

Try it here

Pick a scenario, edit the request, and run it against the sandbox from this page. The explorer accepts os_test_ keys only and never reaches the live host, so nothing here is billed; the “production” code it copies is for your own backend with a live key.

curl -X POST https://sandbox.offendersearch.app/v1/fcra/end-users \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sample Staffing LLC", "permissiblePurposes": [ "employment" ], "certification": { "text": "End user certifies it will use reports only for employment purposes.", "version": "v1", "certifiedAt": "2026-10-01T12:00:00Z" } }'

Every test name: FCRA API sandbox orders·Postman collection·FCRA API sandbox