This guide walks you through Carbn’s two-step user onboarding process: first generating user consent, then creating the verified user profile.

​
Understanding User Types

Carbn supports two primary user types:
  • Individual Users: Personal accounts requiring identity verification and consent
  • Business Users: Corporate accounts requiring business verification and beneficial ownership details

​
Step-by-Step Onboarding

1

Generate User Consent

Before creating a user, you must first generate a consent record. This captures the user’s acceptance of terms and conditions and generates a consent ID that’s required for user creation.User consent is a critical compliance requirement that:
  • Legal Protection: Establishes clear user agreement to terms of service
  • Regulatory Compliance: Meets KYC/AML requirements for financial services
  • Audit Trail: Creates verifiable record of user consent with timestamps
  • Risk Management: Ensures users understand their obligations and rights
  • User must actively accept current terms and conditions
  • Timestamp must be recorded at time of acceptance
  • Consent must be obtained before any user data processing
The user must be shown a clear message where they consent to accept the terms and conditions during onborading.
curl --location --request POST 'https://api.carbnconnect.com/onboarding/api/v1/tnc' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your-api-key>' \
--data-raw '{
  "tnc_data": {
    "tnc_accepted": true,
    "accepted_at": "2024-01-01T12:00:00Z"
  }
}'

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
The response is a unique consent ID (UUID) that you’ll use in the next step. Store this securely as it’s required for user creation.
  • Required Parameter: The consent ID is mandatory for all user creation requests
  • Compliance Link: Connects user profiles to their consent records
  • Audit Trail: Enables tracking of consent to user relationship
  • Legal Requirement: Proves user agreed to terms before account creation
2

Create User Profile

Now create the user profile using the consent ID from the previous step. This establishes the user’s identity within the Carbn network and links them to their consent record.

​
Understanding Document Types

The user creation request includes two distinct document categories:
  • Identity Documents (identity object): Primary identification documents like national ID, passport, or driver’s license that prove the user’s identity
  • Supporting Documents (documents array): Additional documents that support the user’s profile, such as proof of address, tax documents, or source of funds verification
Make sure to use the consent_id from previous step in your request.
curl --location --request POST 'https://api.carbnconnect.com/onboarding/api/v1/users' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your-api-key>' \
--header 'Idempotency-Key: <generate-a-uuid>' \
--data-raw '{
  "first_name": "John",
  "last_name": "Doe",
  "email_address": "john.doe@example.com",
  "phone_number": "+1234567890",
  "user_type": "individual",
  "date_of_birth": "1990-01-01",
  "consent_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "metadata": "{}",
  "sharing_consent": true,
  "identity": {
    "identity_country_code": "DEU",
    "identity_number": "XXXXXXXXXXXX",
    "identity_document_name": "permanent_residency_id",
    "identity_document_front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
    "identity_document_back": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
  },
  "documents": [
    {
      "name": "steuer_id",
      "type": "tax_document",
      "issuing_country": "DEU",
      "document_number": "<string>",
      "document_front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
      "document_back": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
    }
  ],
  "address": {
    "line1": "123 Main Street",
    "city": "City Name",
    "sub_division": "ST",
    "country": "DEU",
    "postal_code": "12345"
  }
}'

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "under_review",
  "documents": [
    {
      "name": "national_id",
      "type": "identity_front"
    },
    {
      "name": "national_id", 
      "type": "identity_back"
    },
    {
      "name": "steuer_id",
      "type": "tax_document"
    }
  ],
  "first_name": "John",
  "last_name": "Doe",
  "email_address": "john.doe@example.com",
  "phone_number": "+1234567890",
  "date_of_birth": "1990-01-01",
  "address": {
    "line1": "123 Main Street",
    "city": "City Name",
    "sub_division": "ST",
    "country": "DEU",
    "postal_code": "12345"
  },
  "rejection_reasons": null,
  "requirements": null
}

​
Checking User Status

After creating a user, you can retrieve their current status and details using the GET user endpoint. This endpoint returns the exact same response format as the create and update user endpoints. 
curl --location --request GET 'https://api.carbnconnect.com/onboarding/api/v1/users/{user_id}' \
--header 'x-api-key: <your-api-key>'

​
Understanding User Status Values

The response will include a status field that indicates the current state of the user’s verification: 
{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "active",
  "documents": [
    {
      "name": "national_id",
      "type": "identity_front"
    },
    {
      "name": "national_id", 
      "type": "identity_back"
    },
    {
      "name": "steuer_id",
      "type": "tax_document"
    }
  ],
  "first_name": "John",
  "last_name": "Doe",
  "email_address": "john.doe@example.com",
  "phone_number": "+1234567890",
  "date_of_birth": "1990-01-01",
  "address": {
    "line1": "123 Main Street",
    "city": "City Name",
    "sub_division": "ST",
    "country": "DEU",
    "postal_code": "12345"
  },
  "rejection_reasons": null,
  "requirements": null
}

​
Status Explanations

active

​
Updating User Information

If a user needs to update their information (due to rejection or incomplete status), use the PUT endpoint to modify their details: 
curl --location --request PUT 'https://api.carbnconnect.com/onboarding/api/v1/users/{user_id}' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your-api-key>' \
--data-raw '{
  "identity": {
    "identity_document_front": "data:image/jpeg;base64,NEW_FRONT_IMAGE...",
    "identity_document_back": "data:image/jpeg;base64,NEW_BACK_IMAGE..."
  },
  "documents": [
    {
      "name": "steuer_id",
      "type": "tax_document",
      "issuing_country": "DEU",
      "document_number": "NEW_DOCUMENT_NUMBER",
      "document_front": "data:image/jpeg;base64,NEW_DOC_FRONT...",
      "document_back": "data:image/jpeg;base64,NEW_DOC_BACK..."
    }
  ]
}'
The PUT endpoint accepts the same fields as the POST endpoint, but all fields are optional. Only include the fields you want to update. The response format is identical to the GET and POST endpoints.

​
What’s Next?

After successfully onboarding your first user, here are the essential topics to master:

Rejection Reasons

Understand all possible rejection reasons and how to handle them effectively

Enhanced Due Diligence

Learn about additional verification requirements for high-risk users

Understanding Compliance

Deep dive into KYC/AML requirements and regulatory compliance

Setup Webhook

Configure real-time notifications for user status changes and events

​
Getting Help

Contact Support

When contacting support, please include:
User ID from the response
Endpoint you were trying to access
Error response details available
Timestamp when the error occurred