Skip to main content
POST
Report a card found
Sandbox only. This endpoint is available in sandbox only while we finish development. It is not available in production yet, and its request and response shapes may change before release.

Authorizations

x-api-key
string
header
required

Headers

x-idempotency-key
string<uuid>
required

Unique key (UUID) to ensure request idempotency on POST, PUT and PATCH requests.

A key is scoped to your client, the HTTP method and the path, and is remembered for 24 hours after a successful (below 400) response. Repeating the same request (same JSON body, whatever the key order or whitespace) with the same key within that window returns the original response with X-Idempotent-Replayed: true instead of executing the request again. Using the same key on the same endpoint with a different body returns 422 with problem type idempotency-key-reused; the request is not executed. Error responses (4xx and 5xx) are not remembered, so a request refused for a fixable reason can be corrected and retried under the same key. Request bodies that are not JSON (for example file uploads) are not compared.

Path Parameters

card_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

Response

The report is cleared. freeze_sources no longer includes lost_stolen, and status still reads frozen — clearing a report is not an unfreeze. An overdrawn card keeps its own status.

Response containing card details.

id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

cardholder_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

customer_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

wallet_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

version
integer<int64>
required

The card's version, strictly increasing for this card. It is bumped by one on every change that emits a card.created or card.updated event, including a request that changes nothing, and the same value appears as version in that event's payload. Webhook deliveries can arrive out of order, and updated_at has only one-second resolution, so neither orders them. Keep the highest version you have applied for each card and drop any event or response whose version is not greater than it.

Required range: x >= 1
Example:

7

status
enum<string>
required

Current status of the card. Returns pending on create; flips to active via a card.updated webhook.

overdrawn: The card's wallet owes money after a lost dispute. The card declines every authorization. It returns to its earlier status when the debt is paid. A client cannot request this status, and cannot set active or frozen while the card holds it.

Available options:
pending,
active,
frozen,
closed,
overdrawn
Example:

"pending"

created_at
integer
required

Unix timestamp (seconds) of creation.

updated_at
integer
required

Unix timestamp (seconds) of last update.

last4
string | null

Non-sensitive last four digits, populated from the card provider.

Example:

"4242"

spend_limit
Spend Limit · object | null

A single cap on card spend, enforced when a purchase is authorized. A per_transaction limit is checked against the amount the purchase holds, which in some merchant categories is larger than the purchase: a fuel-pump authorization below 175 USD holds 175 USD, and a restaurant holds 30% above the bill. daily, weekly, monthly and yearly limits count the purchase amount.

external_id
string | null
nickname
string | null

Client-supplied display name for the card. Null when none was set.

Maximum string length: 64
Example:

"Ads card"

freeze_sources
enum<string>[]

What is currently holding a freeze on this card, distinct and sorted. Empty when nothing is. A card is frozen while any source holds it, and lifting one source does not lift another. Read this rather than inferring the cause from status: status reports the card's state at the issuer, so it says only that the card is frozen, never why. manual is a freeze applied through this API and is the only source a client can lift, by sending status: active to this card's PATCH endpoint. While any other source is present that request is rejected with a card-freeze-held problem, because no card-level action will clear it. lost_stolen is the exception that has a remedy: the cardholder reported the card lost or stolen, and reporting it found with POST /cards/{card_id}/found_report clears the report and leaves the card frozen. The ordinary unfreeze works after that.

What is holding a freeze on a card.

manual is a freeze applied deliberately through this API, and is the only source a client can lift.

lost_stolen is a freeze held because the cardholder reported the card lost or stolen. A request to set the card active while it is held is refused. To release it, report the card found with POST /cards/{card_id}/found_report, which clears the report and leaves the card frozen; the ordinary unfreeze works after that.

This enum grows as new freeze causes are built — a value is added when it can actually occur, never before. Treat any value other than manual, including one your client does not recognise, as a hold no card-level request will clear.

Available options:
manual,
lost_stolen
Example:
cardholder
Cardholder Response · object

The cardholder this card belongs to.

wallet
Card Wallet Response · object

The wallet this card draws on. Populated on the single-card detail endpoint; omitted from list responses.