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

# Upload KYC documents

> Upload identity documents (government ID, selfie) for a customer.

**Document requirements:**
- Formats: JPEG, PNG
- Max size: 10MB per image
- Required documents: `id_front`, `id_back` (if applicable), `selfie`
- Encoding: Base64

Submit documents using the `documentType` field:
- `document`: For government ID images (front and back)
- `selfie`: For selfie verification photo

Submitted documents will be reviewed by Etherfuse admins before approval.
You'll receive a `kyc_updated` webhook when the status changes.

**Sandbox auto-approval:** In sandbox, uploading documents for a `personal` customer org
immediately approves the customer and fires a `kyc_updated` webhook. The response
`status` returns `"approved"` (not `"proposed"`). This shortcut is sandbox-only —
production still requires manual review.




## OpenAPI

````yaml /openapi.yaml post /ramp/customer/{customer_id}/kyc/documents
openapi: 3.1.0
info:
  title: FX API
  version: 1.0.0
  description: >
    API for managing FX operations including onboarding, quotes, orders, and
    customer management.

    This API provides endpoints for managing customers, bank accounts, crypto
    wallets, orders, and webhooks.
servers:
  - url: https://api.etherfuse.com
    description: Production API
  - url: https://api.sand.etherfuse.com
    description: Sandbox API (for testing)
security: []
tags:
  - name: Lookup
    description: Public endpoints for looking up stablebond and exchange rate data
  - name: Assets
    description: Get available assets for ramping
  - name: Onboarding
    description: Customer onboarding and KYC
  - name: Bank Accounts
    description: Manage customer bank accounts
  - name: Agreements
    description: Handle customer agreements and consents
  - name: Quotes
    description: Get quotes for conversions
  - name: Orders
    description: Create and manage orders
  - name: Swaps
    description: Create and manage swaps
  - name: Customers
    description: Manage customers
  - name: Crypto Wallets
    description: Manage crypto wallets
  - name: Webhooks
    description: Manage webhook subscriptions
  - name: Organizations
    description: Manage organizations and child organizations
paths:
  /ramp/customer/{customer_id}/kyc/documents:
    post:
      tags:
        - KYC
      summary: Upload KYC documents
      description: >
        Upload identity documents (government ID, selfie) for a customer.


        **Document requirements:**

        - Formats: JPEG, PNG

        - Max size: 10MB per image

        - Required documents: `id_front`, `id_back` (if applicable), `selfie`

        - Encoding: Base64


        Submit documents using the `documentType` field:

        - `document`: For government ID images (front and back)

        - `selfie`: For selfie verification photo


        Submitted documents will be reviewed by Etherfuse admins before
        approval.

        You'll receive a `kyc_updated` webhook when the status changes.


        **Sandbox auto-approval:** In sandbox, uploading documents for a
        `personal` customer org

        immediately approves the customer and fires a `kyc_updated` webhook. The
        response

        `status` returns `"approved"` (not `"proposed"`). This shortcut is
        sandbox-only —

        production still requires manual review.
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KycDocumentUploadRequest'
      responses:
        '200':
          description: Documents uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: proposed
                  message:
                    type: string
                    example: Documents uploaded for review
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    KycDocumentUploadRequest:
      type: object
      description: Request body for uploading KYC identity documents
      required:
        - documentType
        - images
      properties:
        pubkey:
          type: string
          description: >-
            Public key of the wallet to upload documents for. Optional — if
            omitted, documents are attached at the organization level.
        documentType:
          type: string
          enum:
            - document
            - selfie
          description: Type of document being uploaded (government ID or selfie photo)
        images:
          type: array
          description: Array of images as data URLs (JPEG or PNG, max 10MB each)
          items:
            type: object
            required:
              - label
              - image
            properties:
              label:
                type: string
                description: Label for the image (e.g., "id_front", "id_back", "selfie")
              image:
                type: string
                description: >-
                  Data URL containing base64-encoded image (e.g.,
                  "data:image/jpeg;base64,/9j/4AAQ...")
      example:
        pubkey: 9Qx7r...
        documentType: document
        images:
          - label: id_front
            image: data:image/jpeg;base64,/9j/4AAQSkZJRg...
          - label: id_back
            image: data:image/jpeg;base64,/9j/4AAQSkZJRg...
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example:
        error: Invalid request parameters
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key for authentication. Pass the key directly (e.g., `Authorization:
        your-api-key`). Do not use a `Bearer` prefix.

````