NAnatural
Card Sessions

Get card session

Changed on

Get a card session's status. It never includes card data.

get/card-sessions/{sessionId}

Request

  • Base URL
    https://api.natural.com
  • URL
    https://api.natural.com/card-sessions/{sessionId}
  • Auth
    HTTP bearer

Path parameters

sessionIdstring required

Card session ID (csn_*).

Query parameters

customerPartyIdstring

Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf.

Headers

X-Instance-IDstring nullable

Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money.

Response

Successful Response

sessionIdstring required
cardIdstring required
cardSource'natural_issued' | 'external' required

natural_issued: an agent card Natural issued to you. external: a card the user added on the dashboard.

status'pending_approval' | 'approved' | 'declined' | 'claimed' | 'expired' required

pending_approval: waiting for the user; keep polling. approved: claim it now. declined: the user said no. claimed: already collected. expired: open a new session.

allowedHostsstring[] required
referencestring nullable required

The reference you created the session with. Null when you didn't set one.

approvalExpiresAtstring required

A pending session must be approved before this, 24 hours after creation. After it, an unapproved session is expired.

claimExpiresAtstring required

An approved session must be claimed before this: approval plus claimWindowSeconds. Until the user approves, it's the latest that could be: approvalExpiresAt plus claimWindowSeconds. After it, an unclaimed session is expired.

claimedAtstring nullable required
credentialExpiresAtstring nullable required

When the claimed proxy login stops working.

createdAtstring required

Changes