FCRA Partner API · v1.0.0 · approved partners

Disputes & reinvestigation

Open a dispute on a furnished record, follow the 30-day clock, and get the outcome.

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

Open a dispute

When a consumer disputes a record you received from us, open a reinvestigation on the order. Name the records, the reason, the consumer’s statement, and when the dispute reached you — the 30-day clock runs from that moment (15 U.S.C. § 1681i(a)(1)); without receivedAt it runs from the call. Every request field is in the dispute request reference below.

POST /v1/fcra/orders/{id}/disputes
curl -X POST https://api.offendersearch.app/v1/fcra/orders/fo_ee0b34c5b52fd35b/disputes \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recordIds": ["crim:IL-SANGAMON:2021CR004417"],
    "reason": "not_me",
    "consumerStatement": "I have never lived in Sangamon County.",
    "receivedAt": "2026-10-03T09:12:00Z"
  }'

FCRA dispute API — POST /v1/fcra/orders/{order_id}/disputes request and response

POST/v1/fcra/orders/{order_id}/disputesAuth: X-API-Key

Opens a reinvestigation of records furnished in this order. You receive dispute.created, and our team is notified.

Request

Path parameters
FieldTypeDescription
order_id
required
stringThe order id (fo_…).
Example "fo_ee0b34c5b52fd35b"
Body · application/json
FieldTypeDescription
recordIds
required
array of string1 to 100 recordId values furnished in this order (superseded searches included). Any other id is 422 unknown_record.
Example ["crim:IL-SANGAMON:2021CR004417"]
reason
required
string
one of "not_me", "inaccurate", "incomplete", "outdated", "other"
Why the consumer disputes it.
consumerStatement
optional
string or nullWhat the consumer told you, in their words, up to 8,000 characters.
receivedAt
optional
string (date-time) or nullWhen the dispute reached you, ISO 8601; dueAt is 30 days later. Omit it and the time of this call is used. More than five minutes in the future is a 422.

Response

201 · application/json

The dispute, status received, due 30 days after receivedAt.

The body is the Dispute object. A reinvestigation of furnished records, on the 30-day clock from receivedAt.

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 order on this account.
422unknown_recordA recordIds entry was not furnished in this order.
422—A field failed validation, including a receivedAt more than five minutes in the future (the standard validation body).

The dispute object

GET /v1/fcra/disputes/{id}
{
  "id": "fd_acae08b7d57ccc18",
  "orderId": "fo_ee0b34c5b52fd35b",
  "origin": "partner",
  "recordIds": ["crim:IL-SANGAMON:2021CR004417"],
  "reason": "not_me",
  "consumerStatement": "I have never lived in Sangamon County.",
  "status": "investigating",
  "receivedAt": "2026-10-03T09:12:00Z",
  "dueAt": "2026-11-02T09:12:00Z",
  "extendedAt": null,
  "overdue": false,
  "notes": null,
  "changes": null,
  "resolvedAt": null
}
StatusMeaning
receivedLogged; the clock is running.
investigatingOur team is reinvestigating the record.
verifiedThe record was confirmed as furnished. Nothing changes.
modifiedThe record was corrected. changes lists what changed.
deletedThe record was removed, or found not to be the consumer’s.
unable_to_verifyIt could not be verified. It is treated as deleted.

If the consumer sends new information during the investigation, add it with POST /v1/fcra/disputes/{id}/information and { "statement": "…" }. That is the one 15-day extension (15 U.S.C. § 1681i(a)(1)(B)): dueAt moves and extendedAt records when. It returns 409 dispute_not_extendable once the dispute is resolved, already extended or past due. overdue is true for an open dispute past dueAt.

The Dispute object — FCRA dispute fields

A reinvestigation of furnished records, on the 30-day clock from receivedAt.

Returned or accepted by POST /v1/fcra/orders/{order_id}/disputes, GET /v1/fcra/disputes, GET /v1/fcra/disputes/{dispute_id}, POST /v1/fcra/disputes/{dispute_id}/information.

