---
page_source: https://juspay.io/sea/docs/express-checkout-sdk-global/react-native/base-sdk-integration/2-create-customer-api
page_title: 2.2 Create Customer API
---

## API Version: default


# Create Customer API



This API is responsible for creating a new customer object in Juspay systems. You can invoke this API whenever a new user registers in your App/Website and is triggering the payment process.Customer creation at Juspay end is required for : Tokenization/Storing Cards, Linked Wallet Flows and Subscription flows.## Endpoints:
- Sandbox: https://sandbox.juspay.in/customers

- Production: https://api.juspay.in/customers

## Request Type: 
POST

## Content-Type: 
application/json

## Authorization:

#### Basic Auth:
Consists of two parts.

* Username: API Key obtained from Juspay dashboard
* Password: Empty string
- Value: <p>Example:- <br> Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==</p>
- Tags: Base64 Encoded username:password, required
## Headers:

#### x-merchantid:
Unique identifier for the merchant. This is the Merchant ID provided by Juspay. The value is case sensitive.

> **Note**
> Passing this value will help us route efficiently at network level.


- Value: x-merchantid: testaccount
- Tags: string, Recommended

#### Content-Type:
application/x-www-form-urlencoded
- Tags: String, Mandatory
## Sample Code Snippets:
### Sample Request:

#### Request Code Snippet:

```request
curl -X POST https://api.juspay.in/customers\
-u your_api_key:\
-H 'x-merchantid: merchant_id'\
-H 'Content-Type: application/x-www-form-urlencoded'\
-d "object_reference_id=customer@gmail.com"\
-d "mobile_number=99887766"\
-d "email_address=customer@gmail.com"\
-d "first_name=John"\
-d "last_name=Smith"\
-d "mobile_country_code=65"
```

### Sample Response:

#### 200 - Success:
```json
{
  "id": "cst_afdeuvmfhs3j1acm",
  "object": "customer",
  "object_reference_id": "customer@gmail.com",
  "mobile_country_code": "65",
  "mobile_number": "99887766",
  "email_address": "customer@gmail.com",
  "first_name": "John",
  "last_name": "Smith",
  "date_created": "2020-03-17T14:13:37Z",
  "last_updated": "2020-03-17T14:13:37Z"
}
```

#### 401 - Unauthorized:
```plaintext
{
    "status": "error",
    "error_code": "access_denied",
    "error_info": {
        "user_message": "Unauthorized.",
        "request_id": "e40e052a-f3c0-4242-9f25-c7ba47b97c31",
        "href": "NA",
        "developer_message": "Invalid API Key. Please pass a valid and active api key.",
        "code": "UNAUTHORIZED",
        "category": "USER_ERROR"
    }
}
```

#### 400 - Bad Request:
```plaintext
{
    "error_message": "[objectReferenceId] cannot be null",
    "status": "invalid_request_error",
    "error_code": "nullable",
    "error_info": {
        "user_message": "Mandatory fields are missing.",
        "fields": [
            {
                "field_name": "object_reference_id",
                "reason": "Missing value."
            }
        ],
        "request_id": "411b73c7-866e-4210-9171-70c8b9241b6f",
        "href": "NA",
        "developer_message": "Missing object reference id. Please pass valid object reference id.",
        "code": "MISSING_MANDATORY_PARAMETER",
        "category": "USER_ERROR"
    }
}
```

#### 400 - Validation Errors:
```plaintext
{
    "error_message": "Wrong value in mobile_number",
    "status": "Invalid Request",
    "error_code": "Invalid Request",
    "error_info": {
        "user_message": "Invalid request params. Please verify your input.",
        "fields": [
            {
                "field_name": "mobile_number",
                "reason": "Invalid value."
            }
        ],
        "request_id": "d41a008a-a07e-470d-ba09-ac369465a410",
        "href": "NA",
        "developer_message": "Invalid request params",
        "code": "INVALID_INPUT",
        "category": "USER_ERROR"
    }
}
```

## Body Parameters:
### Basic Parameters:

#### object_reference_id:
- Description: Unique ID that you use to represent the customer in your database. This must be atleast 8 characters and must be unique. The typical value for this field would be email address or mobile number or auto increment ID that you have in your DB

Example:-cust_123489
- Value: Example:as
- Tags: string, required, Max Length :255 

#### mobile_number:
- Description: Customers mobile number. We recommend passing number without appending "+" or mobile country code.Dummy values can be passed if customer details are unavailable.

> **Warning**
> Must contain digits only. Spaces or special characters are not supported.Passing formatted values will result in a `400 – Validation error`.


- Value:  99887766
- Tags: string, required, Max Length : 300

