Users

Users are a core part of the Coba API — they represent the individuals or entities that interact with your application. On this page, you’ll find everything you need to create and manage users programmatically.

The user model

The user model contains all the information about a user registered through the Coba API. It includes details such as the name, email, phone number, and status. Users can be individuals or businesses.

Each user is immutable once created, but their status can change based on interactions with your application.

Properties

Name
id
Type
string
Description
The unique identifier of the user. Sample: 68811830bb6e5d659501e1e8
Name
status
Type
string
Description
The current onboarding status for the user: ['onboarding', 'review', 'approved']

POST/users

1. Create a user

This endpoint allows you to create a new user.

Required attributes

Name
country
Type
string
Description
The country of the user. One of: MX, PE
Name
email
Type
string
Description
The email address of the user.
Name
phone_number
Type
string
Description
The phone number of the user, including country code. Sample: +528111235654
Name
user_type
Type
enum<string>
Description
The type of user being created. One of: individual or business.
Name
address
Type
object
Description
The address of the user.
Name
address.street1
Type
string
Description
The street address of the user.
Name
address.city
Type
string
Description
The city of the user.
Name
address.state
Type
string
Description
The state of the user.
Name
address.postal_code
Type
string
Description
The ZIP code of the user.
Name
address.country
Type
string
Description
The country of the user.
Name
address.street2
Type
string
Description
Secondary street address of the user, if applicable.
Name
first_name
Type
string
Description
The first name of the user. Required for individual type users.
Name
middle_name
Type
string
Description
The middle name of the user.
Name
last_name
Type
string
Description
The last name of the user. Required for individual type users.
Name
second_last_name
Type
string
Description
The second last name of the user.
Name
business_name
Type
string
Description
The name of the buiness. Required for business type users.
Name
additional_information
Type
enum<string>
Description
Additional information about the user, such as their tax ID or business registration number.
Name
additional_information.taxpayer_id
Type
string
Description
The tax ID of the user, if applicable.
Name
additional_information.curp
Type
string
Description
The CURP of the user, if applicable.
Name
additional_information.date_of_incorporation
Type
string
Description
This is the date when the entity was officially registered with the country's tax authority. It’s the date the company was legally formed and registered for tax purposes.
Name
additional_information.expected_monthly_transactional_volume
Type
string
Description
Estimated Monthly Transaction Volume
Name
additional_information.platform_usage_reason
Type
string
Description
A detailed description of the reason for using the platform, including the nature of the business activities and how the platform will be used.
For users of type individual, the client application must display the following declaration to the user and require explicit acceptance. Once accepted, the exact text below must be sent as the value of platform_usage_reason:
Declaro que el motivo de mi relación comercial con la plataforma es únicamente realizar operaciones de on-ramp y off-ramp de stablecoins. Asimismo, declaro que los fondos que serán operados a través de la plataforma provienen exclusivamente de mi actividad económica lícita, y que yo soy el beneficiario final (UBO) de dichas transacciones y de los recursos involucrados, sin actuar en nombre ni por cuenta de terceros.
Name
additional_information.source_of_funds
Type
string
Description
A description of the origin and nature of the funds that will be operated through the platform.

Request

POST

/users

curl -X POST https://sandbox.api.coba.ai/metal/users \
  -H "Authorization: Bearer {token}" \
  -H "X-Coba-Metal-API-Key: {client_api_key}" \
  -d '{
    "user": {
      "country": "MX",
      "first_name": "John",
      "middle_name": "Michael",
      "last_name": "Doe",
      "second_last_name": "Smith",
      "email": "john.doe@example.com",
      "phone_number": "+528111235654",
      "user_type": "individual",
      "address": {
        "street1": "123 Main St",
        "street2": "Apt 4B",
        "city": "Mexico City",
        "state": "CDMX",
        "postal_code": "64000",
        "country": "MX"
      },
      "additional_information": {
        "taxpayer_id": "ACME12345YR2",
        "curp": "GODE561231HDFRRN04",
        "date_of_incorporation": "2015-01-01",
        "expected_monthly_transactional_volume": "10,000 USD",
        "platform_usage_reason": "Declaro que el motivo de mi relación comercial con la plataforma es únicamente realizar operaciones de on-ramp y off-ramp de stablecoins. Asimismo, declaro que los fondos que serán operados a través de la plataforma provienen exclusivamente de mi actividad económica lícita, y que yo soy el beneficiario final (UBO) de dichas transacciones y de los recursos involucrados, sin actuar en nombre ni por cuenta de terceros.",
        "source_of_funds": "Funds originate from business income, including payments received from customers for goods and services."
      }
    }
  }'

