> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Exchange the attempt

> One-time collection of the user's connection after they verified (you'll know from the `connection.created` webhook, which carries `onboarding_attempt_id`). Returns the same token pair `connect/verify` would have: store `access_token`, `refresh_token`, and `user.id`, and keep the session alive with `POST /api/v2/connect/refresh`. Only the client that created the attempt can exchange it, and only once.

## How it works

After the user verifies (the `connection.created` webhook tells you), exchange
the attempt once for the connection: the same `access_token`, `refresh_token`,
and `user.id` that `connect/verify` returns. Store all three and refresh with
[`POST /api/v2/connect/refresh`](/companies/api/reference/connect-refresh);
the user never sees a code again.

Only the client that created the attempt can exchange it, and only once. A
`409 not_converted` means the user hasn't verified yet; a
`410 already_exchanged` means you already collected the pair, so use the
tokens you stored.


## OpenAPI

````yaml openapi.json POST /api/v2/onboarding_attempts/{id}/exchange
openapi: 3.1.0
info:
  title: Agentcard API
  version: 2.0.0
  description: >-
    The Agentcard v2 API — connect your users and verify their identity from
    your own backend. Every call is authenticated with a platform access token
    minted from your `client_id` + `client_secret`.
servers:
  - url: https://api.agentcard.sh
    description: >-
      There is one base URL. Sandbox vs production is decided by the client
      credential you use, never by the host.
security:
  - platformToken: []
tags:
  - name: Authentication
    description: >-
      Exchange your client credentials for a platform access token, and
      introspect what a token acts as.
  - name: Connect
    description: >-
      Connect a user to your platform: send a one-time code, verify it, record
      consent, and keep the connection alive.
  - name: Identity verification
    description: >-
      Verify a connected user's identity: upload their ID, submit any extra
      fields we ask for, then show a short face scan.
  - name: Wallet funding
    description: >-
      Fund a connected user's wallet from your own UI — request a payment link,
      relay the phone verification code, and poll until the funds land.
  - name: Withdrawals
    description: >-
      Move money out of a connected user's wallet — to a saved bank account or a
      crypto address on Base. Transfers are processed manually by the Agentcard
      team, usually within 1-3 business days.
paths:
  /api/v2/onboarding_attempts/{id}/exchange:
    post:
      summary: Exchange for the connection
      description: >-
        One-time collection of the user's connection after they verified (you'll
        know from the `connection.created` webhook, which carries
        `onboarding_attempt_id`). Returns the same token pair `connect/verify`
        would have: store `access_token`, `refresh_token`, and `user.id`, and
        keep the session alive with `POST /api/v2/connect/refresh`. Only the
        client that created the attempt can exchange it, and only once.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The attempt id from the create response.
      responses:
        '200':
          description: The connection. Store the token pair and `user.id`.
          content:
            application/json:
              example:
                object: connection
                access_token: act_1a2b3c…
                refresh_token: rct_4d5e6f…
                token_type: Bearer
                expires_in: 3600
                user:
                  id: user_7g8h9i
                external_user_id: your-internal-id
        '409':
          description: '`not_converted`: the user has not verified yet.'
        '410':
          description: >-
            `already_exchanged`: the pair was already collected; use the tokens
            you stored.
components:
  securitySchemes:
    platformToken:
      type: http
      scheme: bearer
      description: >-
        A platform access token. Get one on the **Create an access token**
        endpoint by exchanging your `client_id` + `client_secret`, then send it
        as `Authorization: Bearer <token>`. Tokens live one hour.

````