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

# Simulate an outcome (test mode)

> **Test mode only.** Drives a test-mode verification to a chosen terminal outcome instantly — test verifications never complete on their own. The simulated verdict flows through the same status contract and fires the same `identity.verification.updated` webhook a real review produces, so your status handling and webhook consumer are exercised end to end. Requires a test-mode client credential; live tokens get `403 sandbox_only`.

## Why this exists

Test-mode verifications never complete on their own — there is no reviewer
behind them. This endpoint is the missing verdict: pick an outcome and the
verification reaches it instantly, through the same status contract and the
same `identity.verification.updated` webhook a real review produces.

| Outcome          | What your integration sees                                                                                                          |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `approved`       | Status flips to `approved` — the happy path.                                                                                        |
| `rejected`       | Terminal `rejected` with a `reason` — the failure state to surface to the user.                                                     |
| `requires_input` | A retryable bounce (`awaiting_documents` or `needs_information`, with a `reason`) — the "send new photos" loop your UI must handle. |

Pass a custom `reason` to see exactly how your UI renders a specific review
message. Re-simulating overwrites the previous outcome, so a single test user
can walk approved → rejected → approved without reconnecting.

Live tokens are refused with `403 sandbox_only`: live verifications are
decided by the identity provider.


## OpenAPI

````yaml openapi.json POST /api/v2/kyc/simulate
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/kyc/simulate:
    post:
      tags:
        - Identity verification
      summary: Simulate an outcome (test mode)
      description: >-
        **Test mode only.** Drives a test-mode verification to a chosen terminal
        outcome instantly — test verifications never complete on their own. The
        simulated verdict flows through the same status contract and fires the
        same `identity.verification.updated` webhook a real review produces, so
        your status handling and webhook consumer are exercised end to end.
        Requires a test-mode client credential; live tokens get `403
        sandbox_only`.
      operationId: kycSimulate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
                - outcome
              properties:
                user_id:
                  type: string
                  description: The connected user's id.
                outcome:
                  type: string
                  enum:
                    - approved
                    - rejected
                    - requires_input
                  description: >-
                    The verdict to apply. `approved` — verification succeeds.
                    `rejected` — terminal rejection. `requires_input` — a
                    retryable bounce asking for new document photos.
                reason:
                  type: string
                  maxLength: 300
                  description: >-
                    Optional end-user-safe explanation carried on non-approved
                    outcomes — it appears as `reason` in statuses and webhook
                    events, exactly like a real review's. It must not name
                    internal providers or identifiers (rejected with `400
                    invalid_reason`), since it is shown to end users verbatim.
            example:
              user_id: user_7g8h9i
              outcome: rejected
              reason: The name on the document does not match the application.
      responses:
        '200':
          description: >-
            The verification's new state, exactly as `GET /api/v2/kyc` now
            reports it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycState'
              example:
                object: kyc
                simulated: true
                status: rejected
                reason: The name on the document does not match the application.
        '400':
          description: >-
            `invalid_request` — missing `user_id` or an unknown `outcome`.
            `invalid_reason` — the `reason` names an internal provider or
            identifier (it is shown to end users verbatim).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            `sandbox_only` — the token is a live credential. Live verifications
            are decided by the identity provider and cannot be simulated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: sandbox_only
                  message: >-
                    Simulated verification outcomes only exist in test mode.
                    Live verifications are decided by the identity provider.
        '404':
          $ref: '#/components/responses/ConnectionNotFound'
        '409':
          $ref: '#/components/responses/UserConflict'
        '502':
          $ref: '#/components/responses/VerificationError'
components:
  schemas:
    KycState:
      type: object
      description: The single status contract every KYC response carries.
      properties:
        object:
          type: string
          enum:
            - kyc
        status:
          type: string
          enum:
            - awaiting_documents
            - needs_information
            - requires_verification
            - pending
            - approved
            - rejected
          description: >-
            `awaiting_documents` — upload the front and back.
            `needs_information` — collect the `required_fields` and submit them.
            `requires_verification` — show the user the `iframe_url`. `pending`
            — under review, no action needed. `approved` — verified, done.
            `rejected` — the user did not pass. Statuses are not one-way: a
            review can send a user back — `pending` may return to
            `needs_information` (a detail didn't match the document; re-collect
            the listed fields and resubmit, the check re-runs automatically) or
            to `awaiting_documents` (the images were unusable; upload both sides
            again). Always branch on the current status.
        required_fields:
          type: array
          items:
            type: string
          description: >-
            Only on `needs_information` — exactly the fields to collect and post
            to `/kyc/information`.
        iframe_url:
          type: string
          description: >-
            Only on `requires_verification` — the URL to show the user for the
            face scan. Embed it in an iframe with `allow="camera; microphone"`.
            Short-lived: always use the most recent one from a poll or webhook,
            never a stored copy.
        warnings:
          type: array
          items:
            type: string
          description: >-
            Optional, on document uploads — actionable feedback safe to show the
            user (for example, that the other side of the document is still
            needed).
        extracted:
          type: object
          description: >-
            Optional, on document uploads — what the document reader pulled off
            the uploaded image(s), so you can prefill your details form instead
            of asking the user to re-type what the ID already says. Keys match
            the `/kyc/information` request fields (`first_name`, `last_name`,
            `date_of_birth`, `address_line1`, `address_city`, `address_region`,
            `address_postal_code`, `address_country`) plus `document_type`,
            `issuing_country`, and `document_number` (the number printed on the
            document — for US documents this is NOT the SSN, so never prefill it
            into `national_id_number` when `issuing_country` is `US`). Fields
            appear as they become readable: the front usually carries the name
            and date of birth; a US back adds the barcode address. Always let
            the user confirm or correct prefilled values.
          additionalProperties:
            type: string
        reason:
          type: string
          description: >-
            Optional, on `needs_information`, `awaiting_documents`,
            `requires_verification`, and `rejected` — a short, end-user-safe
            explanation of what the review asked for (for example, “Enter your
            full name exactly as it appears on your identity document.”). Safe
            to show the user verbatim.
    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'
    VerificationError:
      description: '`verification_error` — the step failed downstream. Try again.'
      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.

````