Create a customer

0Gate is the primary public integration path for hosted payment, ramp, and swap experiences. Keep secret-key operations on your server and hand only browser-safe values to the widget.

A customer is your own CRM-style reference for an end user: an email plus optional contact fields and free-form metadata. It is a partner-scoped identity record you create and manage, not the KYC-verified 0Bit user identity. Use it to keep a stable handle for a person across sessions, transactions, and support.

Endpoint

Use it for

Create a partner-scoped customer record for an end user and get back its 0Bit id to store against your own user. Send your own reference as external_id so you can look the customer up later without storing the 0Bit id.

This is a standard identity write (CRM-style), not a privacy-minimized KYC view. The fields you send are the contact details you choose to keep — there is no document, screening, or verification payload involved.

Production rules

• Keep secret keys on your server. This endpoint requires an sk_* key. Never call it from a browser with a publishable pk_* key.
• Send an Idempotency-Key for the write and reuse the same key when you retry a timeout — a repeat collapses to the original response instead of creating a second customer.
• email is unique per partner, and external_id is unique per partner when supplied. A duplicate of either is a 409 with code customer_already_exists — branch on it rather than retrying.
• Validate external_id, phone, and country_code formats before the call to avoid a 400.
• Store the returned id, your external_id, the request id, and timestamps so support and reconciliation do not depend on browser callbacks alone.
• Treat examples and placeholder ids as fake data only.

Headers

Request body

Response

Returns 201 with the created customer object.

Customer object

Examples

curl -X POST https://gate-api.0bit.app/v1/customers \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 7f9c2b1e-0000-4a00-8000-000000000123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jordan@example.com",
    "external_id": "user_42",
    "phone": "+447700900000",
    "first_name": "Jordan",
    "last_name": "Doe",
    "country_code": "GB",
    "metadata": { "plan": "pro" }
  }'

{
  "id": "67a1f3b9e4b0c10001234567",
  "object": "customer",
  "partner_id": "ptnr_test_000000000001",
  "mode": "test",
  "livemode": false,
  "external_id": "user_42",
  "email": "jordan@example.com",
  "phone": "+447700900000",
  "first_name": "Jordan",
  "last_name": "Doe",
  "country_code": "GB",
  "kyc_status": "unverified",
  "metadata": { "plan": "pro" },
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

{
  "type": "conflict",
  "code": "customer_already_exists",
  "message": "A customer with email \"jordan@example.com\" already exists",
  "request_id": "req_test_000000000123",
  "doc_url": null,
  "statusCode": 409
}

Errors

All errors use the unified envelope and carry an X-Request-Id response header. Branch on code/type/statusCode, not on the free-form message.

{
  "type": "invalid_request",
  "code": "invalid_request",
  "message": "Example validation error using fake data.",
  "request_id": "req_test_000000000123",
  "doc_url": null,
  "statusCode": 400
}

Public boundary

This reference covers partner-scoped endpoint behavior, authentication, idempotency, webhook verification, and support-safe records. Internal operations, administrative routes, and unsupported availability claims are outside the public API contract.

Related pages