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

# Create Customer

> Registers a new customer. Email, phone, and client reference ID must each be unique across your organization.

<Prompt description="Create Customer" actions={["cursor"]}>
  Integrate the DollarPe Create Customer endpoint into my application.

  Endpoint: POST /customer/create
  Base URL: [https://api.dollarpe.in](https://api.dollarpe.in) (production) | [https://sandbox.dollarpe.in](https://sandbox.dollarpe.in) (sandbox)

  Auth headers required on every request:

  * X-API-KEY: your API key
  * X-TIMESTAMP: current Unix time in seconds
  * X-SIGNATURE: Base64(HMAC-SHA256(X-API-KEY + X-TIMESTAMP + sortedJSONBody, apiSecret))

  Key constraints:

  * email, phone, and client\_reference\_id must be unique per organization
  * country\_code must be a valid ISO code

  Task: Write a typed function that:

  1. Accepts customer fields (name, email, phone, country\_code, client\_reference\_id)
  2. Builds the auth headers with the signed request body
  3. Calls POST /customer/create
  4. Returns the created customer object with its ID
  5. Handles 400 errors (duplicate email/phone/reference\_id, invalid country) and 500

  Language: TypeScript
</Prompt>

## Error Codes and Messages

| API Status Code | Response                           | Reason                             |
| --------------- | ---------------------------------- | ---------------------------------- |
| 400             | Email already in use               | Email already in use               |
| 400             | Phone already in use               | Phone already in use               |
| 400             | Invalid country code               | Invalid country code               |
| 400             | Client Reference ID already exists | Client Reference ID already exists |
| 500             | Internal Server Error              | Internal Server Error              |


## OpenAPI

````yaml POST /customer/create
openapi: 3.1.0
info:
  title: DollarPe API
  description: API for DollarPe - Customer, Payout, and Webhook services
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://sandbox.dollarpe.xyz/pos/api/v1
    description: Payout API Base URL
    variables:
      base_url:
        default: https://sandbox.dollarpe.xyz
  - url: https://sandbox.dollarpe.xyz/cms/api/v1
    description: Customer API Base URL
    variables:
      base_url:
        default: https://sandbox.dollarpe.xyz
security:
  - ApiKeyAuth: []
    TimestampAuth: []
    SignatureAuth: []
tags:
  - name: Customer
    description: Customer related operations
    x-displayName: Customer
    x-traitTag: true
  - name: Payout
    description: Payout related operations
  - name: Webhooks
    description: Webhook related operations
  - name: Widget
    description: Hosted buy/sell widget session initialization
paths:
  /customer/create:
    post:
      tags:
        - Customer
      description: Create a new customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - full_name
                - email
                - phone
                - alpha_3_country_code
              properties:
                full_name:
                  type: string
                  description: Full name of the customer
                  example: John Doe
                email:
                  type: string
                  description: Email address of the customer
                  example: john@example.com
                phone:
                  type: string
                  description: Phone number of the customer
                  example: '9911002211'
                alpha_3_country_code:
                  type: string
                  description: Country code (based on nationality)
                  example: IND
                client_reference_id:
                  type: string
                  description: Optional customer reference ID
                  example: test123
                non_residence_status:
                  type: boolean
                  description: Boolean to define if the customer is a non-resident
                  example: true
                residence_alpha_3_country_code:
                  type: string
                  description: Country code (based on country of residence)
                  example: USA
      responses:
        '200':
          description: Customer created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        example: 550e8400-e29b-41d4-a716-446655440000
                      client_reference_id:
                        type: string
                        example: test123
                      full_name:
                        type: string
                        example: John Doe
                      email:
                        type: string
                        example: john.doe@example.com
                      phone:
                        type: string
                        example: '+1234567890'
                      country:
                        type: string
                        example: USA
                      type:
                        type: string
                        example: INDIVIDUAL
                      status:
                        type: string
                        example: UNVERIFIED
                      failure_reason:
                        type: string
                        example: null
                      document_type:
                        type: string
                        example: AADHAAR
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Bad Request
                  err_code:
                    type: string
                    example: INPUT_MALFORMED
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    example:
                      type:
                        - type is required
                      email:
                        - email is required
                  data:
                    type: 'null'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Internal Server Error
                  err_code:
                    type: string
                    example: SYS_INTERNAL_ERROR
                  errors:
                    type: string
                    example: Unexpected error occurred. Please try again later.
                  data:
                    type: 'null'
      servers:
        - url: https://sandbox.dollarpe.xyz/cms/api/v1
          description: Customer API Base URL
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API Key for authentication
    TimestampAuth:
      type: apiKey
      in: header
      name: X-TIMESTAMP
      description: Current timestamp in seconds since epoch
    SignatureAuth:
      type: apiKey
      in: header
      name: X-SIGNATURE
      description: HMAC SHA256 signature of the request encoded in Base64

````