curl --request POST \
--url https://api.platform.sandbox.dakota.xyz/cards/{card_id}/lost_stolen_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}/lost_stolen_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}/lost_stolen_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}/lost_stolen_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": 4,
"last4": "4242",
"external_id": "ads-card-01",
"nickname": "Ads card",
"freeze_sources": [
"lost_stolen"
],
"created_at": 1758211200,
"updated_at": 1758212400
}{
"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"
}{
"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 lost or stolen
Report that the cardholder told you their card was lost or stolen. Dakota freezes the card, pauses it at the card issuer, and records the report so that no ordinary unfreeze can lift it.
The request has no body. The path names the card.
This is not a dispute. Use it when the cardholder reports the card
missing and names no specific transaction they want their money back for.
If they are disputing a charge, file a dispute with
POST /card_dispute_reports instead — that records the report and the
disputed transaction together.
The freeze is not an ordinary freeze. The card comes back with
freeze_sources including lost_stolen, and while that source is
present a request setting status: active on
PATCH /cards/{card_id} is refused with #card-freeze-held. Freezing,
closing and renaming all still work, and so does
PUT /cards/{card_id}/spend_limit.
To release it, report the card found with
POST /cards/{card_id}/found_report. That clears the report and leaves
the card frozen; the ordinary unfreeze works after that. If the card is
gone for good, close it and issue a new one.
It is safe to repeat. Reporting a card that is already reported returns 200 with the same card and does nothing a second time. 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, which pauses the card at the card issuer. 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}/lost_stolen_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}/lost_stolen_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}/lost_stolen_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}/lost_stolen_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": 4,
"last4": "4242",
"external_id": "ads-card-01",
"nickname": "Ads card",
"freeze_sources": [
"lost_stolen"
],
"created_at": 1758211200,
"updated_at": 1758212400
}{
"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"
}{
"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 card is reported and frozen. freeze_sources includes
lost_stolen, and status reads frozen — unless the card was
already overdrawn, which keeps its own status and returns to
frozen rather than active once the debt is paid.
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?

