# Create New Contact

Create a new contact in your address book. Contacts can be referenced later when sending messages using aliases, batch campaigns, or template-based messaging.

### <mark style="color:green;">`POST`</mark> `/addressbook/contacts`&#x20;

#### Required Permission

```
create:Contacts
```

Your API key must have this permission enabled in order to use this endpoint.

### Example Request

```bash
curl --location 'https://<hostname>/contacts' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "alias": "john",
    "msisdn": "4479000000001",
    "meta": {
      "NAME": "John",
      "CITY": "London"
    }
  }'

```

Replace `YOUR_API_KEY` with your API key.

{% hint style="info" %}
All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request.
{% endhint %}

#### Request Parameters

| Field  | Type   | Required | Description                                                                          |
| ------ | ------ | -------- | ------------------------------------------------------------------------------------ |
| alias  | string | Yes      | Unique identifier for the contact. Used for alias-based messaging.                   |
| msisdn | string | Yes      | Phone number in international format.                                                |
| meta   | object | No       | Custom key-value data associated with the contact. Used for message personalisation. |

#### Responses

#### Success (HTTP 200)

Returned when the contact is successfully created.

```json
{
  "success": true,
  "record": {
    "id": "3392287d-7a79-4789-9ef8-7dc174836688",
    "alias": "john",
    "msisdn": "4479000000001",
    "created_on": "2025-11-10T20:15:12.000Z"
  }
}
```

#### Validation Error (HTTP 400)

Returned when required fields are missing or invalid.

```json
{
  "success": false,
  "error": {
    "name": "ValidationError",
    "statusCode": 400,
    "message": "Alias is required"
  }
}
```

{% hint style="warning" %}
**Aliases** must be unique within your address book.
{% endhint %}