Skip to main content
POST
/
api
/
v1
/
cardholder_onboarding_sessions
curl -X POST https://api.agentcard.sh/api/v1/cardholder_onboarding_sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://yoursite.com/agentcard/return",
    "email": "jane@example.com",
    "external_user_id": "user_123",
    "state": "f3a9c2"
  }'

{
  "id": "cos_a1b2c3d4e5f6a7b8c9d0e1f2",
  "status": "pending",
  "url": "https://api.agentcard.sh/onboard/4f8a…",
  "return_url": "https://yoursite.com/agentcard/return",
  "state": "f3a9c2",
  "external_user_id": "user_123",
  "cardholder_id": null,
  "sandbox": true,
  "created_at": "2026-06-10T18:00:00.000Z",
  "completed_at": null,
  "expires_at": "2026-06-10T19:00:00.000Z"
}
Creates a hosted onboarding session. Redirect your user to the returned url; they confirm their email with a one-click link, consent on an AgentCard-hosted page, and a cardholder is created (or claimed) in your organization linked to their AgentCard account. We then send them back to your return_url with the session id. Before your first session, register your return URLs once: PUT /orgs/:orgId/onboarding-return-urls (organization owner, dashboard credentials) with { "returnUrls": ["https://yoursite.com/agentcard/return"] }.
The hosted url contains a secret capability token. Hand it only to the end user it is meant for — anyone with the link can start the email step.

​
Request body

​
return_url
string
required
Where we send the user after consent. Must exactly match (origin + path) one of your registered onboarding return URLs. https required; http://localhost is allowed with test keys.
​
email
string
Prefill for the email form. Required in practice for test keys — test-mode sessions will only send the confirmation email to this exact address.
​
external_user_id
string
Your own identifier for this user. Echoed back on the session object and the completion webhook so you can correlate.
​
cardholder_id
string
An existing, unlinked cardholder in your organization to claim instead of creating a new one. The user must verify the email on that cardholder’s record. 404 if unknown, 409 if already linked.
​
state
string
Opaque value (max 512 chars) echoed back on the final redirect — use it to bind the redirect to your user’s browser session (CSRF).

​
Response

​
id
string
Session id (cos_…). The final redirect carries it as ?session_id=.
​
url
string
The hosted onboarding URL to redirect your user to. Expires in 60 minutes.
​
status
string
pending → verified → completed (or expired).
curl -X POST https://api.agentcard.sh/api/v1/cardholder_onboarding_sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://yoursite.com/agentcard/return",
    "email": "jane@example.com",
    "external_user_id": "user_123",
    "state": "f3a9c2"
  }'

{
  "id": "cos_a1b2c3d4e5f6a7b8c9d0e1f2",
  "status": "pending",
  "url": "https://api.agentcard.sh/onboard/4f8a…",
  "return_url": "https://yoursite.com/agentcard/return",
  "state": "f3a9c2",
  "external_user_id": "user_123",
  "cardholder_id": null,
  "sandbox": true,
  "created_at": "2026-06-10T18:00:00.000Z",
  "completed_at": null,
  "expires_at": "2026-06-10T19:00:00.000Z"
}

​
After the redirect

The user lands on return_url?session_id=cos_…&state=…. Never trust the query params alone — fetch the session server-side with your API key and read status and cardholder_id: 
curl https://api.agentcard.sh/api/v1/cardholder_onboarding_sessions/cos_a1b2... \
  -H "Authorization: Bearer sk_test_..."
You’ll also receive a cardholder_onboarding_session.completed webhook (plus cardholder.created when a new cardholder was created rather than claimed). From there, use the regular cardholder endpoints — payment-method setup, card creation — with the returned cardholder_id.