> ## Documentation Index > Fetch the complete documentation index at: https://docs.carbn.xyz/llms.txt > Use this file to discover all available pages before exploring further. # User Onboarding > Create a new user with KYC information ## OpenAPI ````yaml /api-reference/openapi.json post /onboarding/api/v1/users openapi: 3.0.0 info: title: Carbn Connect API version: 1.0.0 description: >- API documentation for Carbn Connect services including user onboarding, KYC, wallet management, and transfers. servers: - url: https://api.carbnconnect.com description: Production server security: - ApiKeyAuth: [] paths: /onboarding/api/v1/users: post: tags: - User Management summary: User Onboarding description: Create a new user with KYC information operationId: userOnboarding requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UserOnboardingRequest' responses: '200': description: User created successfully content: application/json: schema: $ref: '#/components/schemas/UserDetailsResponse' '400': description: Invalid request '401': description: Unauthorized - API key is missing or invalid security: - ApiKeyAuth: [] components: schemas: UserOnboardingRequest: type: object required: - first_name - last_name - email_address - phone_number - user_type - date_of_birth - consent_id - sharing_consent - identity - address properties: first_name: type: string example: John last_name: type: string example: Doe email_address: type: string format: email example: user@example.com phone_number: type: string example: +1XXXXXXXXXX user_type: type: string enum: - individual example: individual date_of_birth: type: string format: date example: YYYY-MM-DD consent_id: type: string format: uuid example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx metadata: type: string example: '{}' sharing_consent: type: boolean example: true identity: type: object required: - identity_country_code - identity_number - identity_document_name - identity_document_front - identity_document_back properties: identity_country_code: type: string example: DEU identity_number: type: string example: XXXXXXXXXXXX identity_document_name: type: string enum: - national_id - drivers_license - passport - permanent_residency_id example: permanent_residency_id identity_document_front: type: string format: base64 example: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD... description: >- Front side of identity document in data URL format (data:image/jpeg;base64,...) identity_document_back: type: string format: base64 example: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD... description: >- Back side of identity document in data URL format (data:image/jpeg;base64,...) address: type: object required: - line1 - city - sub_division - country - postal_code properties: line1: type: string example: 123 Main Street city: type: string example: City Name sub_division: type: string example: ST description: >- The subdivision code depends on the country. Each country has its own set of valid subdivision codes. oneOf: - title: German subdivisions enum: - BB - BE - BW - BY - HB - HH - HE - MV - NI - NW - RP - SL - SN - ST - SH - TH description: Valid when country is DEU - title: USA subdivisions enum: - CA - WI description: Valid when country is USA - title: French subdivisions enum: - '01' - '02' - '03' - '04' - '05' - '06' - '07' - '08' - '09' - '10' - '11' - '12' - '13' - '14' - '15' - '16' - '17' - '18' - '19' - 20R - '21' - '22' - '23' - '24' - '25' - '26' - '27' - '28' - '29' - 2A - 2B - '30' - '31' - '32' - '33' - '34' - '35' - '36' - '37' - '38' - '39' - '40' - '41' - '42' - '43' - '44' - '45' - '46' - '47' - '48' - '49' - '50' - '51' - '52' - '53' - '54' - '55' - '56' - '57' - '58' - '59' - '60' - '61' - '62' - '63' - '64' - '65' - '66' - '67' - '68' - '69' - 69M - 6AE - '70' - '71' - '72' - '73' - '74' - 75C - '76' - '77' - '78' - '79' - '80' - '81' - '82' - '83' - '84' - '85' - '86' - '87' - '88' - '89' - '90' - '91' - '92' - '93' - '94' - '95' - '971' - '972' - '973' - '974' - '976' - ARA - BFC - BL - BRE - CP - CVL - GES - HDF - IDF - MF - NAQ - NC - NOR - OCC - PAC - PDL - PF - PM - TF - WF description: Valid when country is FRA - title: Belgian subdivisions enum: - BRU - VAN - VBR - VLG - VLI - VOV - VWV - WAL - WBR - WHT - WLG - WLX - WNA description: Valid when country is BEL - title: Dutch subdivisions enum: - AW - BQ1 - BQ2 - BQ3 - CW - DR - FL - FR - GE - GR - LI - NB - NH - OV - SX - UT - ZE - ZH description: Valid when country is NLD country: type: string example: DEU enum: - ABW - AFG - AGO - AIA - ALA - ALB - AND - ARE - ARG - ARM - ASM - ATA - ATF - ATG - AUS - AUT - AZE - BDI - BEL - BEN - BES - BFA - BGD - BGR - BHR - BHS - BIH - BLM - BLR - BLZ - BMU - BOL - BRA - BRB - BRN - BTN - BVT - BWA - CAF - CAN - CCK - CHE - CHL - CHN - CIV - CMR - COD - COG - COK - COL - COM - CPV - CRI - CUB - CUW - CXR - CYM - CYP - CZE - DEU - DJI - DMA - DNK - DOM - DZA - ECU - EGY - ERI - ESH - ESP - EST - ETH - FIN - FJI - FLK - FRA - FRO - FSM - GAB - GBR - GEO - GGY - GHA - GIB - GIN - GLP - GMB - GNB - GNQ - GRC - GRD - GRL - GTM - GUF - GUM - GUY - HKG - HMD - HND - HRV - HTI - HUN - IDN - IMN - IND - IOT - IRL - IRN - IRQ - ISL - ISR - ITA - JAM - JEY - JOR - JPN - KAZ - KEN - KGZ - KHM - KIR - KNA - KOR - KWT - LAO - LBN - LBR - LBY - LCA - LIE - LKA - LSO - LTU - LUX - LVA - MAC - MAF - MAR - MCO - MDA - MDG - MDV - MEX - MHL - MKD - MLI - MLT - MMR - MNE - MNG - MNP - MOZ - MRT - MSR - MTQ - MUS - MWI - MYS - MYT - NAM - NCL - NER - NFK - NGA - NIC - NIU - NLD - NOR - NPL - NRU - NZL - OMN - PAK - PAN - PCN - PER - PHL - PLW - PNG - POL - PRI - PRK - PRT - PRY - PSE - PYF - QAT - REU - ROU - RUS - RWA - SAU - SDN - SEN - SGP - SGS - SHN - SJM - SLB - SLE - SLV - SMR - SOM - SPM - SRB - SSD - STP - SUR - SVK - SVN - SWE - SWZ - SXM - SYC - SYR - TCA - TCD - TGO - THA - TJK - TKL - TKM - TLS - TON - TTO - TUN - TUR - TUV - TWN - TZA - UGA - UKR - UMI - URY - USA - UZB - VAT - VCT - VEN - VGB - VIR - VNM - VUT - WLF - WSM - YEM - ZAF - ZMB - ZWE description: Three-letter country code (ISO 3166-1 alpha-3) postal_code: type: string example: '12345' documents: type: array title: AdditionalDocuments description: >- Additional supporting documents for user onboarding. Can include various document types such as proof of address, source of funds, etc. minItems: 0 items: type: object required: - name - type - issuing_country - document_number properties: name: type: string example: steuer_id description: Document name - can be any document identifier type: type: string enum: - tax_document - proof_of_account_purpose - proof_of_address - proof_of_individual_name_change - proof_of_relationship - proof_of_source_of_funds - proof_of_source_of_wealth - proof_of_tax_identification - other example: tax_document issuing_country: type: string example: DEU document_number: type: string example: document_front: type: string format: base64 example: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD... description: >- Front side of the document in data URL format (data:image/jpeg;base64,...) document_back: type: string format: base64 example: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD... description: >- Back side of the document in data URL format (data:image/jpeg;base64,...) UserDetailsResponse: type: object properties: id: type: string format: uuid example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx description: Unique user identifier status: type: string enum: - under_review - active - rejected - offboarded - incomplete example: under_review description: >- Current user status. under_review: Initial status when user is created (default). active: User has been approved and verified. paused: User account is temporarily paused. rejected: User has been rejected during KYC process. offboarded: User has been removed/offboarded from the system. incomplete: User profile is missing required information. documents: type: array items: type: object properties: name: type: string example: national_id description: Document name/type type: type: string example: identity_front description: Document type description: List of uploaded documents (both identity and supporting documents) example: - name: national_id type: identity_front - name: national_id type: identity_back - name: steuer_id type: tax_document address: type: object properties: line1: type: string example: 123 Main Street description: Address line 1 line2: type: string nullable: true example: null description: Address line 2 (optional) city: type: string example: City Name description: City country: type: string example: DEU description: Country code (ISO 3166-1 alpha-3) region: type: string nullable: true example: null description: Region (optional) sub_division: type: string example: ST description: Sub-division/state code postal_code: type: string example: '12345' description: Postal code first_name: type: string example: John description: User's first name last_name: type: string example: Doe description: User's last name email_address: type: string format: email example: user@example.com description: User's email address phone_number: type: string example: +1XXXXXXXXXX description: User's phone number date_of_birth: type: string format: date example: YYYY-MM-DD description: User's date of birth rejection_reasons: type: array items: type: object properties: reason: type: string example: Your information could not be verified description: >- Customer-facing rejection reason that can be safely shared with users created_at: type: string format: date-time example: '2025-09-09T11:46:22.037Z' description: Timestamp when the rejection reason was recorded developer_reason: type: string example: ID cannot be verified against third-party databases description: >- Internal reason for developers only (may contain sensitive information) nullable: true example: null description: >- Array of rejection reason objects (only populated for rejected users, null otherwise). Each object contains customer-facing reason, timestamp, and internal developer reason. requirements: type: array items: type: string nullable: true example: null description: >- List of missing requirements for incomplete users (null when no requirements are missing) securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for authentication. Must be included in the x-api-key header. ````