Successful Response

{
  "id": "68811830bb6e5d659501e1e8",
  "status": "onboarding"
}

POST/users/:id/additional_information

2. Add additional information to a user (if necessary)

This endpoint allows you to add additional information to an existing user. This is useful for providing more context about the user, such as their tax ID or business registration number.

You can call this endpoint after creating a user to provide additional information that may be required for compliance or business purposes.

Note: the information you provide won't be overwritten. If you need to update any of the additional information, you may need to added with a different key name

Required attributes

Name
additional_information
Type
object
Description
Additional information about the user.

Request

POST

/users/:id/additional_information

curl -G https://sandbox.api.coba.ai/metal/users/:id/additional_information \
  -H "Authorization: Bearer {token}" \
  -H "X-Coba-Metal-API-Key: {client_api_key}" \
  -d '{
    "additional_information": {
        "rfc": "ACME12345YR2",
        "curp": "ACME1234567890"
    }
  }'

Response

Status 204 No Content

POST/users/:id/documents

3. Upload Document

This endpoint allows you to upload a document for an existing user. This is useful for providing more context about the user, such as their tax ID or business registration number.

You can call this endpoint as many times as needed to upload different documents for the same user.

Required documents for user onboarding

ID (passport, INE, drivers license, etc)

Proof of address (issued within the last 3 months)

Tax Compliance Certificate / Constancia de Situación Fiscal (issued within the last 3 months)

Documents supporting economic activity (Payroll receipts, invoices or the most recent tax returns)

Articles of Incorporation / Acta Constitutiva (required only for business users)

Required attributes

Name
document
Type
base64 string
Description
Document to upload in base64, including content type (PDF, JPG, PNG).
Name
document_type
Type
string
Description
The type of document being uploaded.

Request

POST

/users/:id/documents

curl -X POST https://sandbox.api.coba.ai/metal/users/:id/documents \
  -H "Authorization: Bearer {token}" \
  -H "X-Coba-Metal-API-Key: {client_api_key}" \
  -d '{
    "document_type": "id_card",
    "document": "data:image/png;base64,iVBORw0KGgoAAAANSUh..."
  }'

Response

Status 204 No Content

POST/users/:id/terms/accept

4. Accept terms and conditions

This endpoint allows you to accept the terms and conditions for an existing user.

Request

POST

/users/:id/terms/accept

curl -X POST https://sandbox.api.coba.ai/metal/users/:id/terms/accept \
  -H "Authorization: Bearer {token}" \
  -H "X-Coba-Metal-API-Key: {client_api_key}"

Response

Status 204 No Content

POST/users/:id/review

5. Request Review

This endpoint allows you to request a review for an existing user.

Request

POST

/users/:id/review

curl -X POST https://sandbox.api.coba.ai/metal/users/:id/review \
  -H "Authorization: Bearer {token}" \
  -H "X-Coba-Metal-API-Key: {client_api_key}"

Response

Status 204 No Content

GET/users/:id

6. Get a user

This endpoint allows you to get an existing user and it's current onboarding status.

Name
id
Type
string
Description
The unique identifier of the user. Sample: 68811830bb6e5d659501e1e8
Name
status
Type
string
Description
The current onboarding status for the user: ['onboarding', 'review', 'approved']

Request

POST

/users/:id/review

curl -X GET https://sandbox.api.coba.ai/metal/users/:id \
  -H "Authorization: Bearer {token}" \
  -H "X-Coba-Metal-API-Key: {client_api_key}"

Successful Response

{
  "id": "68811830bb6e5d659501e1e8",
  "status": "approved"
}