Disputes & reinvestigation
Open a dispute on a furnished record, follow the 30-day clock, and get the outcome.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appOpen 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.
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
Opens a reinvestigation of records furnished in this order. You receive dispute.created, and our team is notified.
Request
| Field | Type | Description |
|---|---|---|
| order_id required | string | The order id (fo_…).Example "fo_ee0b34c5b52fd35b" |
| Field | Type | Description |
|---|---|---|
| recordIds required | array of string | 1 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 null | What the consumer told you, in their words, up to 8,000 characters. |
| receivedAt optional | string (date-time) or null | When 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
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.
| 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 order on this account. |
| 422 | unknown_record | A 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
{
"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
}| Status | Meaning |
|---|---|
received | Logged; the clock is running. |
investigating | Our team is reinvestigating the record. |
verified | The record was confirmed as furnished. Nothing changes. |
modified | The record was corrected. changes lists what changed. |
deleted | The record was removed, or found not to be the consumer’s. |
unable_to_verify | It 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.
| Field | Type | Description |
|---|---|---|
| id | string | The dispute id. Example "fd_acae08b7d57ccc18" |
| orderId | string | The 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 string | The disputed recordId values. |
| reason | string one of "not_me", "inaccurate", "incomplete", "outdated", "other" | The reason given. |
| consumerStatement | string or null | The 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 null | When 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 null | The reinvestigation's notes. null until written. |
| changes | object or null | For a modified outcome, what changed. null otherwise. |
| resolvedAt | string (date-time) or null | When the outcome was reached. null while open. |
| overdue | boolean | true for an open dispute past dueAt. |
Retrieve an FCRA dispute — GET /v1/fcra/disputes/{dispute_id}
A dispute, its due date and its outcome.
Request
| Field | Type | Description |
|---|---|---|
| dispute_id required | string | The dispute id (fd_…).Example "fd_acae08b7d57ccc18" |
Response
The dispute.
The body is the Dispute object. A reinvestigation of furnished records, on the 30-day clock from receivedAt.
| 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 dispute on this account. |
Extend an FCRA dispute — POST /v1/fcra/disputes/{dispute_id}/information
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
| Field | Type | Description |
|---|---|---|
| dispute_id required | string | The dispute id (fd_…).Example "fd_acae08b7d57ccc18" |
| Field | Type | Description |
|---|---|---|
| statement required | string | The consumer's new information, 1 to 8,000 characters. |
Response
The extended dispute.
The body is the Dispute object. A reinvestigation of furnished records, on the 30-day clock from receivedAt.
| 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 dispute on this account. |
| 409 | dispute_not_extendable | The dispute is resolved, already extended, or past dueAt. |
What an outcome does
deletedandunable_to_verifysuppress the record from every later FCRA order (disputed_suppressed).modifiedattaches the correction to the record, ascorrections, in every later order that furnishes it.- A
record.correctedevent 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
Every dispute on your orders, opened by you or in the consumer portal, earliest due first.
Request
| Field | Type | Description |
|---|---|---|
| status optional | string one of "received", "investigating", "verified", "modified", "deleted", "unable_to_verify" | Only disputes with this status. |
| orderId optional | string | Only disputes on this order. |
Response
The disputes.
| Field | Type | Description |
|---|---|---|
| disputes | array of Dispute | The disputes, by dueAt. |
| 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. |