curl --request POST \
--url https://api.platform.sandbox.dakota.xyz/cards/{card_id}/found_report \
--header 'x-api-key: <api-key>' \
--header 'x-idempotency-key: <x-idempotency-key>'const options = {
method: 'POST',
headers: {'x-idempotency-key': '<x-idempotency-key>', 'x-api-key': '<api-key>'}
};
fetch('https://api.platform.sandbox.dakota.xyz/cards/{card_id}/found_report', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.platform.sandbox.dakota.xyz/cards/{card_id}/found_report"
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-api-key": "<api-key>"
}
response = requests.post(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.platform.sandbox.dakota.xyz/cards/{card_id}/found_report"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": "2tQRvvnYkN6edEJUTmF1LzTj2ug",
"cardholder_id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
"customer_id": "2tQRvD3xFcJ7bKpW9qNsT4hZmYr",
"wallet_id": "2tQRvK9pRzM4nVbW8sHqL5jXmYt",
"status": "frozen",
"version": 5,
"last4": "4242",
"external_id": "ads-card-01",
"nickname": "Ads card",
"freeze_sources": [],
"created_at": 1758211200,
"updated_at": 1758213000
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}Report a card found
Report that the cardholder found a card they had reported lost or stolen. Dakota clears the report so the card can be used again.
The request has no body. The path names the card.
The card stays frozen. This clears the report and nothing else. To
put the card back in service, send status: active to
PATCH /cards/{card_id} afterwards — which is refused while the report
stands, and succeeds once it is cleared. Two steps deliberately: an
unfreeze re-runs every other check, including the cardholder’s state and
the wallet’s debt, and a single call that both cleared the report and
opened the card would skip all of them.
A manual freeze you applied yourself is untouched, so a card you had
also frozen by hand stays frozen until you lift that too.
It clears the report whatever set it — the cardholder’s own report
through POST /cards/{card_id}/lost_stolen_report, or a dispute you
filed with reason card_lost or card_stolen. Any dispute you filed
is untouched: this moves the card’s status, never a claim. It is also
not a fraud re-check — neither this call nor the unfreeze that follows
consults an open dispute, so if you need a claim respected, check it
before calling.
An overdrawn card keeps that status and returns to frozen rather
than active once the debt is paid, which is where the report left it.
It is safe to repeat. Reporting a card found that carries no report returns 200 with the card as it stands, and does nothing. If a request times out or its response is lost, send it again.
A card belonging to another client is answered with 404, the same as a card that does not exist.
This endpoint calls the card provider. It is not only a write to Dakota’s own table, so expect network latency.
curl --request POST \
--url https://api.platform.sandbox.dakota.xyz/cards/{card_id}/found_report \
--header 'x-api-key: <api-key>' \
--header 'x-idempotency-key: <x-idempotency-key>'const options = {
method: 'POST',
headers: {'x-idempotency-key': '<x-idempotency-key>', 'x-api-key': '<api-key>'}
};
fetch('https://api.platform.sandbox.dakota.xyz/cards/{card_id}/found_report', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.platform.sandbox.dakota.xyz/cards/{card_id}/found_report"
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-api-key": "<api-key>"
}
response = requests.post(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.platform.sandbox.dakota.xyz/cards/{card_id}/found_report"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": "2tQRvvnYkN6edEJUTmF1LzTj2ug",
"cardholder_id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
"customer_id": "2tQRvD3xFcJ7bKpW9qNsT4hZmYr",
"wallet_id": "2tQRvK9pRzM4nVbW8sHqL5jXmYt",
"status": "frozen",
"version": 5,
"last4": "4242",
"external_id": "ads-card-01",
"nickname": "Ads card",
"freeze_sources": [],
"created_at": 1758211200,
"updated_at": 1758213000
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Customer Not Found",
"status": 404,
"detail": "Customer cst_2abc123 was not found in your organization.",
"instance": "https://api.platform.dakota.xyz/customers/cst_2abc123",
"request_id": "req_7f3a8b2c"
}Authorizations
Headers
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
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.
27^[0-9A-Za-z]{27}$"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.
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.
27^[0-9A-Za-z]{27}$"1NFHrqBHb3cTfLVkFSGmHZqdDPi"
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.
27^[0-9A-Za-z]{27}$"1NFHrqBHb3cTfLVkFSGmHZqdDPi"
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.
27^[0-9A-Za-z]{27}$"1NFHrqBHb3cTfLVkFSGmHZqdDPi"
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.
27^[0-9A-Za-z]{27}$"1NFHrqBHb3cTfLVkFSGmHZqdDPi"
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.
x >= 17
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.
pending, active, frozen, closed, overdrawn "pending"
Unix timestamp (seconds) of creation.
Unix timestamp (seconds) of last update.
Non-sensitive last four digits, populated from the card provider.
"4242"
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.
Show child attributes
Show child attributes
Client-supplied display name for the card. Null when none was set.
64"Ads card"
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.
manual, lost_stolen ["manual"]
The cardholder this card belongs to.
Show child attributes
Show child attributes
The wallet this card draws on. Populated on the single-card detail endpoint; omitted from list responses.
Show child attributes
Show child attributes
Was this page helpful?

