Cards

Card reads require PARTNER_API_V1_BASIC. Card writes and actions (create, update, lock, unlock, terminate) require PARTNER_API_V1_CARDS.

Common flows

List / retrieve cards

GET /api/partner/v1/cards?page=1
GET /api/partner/v1/cards/{id}

Requires PARTNER_API_V1_BASIC. List filters use public Partner API names:

Query parameter	Behavior
`card_type`	`EMPLOYEE`, `VENDOR`, or `SINGLE-USE`
`card_owner_id`	Narrows `card_type` to one owner. Send it with `card_type`; without `card_type`, it is ignored.
`subsidiary_id`	Narrows results to one subsidiary
`status`	Narrows results to one card status
`last_four`	Matches the last four card digits

GET /api/partner/v1/cards?card_type=EMPLOYEE&card_owner_id=123&subsidiary_id=7

Create a card

POST /api/partner/v1/cards

Requires PARTNER_API_V1_CARDS. Request body shape is defined by CreateCardRequest in the OpenAPI schema. type is the only field marked required in the schema, but each card type requires additional fields at request time. Sending a schema-valid payload without them returns a 400 ValidationError:

Card type	Additionally required	Notes
`EMPLOYEE`	`employee_details` (`id` or `email`)	Must resolve to exactly one active user
`VENDOR`	`vendor_details` (`id` or `name`) and `subsidiary_details` (`id` or `name`)	Each must resolve to exactly one active vendor / subsidiary
`SINGLE-USE`	`subsidiary_details` (`id` or `name`)	Must resolve to exactly one active subsidiary

These lookups happen against live data, so even a well-formed employee_details/vendor_details/subsidiary_details object is rejected if it doesn’t resolve to a single active record. To retry card creation safely, optionally send an Idempotency-Key header:

POST /api/partner/v1/cards
Idempotency-Key: 7d26f350-0ca5-4f42-a29f-52e57168d80e

After a successful request, the same key and payload replay the stored response with 200 OK without creating another card. Reusing the key with a different payload returns 409 Conflict. Records are retained for seven days and then removed by scheduled cleanup. Only successful 2xx responses are cached. If you receive a definite non-2xx response, use a new key for the retry. If the outcome is unknown, such as after a timeout, retry the same key to avoid creating a duplicate card. Keys must contain 1–255 printable ASCII characters, without spaces, double quotes, or control characters.

Update a card

PUT /api/partner/v1/cards/{id}

Requires PARTNER_API_V1_CARDS.

Lock / unlock / terminate

PUT /api/partner/v1/cards/{id}/lock
PUT /api/partner/v1/cards/{id}/unlock
PUT /api/partner/v1/cards/{id}/terminate

Requires both PARTNER_API_V1_BASIC and PARTNER_API_V1_CARDS. See the interactive examples under API Reference → cards.

Get started

Core resources

Common flows

List / retrieve cards

Create a card

Update a card

Lock / unlock / terminate

​Common flows

​List / retrieve cards

​Create a card

​Update a card

​Lock / unlock / terminate

Common flows

List / retrieve cards

Create a card

Update a card

Lock / unlock / terminate