#### email_address:
- Description: Email address of the customer. If the backend gateway requires it, then you must send this value.Dummy values can be passed if customer details are unavailable.**Constraints :** You are allowed to use alphanumeric characters and the following special characters:`!#$%&'*+-/=?^_.{|}~`@`

`_`and `.` cannot appear at the beginning or end of the local part of the email address (before and after the `@`symbol).
- Tags: string, Max Length : 300

#### first_name:
- Description: First Name of customer. This value will be used for customer identification.**Constraints :** You are allowed to use alphanumeric characters and the following special characters: `().-_`
- Tags: string, Max Length :255 

#### last_name:
- Description: Last Name of customer. This value will be used for customer identification.**Constraints :** You are allowed to use alphanumeric characters and the following special characters: `().-_`
- Tags: string, Max Length :255 

#### mobile_country_code:
- Description: Your mobile's country code. No need to add prefix ‘+’ in front of it.

> **Note**
> Defaults to `91`(India) if not provided in the request.


- Value:  65
- Tags: string, Max Length :64 
## API Responses:
### 200:

#### id:
- Description: The ID created at Juspay end for each object_reference_id during create customer API call
- Tags: string

#### object:
- Description: Refers to the API object type
- Tags: string

#### mobile_country_code:
- Description: Customer's mobile country code
- Tags: string

#### mobile_number:
- Description: Customers mobile number
- Tags: string

#### last_updated:
- Description: Last updated date on the customer information
- Tags: string

#### last_name:
- Description: Customer's last name
- Tags: string

#### first_name:
- Description: Customer's first name
- Tags: string

#### email_address:
- Description: Customer's e-mail address
- Tags: string

#### date_created:
- Description: Customer creation date at Juspay’s end
- Tags: string
### 400:

#### error_message:
- Description: Error message of the API response
- Value: sample response: [objectReferenceId] cannot be null
- Tags: String

#### status:
- Description: Denotes what type of error message
- Value: Response: invalid_request_error
- Tags: String

#### error_info:
- Description: Detaield information on the error message
- Value:
  - **User_message**:
    - Description: Error message can be duispaleyd to the user
    - Value: sample response: Mandatory fields are missing.
    - Tags: String
  - **Fields**:
    - Description: Denotes what exact parameter is missing in the request
    - Tags: Array
  - **Developer_message**:
    - Description: ccAurate information on the error messaeg to the user
    - Value: sample response: Missing object reference id. Please pass valid object reference id.
    - Tags: String
  - **Category**:
    - Description: Denotes the type of category the error
    - Value: sample response: USER_ERROR
    - Tags: String
- Tags: JSON
### 401:

#### status:
- Description: Status of the api response
- Value: Response: error
- Tags: String

#### error_code:
- Description: error code information
- Value: Sample response: access_denied
- Tags: String

#### error_info:
- Description: Detailed information of the error
- Value:
  - **User_message**:
    - Description: User error message
    - Value: Response: Unauthorized.
    - Tags: String
  - **Developer_message**:
    - Description: Provide accurate details on the error message
    - Value: Sample Response: Invalid API Key. Please pass a valid and active api key.
    - Tags: String
  - **Category**:
    - Description: Denotes the category of the error
    - Value: Sample Response: USER_ERROR
    - Tags: String
- Tags: JSON



## Error Codes:




| Scenario | Error Codes | Description | Sample Error Message |
|---|---|---|---|
| customer creation with same object_reference_id | 400 | Bad Request | {"error_message":"Customer with given object reference id already exist for your account.","status":"invalid_request_error","error_code":"unique","error_info": {"user_message":"Already exists.","developer_message":"Customer account with given object reference already exists.","code":"ALREADY_EXISTS","category":"USER_ERROR"}} |
| Passing object_reference_id as empty value | 400 | Bad Request | {"error_message":"Wrong value in object_reference_id","status":"Invalid Request","error_code":"Invalid Request","error_info": {"user_message":"Invalid request params. Please verify your input.","fields": [{"field_name":"object_reference_id","reason":"Invalid value."}],"developer_message":"Invalid request params","code":"INVALID_INPUT","category":"USER_ERROR"}} |
| Passing mobile_number as empty value | 400 | Bad Request | {"error_message":"Wrong value in mobile_number","status":"Invalid Request","error_code":"Invalid Request","error_info": {"user_message":"Invalid request params. Please verify your input.","fields": [{"field_name":"mobile_number","reason":"Invalid value."}],"developer_message":"Invalid request params","code":"INVALID_INPUT","category":"USER_ERROR"}} |
| Whitelisting of IP in dashboard  | 403 | IP Verification Failed | {"error":true,"error_message":"Internal Server error.","user_message":"Bad Origin.","error_info":{"code":"BAD_ORIGIN","category":"USER_ERROR","user_message":"Bad Origin.","developer_message":"IP Verification Failed"}} |
| Wrong API Key | 401 | Unauthorized | {"status":"error","error_code":"access_denied","error_info": {"user_message":"Unauthorized.","developer_message":"Invalid API Key. Please pass a valid and active api key.","code":"UNAUTHORIZED","category":"USER_ERROR"}} |
| Wrong API endpoint | 404 | Not Found |  |
| passing "-" before mobile_number value | 400 | Bad Request | {"error_message":"Wrong value in mobile_number","status":"Invalid Request","error_code":"Invalid Request","error_info": {"user_message":"Invalid request params. Please verify your input.","fields": [{"field_name":"mobile_number","reason":"Invalid value."}],"developer_message":"Invalid request params","code":"INVALID_INPUT","category":"USER_ERROR"}} |