FCRA Partner API · v1.0.0 · approved partners

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.app

An 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

POST/v1/consumer/portal/sessionNo API key

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

Body · application/json
FieldTypeDescription
accessCode
required
stringThe order's consumerPortal.accessCode, with or without dashes, any case.
Example "K7QF-2MXP-9RDA"
lastName
required
stringThe 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

200 · application/json

A session token.

FieldTypeDescription
token
stringSend as Authorization: Bearer <token> on the other portal routes.
expiresAt
string (date-time)30 minutes from now.
Errors
StatusCodeWhen
401not_matchedAny of the three did not match, or the order was cancelled. The message is the same whatever was wrong.
429lockedFive failures within the last hour for this code or from this IP address. Attempts are refused until fewer than five fall within the hour.
429rate_limitedToo 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

GET/v1/consumer/portal/reportAuth: Authorization: Bearer (portal session)

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

Headers
FieldTypeDescription
Authorization
required
stringBearer <token> from POST /v1/consumer/portal/session.

Response

200 · application/json

The consumer's view of the order.

FieldTypeDescription
order
objectThe order, as the consumer sees it.
order.id
stringThe order id.
order.date
string (date-time)When the order was placed.
order.completedAt
string (date-time) or nullWhen 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
stringThe purpose in plain language, for example Employment screening.
order.requestedBy
string or nullWho asked for the report, as the consumer knows them: the client's branded name, else the partner's organization.
order.endUser
string or nullThe business the report was for.
order.sandbox
booleantrue for a sandbox order.
branding
Branding or nullThe client's branding, when set: the portal shows their name and logo as the requester.
agency
AgencyThe consumer reporting agency that prepared the report and handles disputes.
searches
array of objectEach current search.
searches[].type
string
one of "sex_offender", "criminal", "healthcare"
sex_offender, criminal or healthcare.
searches[].label
stringSex 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 nullThe result in plain language, or This search is still running.
searches[].completedAt
string (date-time) or nullWhen the search finished. null while running.
searches[].coverage
object or nullWhat was searched, in consumer-safe form. null while the search is running.
searches[].coverage.searchedLive
array of objectEach source searched live, and when.
searches[].coverage.searchedLive[].name
stringThe source's name.
searches[].coverage.searchedLive[].jurisdiction
stringWhere it covers.
searches[].coverage.searchedLive[].checkedAt
string (date-time)When it was searched.
searches[].coverage.searchedLive[].answered
booleantrue when it answered.
searches[].coverage.otherSources
objectThe sources searched in our data, summarised.
searches[].coverage.otherSources.count
integerHow many answered.
searches[].coverage.otherSources.oldestDataAsOf
string (date-time) or nullThe oldest dataAsOf among them. null when none carries one.
searches[].coverage.otherSources.newestDataAsOf
string (date-time) or nullThe newest.
records
array of PortalRecordEvery record furnished in the order's finished searches.
rights
objectThe consumer's rights.
rights.summaryUrl
string (uri)The CFPB Summary of Your Rights Under the FCRA.
rights.disputeDays
integerThe reinvestigation period, in days: 30.
rights.supportEmail
stringWhere the consumer can write to us.
Errors
StatusCodeWhen
401no_sessionNo Authorization: Bearer header.
401session_expiredThe 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.

FieldTypeDescription
recordId
stringThe record id. Send it in recordIds to dispute it.
type
string
one of "sex_offender", "criminal", "healthcare"
sex_offender, criminal or healthcare.
title
stringSex offender registry record or Criminal record.
nameOnRecord
string or nullThe name as the record states it.
dobOnRecord
string or nullThe date of birth as the record states it.
verifiedAt
string (date-time) or nullWhen the record was re-verified with the official source.
lines
array of stringThe 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
booleantrue when a dispute corrected this record.
record
FurnishedRecordThe 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

POST/v1/consumer/portal/disputesAuth: Authorization: Bearer (portal session)

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

Headers
FieldTypeDescription
Authorization
required
stringBearer <token> from POST /v1/consumer/portal/session.
Body · application/json
FieldTypeDescription
recordIds
required
array of string1 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 nullThe consumer's statement, up to 8,000 characters.

Response

201 · application/json

The dispute.

The body is the PortalDispute object. A dispute as the consumer sees it in the portal.

Errors
StatusCodeWhen
401session_expiredThe session ended. Open the report again.
422unknown_recordA record id is not in this report.

Consumer portal disputes list — GET /v1/consumer/portal/disputes

GET/v1/consumer/portal/disputesAuth: Authorization: Bearer (portal session)

Every dispute on this order — the consumer's and yours — with status, due date and outcome.

Request

Headers
FieldTypeDescription
Authorization
required
stringBearer <token> from POST /v1/consumer/portal/session.

Response

200 · application/json

The disputes.

FieldTypeDescription
disputes
array of PortalDisputeEvery dispute on this order, by dueAt.
Errors
StatusCodeWhen
401session_expiredThe 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.

FieldTypeDescription
id
stringThe dispute id.
recordIds
array of stringThe disputed record ids.
reason
string
one of "not_me", "inaccurate", "incomplete", "outdated", "other"
The reason given.
consumerStatement
string or nullThe 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 nullWhen 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 nullWhen the outcome was reached, or null.
changes
object or nullWhat 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

POST/v1/consumer/requestsNo API key

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

Body · application/json
FieldTypeDescription
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
stringThe consumer's name. Text past 120 characters is cut.
email
required
stringAn address we can reply to, up to 254 characters. It is checked for a valid shape only.
message
required
stringThe 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
stringA form field the consumer page sends empty. Send it empty or omit it.
elapsedMs
optional
integerSent by the consumer page. Omit it.

Response

201 · application/json

The request, recorded.

FieldTypeDescription
id
stringThe request id (cons_…).
kind
string
one of "file", "dispute"
As sent.
receivedAt
string (date-time)When it was received.
dueAt
string (date-time) or nullFor a dispute, 30 days after receivedAt. null for a file request.
supportEmail
stringWhere the consumer can write to us.
Errors
StatusCodeWhen
422unexpected_fieldsA field other than the six listed was sent.
422invalidA field is missing or not valid, or the message contains a Social Security number. detail.message lists every problem.
429rate_limitedToo many requests in a short period. Retry-After gives the seconds to wait.

Product overview