FieldTypeDescription
id
stringThe dispute id.
Example "fd_acae08b7d57ccc18"
orderId
stringThe order the disputed records were furnished in.
origin
string
one of "partner", "consumer_portal"
partner — opened through this API; consumer_portal — opened by the consumer in the portal.
recordIds
array of stringThe disputed recordId values.
reason
string
one of "not_me", "inaccurate", "incomplete", "outdated", "other"
The reason given.
consumerStatement
string or nullThe consumer's statement. New information added with POST /v1/fcra/disputes/{dispute_id}/information is appended under a dated heading. null when none was given.
receivedAt
string (date-time)When the dispute was received — the start of the 30-day clock.
dueAt
string (date-time)When the reinvestigation is due: 30 days after receivedAt, plus 15 days once extended.
extendedAt
string (date-time) or nullWhen the one 15-day extension was applied. null until then.
status
string
one of "received", "investigating", "verified", "modified", "deleted", "unable_to_verify"
received (logged; the clock is running), investigating, verified (confirmed as furnished; nothing changes), modified (corrected — see changes), deleted (removed, or found not to be the consumer's) or unable_to_verify (treated as deleted).
notes
string or nullThe reinvestigation's notes. null until written.
changes
object or nullFor a modified outcome, what changed. null otherwise.
resolvedAt
string (date-time) or nullWhen the outcome was reached. null while open.
overdue
booleantrue for an open dispute past dueAt.

Retrieve an FCRA dispute — GET /v1/fcra/disputes/{dispute_id}

GET/v1/fcra/disputes/{dispute_id}Auth: X-API-Key

A dispute, its due date and its outcome.

Request

Path parameters
FieldTypeDescription
dispute_id
required
stringThe dispute id (fd_…).
Example "fd_acae08b7d57ccc18"

Response

200 · application/json

The dispute.

The body is the Dispute object. A reinvestigation of furnished records, on the 30-day clock from receivedAt.

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 dispute on this account.

Extend an FCRA dispute — POST /v1/fcra/disputes/{dispute_id}/information

POST/v1/fcra/disputes/{dispute_id}/informationAuth: X-API-Key

Adds the consumer's new information to an open dispute. This is the one 15-day extension: dueAt moves 15 days and extendedAt records when.

Request

Path parameters
FieldTypeDescription
dispute_id
required
stringThe dispute id (fd_…).
Example "fd_acae08b7d57ccc18"
Body · application/json
FieldTypeDescription
statement
required
stringThe consumer's new information, 1 to 8,000 characters.

Response

200 · application/json

The extended dispute.

The body is the Dispute object. A reinvestigation of furnished records, on the 30-day clock from receivedAt.

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 dispute on this account.
409dispute_not_extendableThe dispute is resolved, already extended, or past dueAt.

What an outcome does

  • deleted and unable_to_verify suppress the record from every later FCRA order (disputed_suppressed).
  • modified attaches the correction to the record, as corrections, in every later order that furnishes it.
  • A record.corrected event goes to every partner that received the record, not only the one that opened the dispute.

Disputes from the consumer portal

A consumer can also dispute directly through the consumer portal. That creates the same dispute object with origin: "consumer_portal", and you receive dispute.created for your order. A dispute that reaches us through our consumer request form, without an access code, is reinvestigated by our team and is not listed among your disputes; when it deletes or corrects a record you received, you receive record.corrected. GET /v1/fcra/disputes?status=&orderId= lists every dispute on your orders, earliest due first.

List FCRA disputes — GET /v1/fcra/disputes

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

Every dispute on your orders, opened by you or in the consumer portal, earliest due first.

Request

Query parameters
FieldTypeDescription
status
optional
string
one of "received", "investigating", "verified", "modified", "deleted", "unable_to_verify"
Only disputes with this status.
orderId
optional
stringOnly disputes on this order.

Response

200 · application/json

The disputes.

FieldTypeDescription
disputes
array of DisputeThe disputes, by dueAt.
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.

Product overview