Customers

Creates a customer record and registers them with our banking partner. This does not start verification — the customer stays pending until you upload an identity document (see Upload identity documents and the optional Submit KYC acknowledgement below). Requires an Idempotency-Key header — use a unique value (UUID) per logical create.

Idempotency & retries

A customer_reference is unique per merchant per env. Creating again with the same customer_reference does not create a duplicate:

• If the prior attempt was rejected by verification, the same customer_reference is refreshed with your new body and re-submitted (the customer id stays stable for audit).
• If a prior attempt succeeded, you get the existing customer back.

On a transient provider error (HTTP 502, retry_safe: true in the error detail), retry with the same customer_reference + a fresh Idempotency-Key — the orphan-replay flow resumes from your existing record. On a validation rejection (422), fix the offending field and retry — you may reuse the same customer_reference (the failed record was discarded) with a fresh Idempotency-Key. A validation 422 does not return a customer_id (the half-created row was rolled back).

Errors

Create response

For individual customers returned as pending, the create response adds a next_action and a requirements hint pointing at the document-upload steps — so it’s clear an identity document must be uploaded before verification can start. These fields are purely additive; the base customer fields are unchanged, and they’re absent for business customers (and on list / retrieve / idempotent-replay responses).

{
  "object": "customer",
  "id": "cus_...",
  "status": "pending",
  "next_action": "upload_identity_document",
  "requirements": {
    "identity_document": {
      "required": true,
      "reason": "Verification has not started. Upload an identity document to begin.",
      "steps": [
        "POST /api/v1/customers/{id}/files with { file_category: \"identity\", content_type } to get an upload URL",
        "PUT the file bytes to the returned upload_url, echoing required_headers verbatim (server-side; the URL is not browser-CORS-enabled)",
        "POST /api/v1/customers/{id}/files/attach with { id_file: <file_id> } to attach it and start verification"
      ]
    }
  }
}

Returns a Stripe-style list of customer objects. Use q to answer “did my user X get provisioned here?”.

Returns the customer object.

Narrow scope — contact + address fields only. Identity fields (id_type, id_number, name) are immutable after submission; to correct those, create a new customer with a new customer_reference.

Returns the updated customer object with the latest verification status.

Optional — this endpoint does not start verification, and you can safely skip it.

For individual customers (type: individual — the customer flow this API serves), verification is document-triggered: it begins automatically the moment you attach an identity document (id_file) — see Upload identity documents below. There is no separate KYC submit for individuals. This /kyc call simply records kycSubmittedAt (and stores any supplemental KYC details you pass) as a clean audit acknowledgement — it is never required for verification to happen.

Business / KYB customers verify differently. A business is onboarded with Technest directly — beneficial owners plus business documents, reviewed in roughly 1–5 business days — a separate process not driven by this endpoint (and not self-serve via this API today). See Individual vs business.

status reflects the partner’s verification state. Verification completes asynchronously (a few minutes, up to ~2h). Watch the customer.status_changed webhook for the transition to verified / rejected, or re-read the customer — status also refreshes from the banking partner on read.

Two steps — request a signed upload URL, then PUT the file bytes directly:

1. Request an upload URL — POST /v1/customers/{id}/files with the document slot (file_category) and the file’s content_type (e.g. image/jpeg, application/pdf). Returns a file_upload object with a signed upload_url and the required_headers you must echo (these now include the Content-Type for your file).

2. PUT the bytes to upload_url with the required_headers verbatim, from your backend. Do not send your Bearer token — the signed URL authorizes the upload itself.

3. Attach the uploaded file — POST /v1/customers/{id}/files/attach, mapping file_ids to typed document slots (e.g. id_file).

Issues a dedicated international virtual account for a verified customer in one of the supported currencies.

The call is idempotent per (customer, currency) — only one virtual account exists per customer per currency. List a customer’s issued accounts with GET /v1/customers/{id}/virtual_accounts.

A unified, audit-grade history of everything attributed to one customer — collections (money received into their international account) and payouts (money sent on their behalf), merged into one time-ordered feed.

Field reference