> For the complete documentation index, see [llms.txt](https://wiki.mobivatebulksms.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.mobivatebulksms.com/contact-management/create-new-contact.md).

# 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",
    "groupID": "YOUR_GROUP_ID",
    "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.                                                                                                        |
| groupID | string | No       | The ID of an existing contact group. If provided, the contact will automatically be added to this group when created. If omitted, the contact is created without being assigned to a group. |

{% hint style="info" %}
**Note:** `groupId` is optional. The value must be the ID of an existing contact group. If an invalid group ID is supplied, the request will return a validation error.
{% endhint %}

#### 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 %}