> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincode.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Customer

> Register a new customer account in the FinCode platform

Create a new customer account with personal information and authentication credentials.

Customers can access self-service features including sending remittances, applying for loans, and managing investments.

## Password Encryption

<Warning>
  **Security Requirement**: The `password` and `confirmPassword` fields can optionally be encrypted using RSA public key encryption before sending to the API.
</Warning>

When registering customers, you can choose to encrypt password fields using the RSA public key provided on your dashboard. Encryption ensures data confidentiality during transmission.

### Customer Registration Flow

The `payloadEncrypted` field determines how the system processes your payload:

| Value   | Description                                                                           |
| ------- | ------------------------------------------------------------------------------------- |
| `true`  | Indicates payload is RSA-encrypted. The system will decrypt before processing.        |
| `false` | Indicates payload is sent as raw plaintext. Use only for testing or internal systems. |

<Tip>
  For production integrations, use `payloadEncrypted` with encrypted passwords to protect customer credentials.
</Tip>

<Card title="Encryption Keys & Tokens" icon="lock" href="/integration/encryption-keys-and-tokens">
  Learn how to encrypt passwords using RSA public key encryption with OAEP padding (SHA-256).
</Card>

## Request Headers

| Header         | Type   | Required | Description                          |
| -------------- | ------ | -------- | ------------------------------------ |
| `Content-Type` | string | Yes      | Must be `application/json`           |
| `platform`     | string | Yes      | Platform identifier. Use `fincode`   |
| `uuid`         | string | Yes      | Unique request identifier. Use `200` |

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  const axios = require('axios');
  const crypto = require('crypto');

  // Encrypt password using RSA public key
  function encryptPassword(password, publicKeyBase64) {
    const publicKeyPem = `-----BEGIN PUBLIC KEY-----\n${publicKeyBase64}\n-----END PUBLIC KEY-----`;

    const encrypted = crypto.publicEncrypt(
      {
        key: publicKeyPem,
        padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
        oaepHash: 'sha256',
      },
      Buffer.from(password, 'utf8')
    );

    return encrypted.toString('base64');
  }

  async function createCustomer(customerData, publicKey) {
    // Encrypt passwords before sending
    const encryptedPassword = encryptPassword(customerData.password, publicKey);

    try {
      const response = await axios.post(
        'https://agent.fincode.software/api/v6/services/usermanagement/register-customer',
        {
          devicePlatform: customerData.devicePlatform,
          appVersion: customerData.appVersion,
          appId: customerData.appId,
          customerType: customerData.customerType,
          payloadEncrypted: true, // Required for encrypted data
          firstName: customerData.firstName,
          lastName: customerData.lastName,
          email: customerData.email,
          address: {
            street: customerData.address.street,
            city: customerData.address.city,
            state: customerData.address.state,
            postalCode: customerData.address.postalCode,
            country: customerData.address.country,
          },
          dialingCode: customerData.dialingCode,
          phone: customerData.phone,
          dob: customerData.dob,
          password: encryptedPassword,
          confirmPassword: encryptedPassword,
          dynamicFields: customerData.dynamicFields || {},
        },
        {
          headers: {
            'Content-Type': 'application/json',
            platform: 'fincode',
            uuid: '200',
          },
        }
      );

      console.log('Customer created successfully!');
      console.log('Customer ID:', response.data.customerId);

      return response.data;
    } catch (error) {
      console.error(
        'Failed to create customer:',
        error.response?.data || error.message
      );
      throw error;
    }
  }

  ```

  ```bash cURL (Encrypted Password) theme={null}
  curl -X POST "https://agent.fincode.software/api/v6/services/usermanagement/register-customer" \
    -H "Content-Type: application/json" \
    -H "platform: fincode" \
    -H "uuid: 200" \
    -d '{
      "devicePlatform": "Android",
      "appVersion": "1",
      "appId": "com.app.remit_junction",
      "customerType": "INDIVIDUAL",
      "customerRegistrationFlow": "EXTERNAL_CUSTOMER_SETUP_FLOW",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "dialingCode": "+44",
      "phone": "973 293 74813",
      "dob": "1990-05-15T00:00:00+01:00",
      "password": "O5ti8XI/pLYC27E+ehORvg2YplXqX3ckoS7Kzk9cEdtC+LSzVICID9c/Tzsi0V5dEVScmSb74/OwCjYEo1akURB+hD1fC5E/SHVEZIWMY6OKZjFqGx4fCd5gtS3z2kQsdWdm6rqd7144pZbB7PPzkK/I5kIM2TyzOlfMg4nMNNTbwowhzt1cn1YK9kGwkLQgdpSv1BNHkiSaXXl+I6FAqPEVt7leJGJ5njkv7abxkYpIB8JjDYGdQzBAzBXCRysBuJSrLVgU78eAqQ3OvVRzS5pvdFDPhWPaqvOt7Xz+NaH3P3X6JS7XF14h0+fll/rvYTg+OqPLu4yX68PaGf6gcg==",
      "confirmPassword": "O5ti8XI/pLYC27E+ehORvg2YplXqX3ckoS7Kzk9cEdtC+LSzVICID9c/Tzsi0V5dEVScmSb74/OwCjYEo1akURB+hD1fC5E/SHVEZIWMY6OKZjFqGx4fCd5gtS3z2kQsdWdm6rqd7144pZbB7PPzkK/I5kIM2TyzOlfMg4nMNNTbwowhzt1cn1YK9kGwkLQgdpSv1BNHkiSaXXl+I6FAqPEVt7leJGJ5njkv7abxkYpIB8JjDYGdQzBAzBXCRysBuJSrLVgU78eAqQ3OvVRzS5pvdFDPhWPaqvOt7Xz+NaH3P3X6JS7XF14h0+fll/rvYTg+OqPLu4yX68PaGf6gcg==",
      "address": {
        "address1": "123 High Street",
        "address2": "",
        "countryCommonName": "United Kingdom",
        "postcode": "SW1A 1AA",
        "countryIso3": "GBR"
      },
      "dynamicFields": {}
    }'
  ```
</CodeGroup>

<Accordion title="Using payloadEncrypted: false (Testing Only)" icon="flask">
  For internal testing or development environments where encryption is not required:

  ```bash theme={null}
  curl -X POST "https://agent.fincode.software/api/v6/services/usermanagement/register-customer" \
    -H "Content-Type: application/json" \
    -H "platform: fincode" \
    -H "uuid: 200" \
    -d '{
      "devicePlatform": "Android",
      "appVersion": "1",
      "appId": "com.app.remit_junction",
      "customerType": "INDIVIDUAL",
      "payloadEncrypted": false,
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe+test@example.com",
      "dialingCode": "+44",
      "phone": "973 293 74813",
      "dob": "1990-05-15T00:00:00+01:00",
      "password": "SecurePass123!",
      "confirmPassword": "SecurePass123!",
      "address": {
        "address1": "123 High Street",
        "address2": "",
        "countryCommonName": "United Kingdom",
        "postcode": "SW1A 1AA",
        "countryIso3": "GBR"
      },
      "dynamicFields": {}
    }'
  ```

  <Warning>
    Never use `payloadEncrypted: false` in production environments as it transmits passwords without encryption.
  </Warning>
</Accordion>

## Validation Rules

<AccordionGroup>
  <Accordion title="Email Validation" icon="envelope">
    * Must be a valid email format - Must be unique across all customers in the
      tenant - Cannot be changed after creation - Maximum length: 255 characters
  </Accordion>

  {' '}

  <Accordion title="Password Requirements" icon="lock">
    * Minimum 8 characters - At least one uppercase letter (A-Z) - At least one
      lowercase letter (a-z) - At least one number (0-9) - At least one special
      character (!@#\$%^&\*) - Cannot contain common words or patterns
  </Accordion>

  {' '}

  <Accordion title="Phone Number Format" icon="phone">
    * Must be in international format with country code - Example: +447123456789
      (UK), +12125551234 (US) - No spaces or special characters except leading + -
      Must be a valid phone number for the country
  </Accordion>

  {' '}

  <Accordion title="Age Requirement" icon="calendar">
    * Customer must be at least 18 years old - Date of birth must be in ISO format
      (YYYY-MM-DD) - Cannot be a future date - Cannot be more than 120 years ago
  </Accordion>

  <Accordion title="Name Validation" icon="user">
    * First name: 2-50 characters - Last name: 2-50 characters - Only letters,
      spaces, hyphens, and apostrophes allowed - No numbers or special characters
  </Accordion>
</AccordionGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Login" icon="right-to-bracket" href="/api/auth/login">
    Authenticate the newly created customer
  </Card>

  <Card title="Submit KYC Documents" icon="id-card" href="/api/compliance/submit-cra">
    Upload verification documents for the customer
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /usermanagement/register-customer
openapi: 3.0.0
info:
  title: FinCode API
  version: v6
servers:
  - url: https://{tenant}.fincode.software/api/v6/services
    description: API v6
    variables:
      tenant:
        default: remitjunction
        description: Enter your tenant subdomain
  - url: https://{tenant}.fincode.software/api/v1/services
    description: API v1
    variables:
      tenant:
        default: finlend
        description: Enter your tenant subdomain
  - url: https://api.stag.songhaiexchange.io
    description: Songhai Exchange API
security: []
paths:
  /usermanagement/register-customer:
    post:
      summary: Register Customer
      description: Register a new customer account
      operationId: registerCustomer
      parameters:
        - $ref: '#/components/parameters/platformHeader'
        - $ref: '#/components/parameters/uuidHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                devicePlatform:
                  type: string
                  example: IOS
                appVersion:
                  type: string
                  example: '1'
                appId:
                  type: string
                  example: com.fincode.remitjunction
                customerType:
                  type: string
                  enum:
                    - INDIVIDUAL
                    - COMPANY
                  default: INDIVIDUAL
                  example: INDIVIDUAL
                payloadEncrypted:
                  type: boolean
                  description: >-
                    Determines whether the payload contains encrypted or raw
                    data. Use payloadEncrypted: true when sending encrypted
                    passwords, or payloadEncrypted: false for raw passwords.
                  default: true
                  example: true
                firstName:
                  type: string
                  example: Excel
                lastName:
                  type: string
                  example: Nwachukwu
                email:
                  type: string
                  format: email
                  example: excel.nwachukwu+2@fincode.co.uk
                dialingCode:
                  type: string
                  example: '+44'
                phone:
                  type: string
                  example: 984 573 63733
                dob:
                  type: string
                  format: date
                  example: '1989-12-16'
                password:
                  type: string
                  format: password
                  description: >-
                    Customer password. Must be RSA-encrypted (Base64) when using
                    payloadEncrypted is true, or raw when using false.
                  example: >-
                    O5ti8XI/pLYC27E+ehORvg2YplXqX3ckoS7Kzk9cEdtC+LSzVICID9c/Tzsi0V5d...
                confirmPassword:
                  type: string
                  format: password
                  description: >-
                    Must match the password field. Must be RSA-encrypted
                    (Base64) when using payloadEncrypted is true, or raw when
                    false.
                  example: >-
                    O5ti8XI/pLYC27E+ehORvg2YplXqX3ckoS7Kzk9cEdtC+LSzVICID9c/Tzsi0V5d...
                address:
                  type: object
                  properties:
                    address1:
                      type: string
                      example: San Janet Street
                    address2:
                      type: string
                      example: ''
                    countryCommonName:
                      type: string
                      example: United Kingdom
                    postcode:
                      type: string
                      example: SWA 1AA
                    countryIso3:
                      type: string
                      example: GBR
                dynamicFields:
                  type: object
                  properties: {}
              required:
                - devicePlatform
                - appVersion
                - appId
                - customerType
                - payloadEncrypted
                - firstName
                - lastName
                - email
                - dialingCode
                - phone
                - dob
                - password
                - confirmPassword
                - address
                - dynamicFields
      responses:
        '200':
          description: Customer registered successfully
components:
  parameters:
    platformHeader:
      in: header
      name: platform
      schema:
        type: string
        default: fincode
      required: true
    uuidHeader:
      in: header
      name: uuid
      schema:
        type: string
        default: '200'
      required: true

````