> ## Documentation Index
> Fetch the complete documentation index at: https://doc-test-my.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Contact

> Create a Contact using API.

Use this endpoint to create a new contact.

* A new contact is created if any combination of the following details is unique: `name`, `email`, `contact`, `type` and `reference_id`.
* If **all** the above details match the details of an existing contact, the API returns details of the existing contact.

<RequestExample>
  ```bash Curl theme={null}
  curl -u <YOUR_KEY>:<YOUR_SECRET> \
  -X POST https://api.razorpay.com/v1/contacts \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Gaurav Kumar",
    "email":"gaurav.kumar@example.com",
    "contact":"9000090000",
    "type":"employee",
    "reference_id":"Acme Contact ID 12345",
    "notes":{
      "notes_key_1":"Tea, Earl Grey, Hot",
      "notes_key_2":"Tea, Earl Grey… decaf."
    }
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "id": "cont_00000000000001",
    "entity": "contact",
    "name": "Gaurav Kumar",
    "contact": "9000090000",
    "email": "gaurav.kumar@example.com",
    "type": "employee",
    "reference_id": "Acme Contact ID 12345",
    "batch_id": null,
    "active": true,
    "notes": {
      "notes_key_1": "Tea, Earl Grey, Hot",
      "notes_key_2": "Tea, Earl Grey… decaf."
    },
    "created_at": 1545320320
  }
  ```

  ```json Failure theme={null}
  {
    "error": {
        "code": "BAD_REQUEST_ERROR",
        "description": "Invalid type: employee",
        "source": "business",
        "step": null,
        "reason": "input_validation_failed",
        "metadata": {},
        "field": "type"
    }
  }
  ```
</ResponseExample>

## Request Parameters

<ParamField body="name" type="string" required>
  The contact's name. This field is case-sensitive. A minimum of 3 characters and a maximum of 50 characters are allowed. Name cannot end with a special character, except `.`. Supported characters: `a-z`, `A-Z`, `0-9`, `space`, `’` , `-` , `_` , `/` , `(` , `)` and , `.`. For example, `Gaurav Kumar`.
</ParamField>

<ParamField body="email" type="string">
  The contact's email address. For example, `gaurav.kumar@example.com`.
</ParamField>

<ParamField body="contact" type="string">
  The contact's phone number. For example, `9000090000`.
</ParamField>

<ParamField body="type" type="string">
  Maximum 40 characters. Classification for the contact being created. For example, `employee`. The following classifications are available by default:

  * `vendor`
  * `customer`
  * `employee`
  * `self`

  <br />

  Additional classifications can be created via the [Dashboard](https://x.razorpay.com/) and then used in APIs. It is not possible to create new classifications via API.
</ParamField>

<ParamField body="reference_id" type="string">
  Maximum 40 characters. A user-entered reference for the contact. For example, `Acme Contact ID 12345`.
</ParamField>

<ParamField body="notes" type="object">
  Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, `"note_key": "Beam me up Scotty”`.
</ParamField>

## Response Parameters

<ResponseField name="id" type="string">
  The unique identifier linked to the contact. For example, `cont_00000000000001`.
</ResponseField>

<ResponseField name="entity" type="string">
  The entity being created. Here, it is `contact`.
</ResponseField>

<ResponseField name="name" type="string">
  The contact's name. For example, `Gaurav Kumar`.
</ResponseField>

<ResponseField name="contact" type="string">
  The contact's phone number. For example, `9000090000`.
</ResponseField>

<ResponseField name="email" type="string">
  The contact's email address. For example, `gaurav.kumar@example.com`.
</ResponseField>

<ResponseField name="type" type="string">
  A classification for the contact being created. For example, `employee`.
</ResponseField>

<ResponseField name="reference_id" type="string">
  A user-entered reference for the contact. For example, `Acme Contact ID 12345`.
</ResponseField>

<ResponseField name="batch_id" type="string">
  This value is returned if the contact was created as part of a bulk upload. For example, `batch_00000000000001`.
</ResponseField>

<ResponseField name="active" type="boolean">
  Possible values:

  * `true` (default) : active
  * `false` : inactive
</ResponseField>

<ResponseField name="notes" type="object">
  Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, `"note_key": "Beam me up Scotty”`.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Timestamp, in Unix, when the contact was created. For example, `1545320320`.
</ResponseField>

## Errors

<AccordionGroup>
  <Accordion title="The `name` field is required.">
    **Code:** `4xx`

    The `name` field is missing in the request body.

    **Solution:** Enter the details in the recommended format as per the request body.
  </Accordion>

  <Accordion title="The `name` field is invalid.">
    **Code:** `4xx`

    There are special characters used in the `name` field.

    **Solution:** Enter details as per the format recommended for Create a Contact request for `name` field.
  </Accordion>

  <Accordion title="Invalid type: `contact_typeA`">
    **Code:** `4xx`

    * There are special characters in the `type` field.
    * Casing does not match as per the `type`. `type` is case-sensitive.
    * Contact type sent in the request does not match the types present in the Dashboard.

    **Solution:** Enter the correct contact type in the request body. You cannot create new contact types via API. You must create them via the [RazorpayX Dashboard](http://x.razorpay.com/auth).
  </Accordion>
</AccordionGroup>