> ## 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.

# Start a card attachment

> Start attaching the connected user's own card. Returns a hosted `attach_url` for the user to open — adding the card takes about a minute (a one-time code from their bank, then a passkey). The card number is entered on the hosted page only; it never passes through your servers. Once attached, cards created over MCP charge this card directly — no identity verification and no wallet funding.

## How it works

You ask for an attachment for a connected user; we return an `attach_url`.
The user opens it and adds their own card in about a minute — a one-time code
from their bank, then a passkey. The card number is entered on the hosted page
only; it never passes through your servers.

Poll [Get the attachment status](/companies/api/reference/attach-status) (or
call this endpoint again — with an active attachment it answers `200` with the
card instead of starting over). Once `active`, cards created over
[MCP](/companies/mcp/overview) charge the attached card directly — no identity
verification, no wallet funding.

If the response is `422 user_info_required`, `missing_fields` names what to
collect first: `phone_number` via
[POST /api/v2/wallet/phone/start](/companies/api/reference/wallet-phone-start),
`consent` via
[POST /api/v2/connect/consent](/companies/api/reference/connect-consent).


## OpenAPI

````yaml openapi.json POST /api/v2/attach
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/attach:
    post:
      tags:
        - Card attachment
      summary: Start a card attachment
      description: >-
        Start attaching the connected user's own card. Returns a hosted
        `attach_url` for the user to open — adding the card takes about a minute
        (a one-time code from their bank, then a passkey). The card number is
        entered on the hosted page only; it never passes through your servers.
        Once attached, cards created over MCP charge this card directly — no
        identity verification and no wallet funding.
      operationId: attachStart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: The connected user's id.
              required:
                - user_id
            example:
              user_id: usr_123
      responses:
        '200':
          description: A card is already attached for this user — nothing to do.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardAttachment'
              example:
                object: card_attachment
                id: ca_123
                user_id: usr_123
                status: active
                card:
                  network: visa
                  brand: Visa
                  last4: '4242'
                  art_url: null
        '201':
          description: The attachment was started — send the user the `attach_url`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardAttachment'
              example:
                object: card_attachment
                id: ca_123
                user_id: usr_123
                status: pending
                attach_url: https://agentcard.sh/attach/…
                expires_at: '2026-07-23T00:00:00.000Z'
        '400':
          description: '`invalid_request` — missing `user_id`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            `attach_unavailable` — card attachment is not available; fall back
            to wallet funding + `create_card`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/ConnectionNotFound'
        '409':
          $ref: '#/components/responses/UserConflict'
        '422':
          description: >-
            `user_info_required` — a phone number and recorded consent are
            required first; `missing_fields` names what to collect
            (`phone_number` via `POST /api/v2/wallet/phone/start`, `consent` via
            `POST /api/v2/connect/consent`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: '`attach_failed` — the attachment could not be started; retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: '`attach_unavailable` — temporarily unavailable; retry shortly.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CardAttachment:
      type: object
      properties:
        object:
          type: string
          enum:
            - card_attachment
        id:
          type: string
          description: The attachment id.
        user_id:
          type: string
        status:
          type: string
          enum:
            - pending
            - active
            - ineligible
          description: >-
            `pending` — the user has not finished the attach link. `active` —
            attached; `create_card` now mints against this card. `ineligible` —
            this card cannot be attached; fall back to wallet funding +
            `create_card`.
        attach_url:
          type: string
          description: >-
            The hosted link the user opens to add their card. Present only on
            the start response.
        expires_at:
          type: string
          format: date-time
          description: >-
            When the attach link expires (48 hours). Present only on the start
            response.
        card:
          type: object
          description: >-
            Display details of the attached card. Present when status is
            `active`.
          properties:
            network:
              type: string
              nullable: true
            brand:
              type: string
              nullable: true
            last4:
              type: string
              nullable: true
            art_url:
              type: string
              nullable: true
        reason:
          type: string
          description: >-
            Why the card cannot be attached (e.g. `issuer_excluded`,
            `commercial_card`). Present when status is `ineligible`.
        message:
          type: string
          description: Human-readable guidance. Present when status is `ineligible`.
      required:
        - object
        - id
        - user_id
        - status
    Error:
      type: object
      description: Every v2 error uses the same envelope.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable, machine-readable string (snake_case). Branch on this.
            message:
              type: string
              description: A human-readable explanation, safe to log.
            docs:
              type: string
              description: A link back to the reference.
            field_errors:
              type: object
              additionalProperties:
                type: string
              description: Only on `invalid_fields` — names each field to fix.
            warnings:
              type: array
              items:
                type: string
              description: >-
                Only on document upload errors — actionable feedback safe to
                show the user.
  responses:
    Unauthorized:
      description: >-
        `unauthorized` — the platform access token is missing or expired.
        Exchange your client credentials for a fresh one.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ConnectionNotFound:
      description: >-
        `connection_not_found` — no connection exists for that user under your
        client.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UserConflict:
      description: >-
        `user_conflict` — the email on file in your organization belongs to a
        different account. Contact support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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.

````