Skip to main content
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

User has passed verification and can begin transacting. All required documents have been approved and the user is ready to use all platform features.Key Characteristics:
  • All KYC checks completed successfully
  • User can initiate transactions
Verification is in progress. Our compliance team is reviewing the submitted documents. This typically takes 2-5 minutes for automated approval.Key Characteristics:
  • Initial status when user is created
  • Documents are being processed
  • Automated checks in progress
  • User should wait for status update
Verification failed due to document or data issues. The rejection_reasons array contains detailed rejection objects with user-safe messages, timestamps, and internal developer reasons.Key Characteristics:
  • KYC verification failed
  • rejection_reasons array populated with detailed objects
  • Each rejection includes reason, created_at, and developer_reason
  • User needs to resubmit with corrections
Only share the reason field with end users. The developer_reason may contain sensitive information.
Missing required information or documents. The requirements field lists what’s needed to complete the user profile.Key Characteristics:
  • User profile is missing required data
  • requirements array shows what’s needed
  • User must provide additional information
  • Status will change once requirements are met
Next Steps:
  • Use the PUT /onboarding/api/v1/users/{user_id} endpoint to update user details
  • Provide the missing information listed in the requirements array
  • Include any additional documents or data needed

​
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