Cards

Card endpoints live under /developer/company. Every request needs Authorization: Bearer <access_token> and X-On-Behalf-Of: <company_id> — see Authentication. Reading cards needs no specific permission beyond company membership. Freezing and unfreezing require the manage_cards permission, which owners, admins, and employees hold by default.

Endpoints

Method	Path	Purpose
`GET`	`/developer/company/v2/card`	List cards with filters and paging.
`GET`	`/developer/company/v2/card/{id}`	Fetch one card.
`POST`	`/developer/company/card/{id}/freeze`	Freeze one card.
`POST`	`/developer/company/card/{id}/unfreeze`	Unfreeze one card.

Use the v2 paths for reads. The older GET /developer/company/card list is also reachable but returns a different shape and is not documented here.

List cards

curl -sS "https://api.incard.com/developer/company/v2/card?status=active,frozen&take=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID"

Response (truncated):

{
  "data": [
    {
      "id": "3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e",
      "token": "84de8ea0-e52a-4888-afd2-9d8dd5a42c20",
      "name": "Marketing spend",
      "type": "virtual",
      "lastFour": "4242",
      "expiryDate": "07/29",
      "status": "active",
      "user": { "id": "29b297ca-…", "firstName": "Alex", "lastName": "Example" },
      "spendingLimit": { "type": "monthly", "amount": 5000, "amountSpent": 1249.5, "utilization": 24.99 },
      "companyAccount": { "id": "0d6c0a2a-…", "name": "Main GBP account", "currencyCode": "GBP" },
      "currencyCode": "GBP"
    }
  ],
  "meta": { "total": 1, "totalPending": 0, "totalNonPending": 1, "take": 50, "skip": 0 }
}

Cards are returned newest first. Terminated cards are excluded unless you pass includeTerminated=true or ask for them in status.

Filters and paging

Parameter	Notes
`take`, `skip`	Page size (default 10, max 100) and offset. `meta.total` gives the full count.
`type`	`physical` or `virtual`.
`status`	Comma-separated: `active`, `pending`, `frozen`, `expired`, `terminated`. `expired` is derived from `expiryDate`.
`userIds`	Comma-separated user UUIDs the cards are assigned to.
`companyAccountIds`	Comma-separated account UUIDs the cards draw from.
`search`	Case-insensitive match on card name or last four digits.
`sort`	`unactivatedFirst` lists `pending` cards before the rest.

Invalid values return 400 with { "error": "<field>: <message>" }.

Get a card

curl -sS "https://api.incard.com/developer/company/v2/card/3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID"

Returns the same card object as a list item, without the data wrapper. Unknown or other-company cards return 404 with { "error": "Card not found" }.

Card status

Status	Meaning	Can freeze?	Can unfreeze?
`pending`	Issued but not yet activated.	No	No
`active`	Usable.	Yes	Already active
`frozen`	Frozen by a team member. New authorisations are declined.	Already frozen	Yes
`blocked`	Blocked by Incard. Contact support.	No	No
`closing`	Being closed.	No	No
`terminated`	Permanently cancelled.	No	No

Only a frozen card can be unfrozen through the API.

Freeze a card

curl -sS -X POST "https://api.incard.com/developer/company/card/3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e/freeze" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID"

No request body. The response is the stored card record with status now frozen:

{
  "id": "3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e",
  "companyId": "bebb185d-8210-4e66-ac63-397b49a1e09f",
  "name": "Marketing spend",
  "token": "84de8ea0-e52a-4888-afd2-9d8dd5a42c20",
  "type": "virtual",
  "status": "frozen",
  "lastFour": "4242",
  "updatedAt": "2026-09-02T11:15:27.000Z"
}

The action is idempotent. Freezing a card that is already frozen returns 200 with the unchanged record.

Unfreeze a card

curl -sS -X POST "https://api.incard.com/developer/company/card/3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e/unfreeze" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID"

Returns the card record with status back to active. Unfreezing a card that is already active returns 200 unchanged.

Errors

Card actions report problems in a common envelope:

{
  "severity": "warning",
  "path": "/api/company/card/3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e/unfreeze",
  "status": 400,
  "reason": "Card has invalid source status for this action",
  "method": "POST"
}

Status	`reason`	Cause
400	`Card not found`	The UUID does not match a card in this company.
400	`Card has invalid status for this action`	Freeze attempted on a card that is not `active`.
400	`Card has invalid source status for this action`	Unfreeze attempted on a card that is not `frozen`.
403	`Not permitted`	The API key’s member lacks `manage_cards`.

Get started

Resources

Events

Endpoints

List cards

Filters and paging

Get a card

Card status

Freeze a card

Unfreeze a card

Errors

​Endpoints

​List cards

​Filters and paging

​Get a card

​Card status

​Freeze a card

​Unfreeze a card

​Errors

Endpoints

List cards

Filters and paging

Get a card

Card status

Freeze a card

Unfreeze a card

Errors