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.

POST /addressbook/contacts

Required Permission

create:Contacts

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

Example Request

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.

All endpoints shown in this documentation use a sample base URL. The production API endpoint is provided by our team upon request.

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.

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.

Responses

Success (HTTP 200)

Returned when the contact is successfully created.

{
  "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.

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

Aliases must be unique within your address book.