The consumer portal
The access code on every order, what the consumer sees, and how their disputes reach you.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appAn access code on every order
Every order has consumerPortal.url and consumerPortal.accessCode. Put both in the consumer’s copy of the report or your pre-adverse notice. With the code, their last name and their date of birth, the consumer can see exactly what we furnished about them in that order and dispute any item — without contacting you first.
What the consumer sees
- The date of the order, the screening company that placed it, the business it was for, and the stated purpose.
- Every record furnished in that order, as a plain-language summary — for a registry record, the registry, the registration status when listed, and each offense; for a criminal record, where it is held, the case number and filing date, and each charge with its disposition and date — with the name and date of birth as the record states them, and when it was re-verified. The portal API also returns the full record.
- For each search, in plain language, what was searched: the states searched live and when, any that could not be searched live, and the date the rest of the data is current to.
- A Dispute this item button on each record, and a tracker showing each dispute’s status, due date and outcome.
They never see withheld or held records, other orders, or anything not furnished in that order. The portal never asks for a Social Security number.
Identity and protection
A view opens only when the access code, last name and date of birth all match the order; the code is accepted with or without its dashes, in any case, and the last name in any case. A mismatch returns the same generic message whatever was wrong, and five failures within an hour — for one code, or from one IP address — refuse further attempts until fewer than five fall within the last hour. A session lasts 30 minutes, and a cancelled order cannot be opened.
Consumer portal session API — POST /v1/consumer/portal/session
The consumer opens their file for one order with its access code, their last name and their date of birth. Returns a token valid for 30 minutes.
Request
| Field | Type | Description |
|---|---|---|
| accessCode required | string | The order's consumerPortal.accessCode, with or without dashes, any case.Example "K7QF-2MXP-9RDA" |
| lastName required | string | The consumer's last name as on the order. Case and spacing do not matter. |
| dob required | string (date) | The consumer's full date of birth, YYYY-MM-DD. |
Response
A session token.
| Field | Type | Description |
|---|---|---|
| token | string | Send as Authorization: Bearer <token> on the other portal routes. |
| expiresAt | string (date-time) | 30 minutes from now. |
| Status | Code | When |
|---|---|---|
| 401 | not_matched | Any of the three did not match, or the order was cancelled. The message is the same whatever was wrong. |
| 429 | locked | Five failures within the last hour for this code or from this IP address. Attempts are refused until fewer than five fall within the hour. |
| 429 | rate_limited | Too many attempts in a short period. |
| 422 | — | A field failed validation (the standard validation body). |
Consumer portal report API — GET /v1/consumer/portal/report response fields
Exactly what was furnished about the consumer in this order, in plain language. Withheld records, other orders and anything not furnished are never shown.
Request
| Field | Type | Description |
|---|---|---|
| Authorization required | string | Bearer <token> from POST /v1/consumer/portal/session. |
Response
The consumer's view of the order.
| Field | Type | Description |
|---|---|---|
| order | object | The order, as the consumer sees it. |
| order.id | string | The order id. |
| order.date | string (date-time) | When the order was placed. |
| order.completedAt | string (date-time) or null | When it completed. null until then. |
| order.status | string one of "received", "in_progress", "partial", "complete", "error" | The order status. |
| order.purpose | string one of "employment", "tenant_screening", "consumer_written_instructions", "legitimate_business_need" | The stated purpose. |
| order.purposeLabel | string | The purpose in plain language, for example Employment screening. |
| order.requestedBy | string or null | Who asked for the report, as the consumer knows them: the client's branded name, else the partner's organization. |
| order.endUser | string or null | The business the report was for. |
| order.sandbox | boolean | true for a sandbox order. |
| branding | Branding or null | The client's branding, when set: the portal shows their name and logo as the requester. |
| agency | Agency | The consumer reporting agency that prepared the report and handles disputes. |
| searches | array of object | Each current search. |
| searches[].type | string one of "sex_offender", "criminal", "healthcare" | sex_offender, criminal or healthcare. |
| searches[].label | string | Sex offender registry search or Criminal records search. |
| searches[].status | string one of "queued", "in_progress", "complete", "unavailable", "error" | The search status. |
| searches[].result | string or null one of "records_found", "clear", "incomplete" | The result. null while the search is running. |
| searches[].resultLabel | string or null | The result in plain language, or This search is still running. |
| searches[].completedAt | string (date-time) or null | When the search finished. null while running. |
| searches[].coverage | object or null | What was searched, in consumer-safe form. null while the search is running. |
| searches[].coverage.searchedLive | array of object | Each source searched live, and when. |
| searches[].coverage.searchedLive[].name | string | The source's name. |
| searches[].coverage.searchedLive[].jurisdiction | string | Where it covers. |
| searches[].coverage.searchedLive[].checkedAt | string (date-time) | When it was searched. |
| searches[].coverage.searchedLive[].answered | boolean | true when it answered. |
| searches[].coverage.otherSources | object | The sources searched in our data, summarised. |
| searches[].coverage.otherSources.count | integer | How many answered. |
| searches[].coverage.otherSources.oldestDataAsOf | string (date-time) or null | The oldest dataAsOf among them. null when none carries one. |
| searches[].coverage.otherSources.newestDataAsOf | string (date-time) or null | The newest. |
| records | array of PortalRecord | Every record furnished in the order's finished searches. |
| rights | object | The consumer's rights. |
| rights.summaryUrl | string (uri) | The CFPB Summary of Your Rights Under the FCRA. |
| rights.disputeDays | integer | The reinvestigation period, in days: 30. |
| rights.supportEmail | string | Where the consumer can write to us. |
| Status | Code | When |
|---|---|---|
| 401 | no_session | No Authorization: Bearer header. |
| 401 | session_expired | The token is unknown or past 30 minutes, or the order was cancelled. |
The PortalRecord object — consumer portal record fields
One furnished record as the consumer sees it: a plain-language summary and the full record.
Returned or accepted by GET /v1/consumer/portal/report.
| Field | Type | Description |
|---|---|---|
| recordId | string | The record id. Send it in recordIds to dispute it. |
| type | string one of "sex_offender", "criminal", "healthcare" | sex_offender, criminal or healthcare. |
| title | string | Sex offender registry record or Criminal record. |
| nameOnRecord | string or null | The name as the record states it. |
| dobOnRecord | string or null | The date of birth as the record states it. |
| verifiedAt | string (date-time) or null | When the record was re-verified with the official source. |
| lines | array of string | The record in plain-language lines: for a registry record, the registry, its registration status when listed, and the offenses listed; for a criminal record, where it is held and each case and charge with its disposition and date. |
| corrected | boolean | true when a dispute corrected this record. |
| record | FurnishedRecord | The full furnished record. The consumer is entitled to everything in their file. |
How portal disputes reach you
A dispute filed in the portal is the same dispute object you would open through the API, with origin: "consumer_portal". You receive dispute.created, and every later status change as dispute.updated.
Consumer portal dispute API — POST /v1/consumer/portal/disputes
The consumer disputes records in this report. It creates the same dispute you would open through the API, with origin: "consumer_portal", and you receive dispute.created.
Request
| Field | Type | Description |
|---|---|---|
| Authorization required | string | Bearer <token> from POST /v1/consumer/portal/session. |
| Field | Type | Description |
|---|---|---|
| recordIds required | array of string | 1 to 100 record ids from this report. Any other id is 422 unknown_record. |
| reason required | string one of "not_me", "inaccurate", "incomplete", "outdated", "other" | Why the consumer disputes it. |
| statement optional | string or null | The consumer's statement, up to 8,000 characters. |
Response
The dispute.
The body is the PortalDispute object. A dispute as the consumer sees it in the portal.
| Status | Code | When |
|---|---|---|
| 401 | session_expired | The session ended. Open the report again. |
| 422 | unknown_record | A record id is not in this report. |
Consumer portal disputes list — GET /v1/consumer/portal/disputes
Every dispute on this order — the consumer's and yours — with status, due date and outcome.
Request
| Field | Type | Description |
|---|---|---|
| Authorization required | string | Bearer <token> from POST /v1/consumer/portal/session. |
Response
The disputes.
| Field | Type | Description |
|---|---|---|
| disputes | array of PortalDispute | Every dispute on this order, by dueAt. |
| Status | Code | When |
|---|---|---|
| 401 | session_expired | The session ended. Open the report again. |
The PortalDispute object — consumer portal dispute fields
A dispute as the consumer sees it in the portal.
Returned or accepted by POST /v1/consumer/portal/disputes, GET /v1/consumer/portal/disputes.
| Field | Type | Description |
|---|---|---|
| id | string | The dispute id. |
| recordIds | array of string | The disputed record ids. |
| reason | string one of "not_me", "inaccurate", "incomplete", "outdated", "other" | The reason given. |
| consumerStatement | string or null | The statement, or null. |
| receivedAt | string (date-time) | When it was received. |
| dueAt | string (date-time) | When the reinvestigation is due. |
| extendedAt | string (date-time) or null | When the 15-day extension was applied, or null. |
| status | string one of "received", "investigating", "verified", "modified", "deleted", "unable_to_verify" | The dispute status. |
| resolvedAt | string (date-time) or null | When the outcome was reached, or null. |
| changes | object or null | What changed on a modified outcome, or null. |
Without an access code
A consumer without a code can still request their file or open a dispute at /consumer. We verify their identity before disclosing anything.
Consumer file request and dispute API — POST /v1/consumer/requests
Public: a consumer without an access code requests their file or disputes information. Identity is verified separately before anything is disclosed. It is what the /consumer page sends.
Request
| Field | Type | Description |
|---|---|---|
| kind required | string one of "file", "dispute" | file — the consumer asks for their file; dispute — the consumer disputes information. A dispute is due 30 days after it is received. |
| name required | string | The consumer's name. Text past 120 characters is cut. |
| email required | string | An address we can reply to, up to 254 characters. It is checked for a valid shape only. |
| message required | string | The request, at least 10 characters; text past 4,000 characters is cut. A message containing a Social Security number is refused (422 invalid). |
| website optional | string | A form field the consumer page sends empty. Send it empty or omit it. |
| elapsedMs optional | integer | Sent by the consumer page. Omit it. |
Response
The request, recorded.
| Field | Type | Description |
|---|---|---|
| id | string | The request id (cons_…). |
| kind | string one of "file", "dispute" | As sent. |
| receivedAt | string (date-time) | When it was received. |
| dueAt | string (date-time) or null | For a dispute, 30 days after receivedAt. null for a file request. |
| supportEmail | string | Where the consumer can write to us. |
| Status | Code | When |
|---|---|---|
| 422 | unexpected_fields | A field other than the six listed was sent. |
| 422 | invalid | A field is missing or not valid, or the message contains a Social Security number. detail.message lists every problem. |
| 429 | rate_limited | Too many requests in a short period. Retry-After gives the seconds to wait. |