Upload KYC docs

curl --request POST \
  --url https://api.sand.etherfuse.com/ramp/customer/{customer_id}/kyc/documents \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentType": "document",
  "images": [
    {
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
      "label": "id_front"
    },
    {
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
      "label": "id_back"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    documentType: 'document',
    images: [
      {image: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...', label: 'id_front'},
      {image: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...', label: 'id_back'}
    ]
  })
};

fetch('https://api.sand.etherfuse.com/ramp/customer/{customer_id}/kyc/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sand.etherfuse.com/ramp/customer/{customer_id}/kyc/documents"

payload = {
    "documentType": "document",
    "images": [
        {
            "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
            "label": "id_front"
        },
        {
            "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
            "label": "id_back"
        }
    ]
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "message": "Documents uploaded for review",
  "status": "proposed"
}

KYC

Upload KYC docs

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

Document requirements:

Formats: JPEG, PNG
Max size: 10 MB total per request (the whole body, across all images), not per image
Required documents: id_front, id_back (if applicable), selfie
Encoding: Base64

Use the documentType field: document for government ID images (front and back), selfie for the selfie verification photo.

Submitted documents are reviewed by Etherfuse admins before approval; you’ll receive a kyc_updated webhook when the status changes.

Sandbox auto-approval: in sandbox, a personal customer auto-approves once all agreements have been signed, with no manual review. Uploading documents is a required step in the programmatic flow, but does not by itself approve the customer; approval lands after agreement signing, at which point a kyc_updated webhook fires. This is sandbox-only; production still requires manual review.

Authentication: use your partner API key. This is a server-side call and cannot be made from a browser.

documentType is document or selfie only. There is no proof_of_address type: the customer’s address comes from the identity submitted to POST /ramp/customer/{customer_id}/kyc, not from a document. Send document and selfie as separate requests; multiple images of the same type can share one request. Re-submitting a documentType appends new images and does not overwrite a prior upload.

Image handling: Etherfuse forwards your image bytes to the identity-verification provider as-is. Stripping EXIF or re-encoding is accepted on our side, but the provider’s OCR, face-match, and liveness checks run on those exact bytes, so lossy re-encoding or dropping EXIF orientation can degrade results. Forward originals when you can; if you must scrub metadata, do it losslessly and preserve orientation.

POST

ramp

customer

{customer_id}

kyc

documents

Upload KYC docs

curl --request POST \
  --url https://api.sand.etherfuse.com/ramp/customer/{customer_id}/kyc/documents \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentType": "document",
  "images": [
    {
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
      "label": "id_front"
    },
    {
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
      "label": "id_back"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    documentType: 'document',
    images: [
      {image: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...', label: 'id_front'},
      {image: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...', label: 'id_back'}
    ]
  })
};

fetch('https://api.sand.etherfuse.com/ramp/customer/{customer_id}/kyc/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sand.etherfuse.com/ramp/customer/{customer_id}/kyc/documents"

payload = {
    "documentType": "document",
    "images": [
        {
            "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
            "label": "id_front"
        },
        {
            "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
            "label": "id_back"
        }
    ]
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "message": "Documents uploaded for review",
  "status": "proposed"
}

Authorizations

Authorization

string

header

required

API key sent in the Authorization header.

Path Parameters

customer_id

string<uuid>

required

The customer (child org) ID. Must belong to the caller's organization or a direct child.

Body

application/json

Request body for uploading KYC document images. This endpoint is for document images only — identity fields (name, address, ID numbers, etc.) are submitted separately via Submit KYC.

documentType

enum<string>

required

The kind of image being uploaded: "document" for a government-issued ID, or "selfie" for a selfie/liveness photo.

Available options:

document,

selfie

images

object[]

required

The image(s) for this document. For a two-sided ID, upload the front and back as separate entries.

Show child attributes

Response

KYC documents uploaded

Get KYC status Create webhook

⌘I

User Authentication

Ramp API

Lookup API

Upload KYC docs

Authorizations

Path Parameters

Body

Response