---
title: "Create a contact"
description: "Creates a contact, optionally adding it to a group. Set `update_if_exists` to update an\nexisting contact with the same number instead of creating a duplicate.\n"
version: "v2"
---

> Documentation Index
> Fetch the complete documentation index at: https://dev.touchsms.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

Path: touchSMS API › Contacts

`POST /v2/contacts`

Creates a contact, optionally adding it to a group. Set `update_if_exists` to update an
existing contact with the same number instead of creating a duplicate.

## Authentication

- `basicAuth`, http, header `Authorization`

## Request body

_Required._

- `number` (`createContact.number`; string, required) — Mobile number, ideally in E.164 format.
  - minLength 5; maxLength 20
- `firstname` (`createContact.firstname`; string, optional)
- `surname` (`createContact.surname`; string, optional)
- `email` (`createContact.email`; string, optional)
  - format `email`
- `group` (`createContact.group`; string, optional) — Add the contact to the group with this name. The group is created if it does not exist.
- `groups` (`createContact.groups`; array<integer>, optional) — IDs of groups to add the contact to.
- `update_if_exists` (`createContact.update_if_exists`; boolean, optional) — Create only. If a contact with this number exists, update it instead of creating a new one.
- `metadata` (`createContact.metadata`; object, optional) — Custom fields. These must be configured on your account first.

## Example request

```json
{
  "number": "+61412345678",
  "firstname": "Sam",
  "surname": "Taylor",
  "email": "sam@example.com",
  "group": "Customers",
  "update_if_exists": true
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://app.touchsms.com.au/api/v2/contacts \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": "+61412345678",
  "firstname": "Sam",
  "surname": "Taylor",
  "email": "sam@example.com",
  "group": "Customers",
  "update_if_exists": true
}
'
```

### TypeScript

```typescript
const url = 'https://app.touchsms.com.au/api/v2/contacts';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Basic <credentials>'},
  body: JSON.stringify({
    number: '+61412345678',
    firstname: 'Sam',
    surname: 'Taylor',
    email: 'sam@example.com',
    group: 'Customers',
    update_if_exists: true
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://app.touchsms.com.au/api/v2/contacts"

payload = {
    "number": "+61412345678",
    "firstname": "Sam",
    "surname": "Taylor",
    "email": "sam@example.com",
    "group": "Customers",
    "update_if_exists": True
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic <credentials>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 200

An existing contact was updated (when `update_if_exists` is true).

#### Example

```json
{
  "data": {
    "id": 4040,
    "user": 5678,
    "firstname": "Sam",
    "surname": "Taylor",
    "email": "sam@example.com",
    "number": "+61412345678",
    "metadata": null,
    "groups": [
      {
        "id": 512,
        "name": "Customers"
      }
    ],
    "updated": "2024-03-11T02:14:07Z",
    "created": "2024-02-02T23:51:19Z"
  }
}
```

- `data` (`createContact.response.200.data`; object, optional)
  - example `{"id":4040,"user":5678,"firstname":"Sam","surname":"Taylor","email":"sam@example.com","number":"+61412345678","metadata":null,"groups":[{"id":512,"name":"Customers"}],"updated":"2024-03-11T02:14:07Z","created":"2024-02-02T23:51:19Z"}`
  - `id` (`createContact.response.200.data.id`; integer, optional)
  - `user` (`createContact.response.200.data.user`; integer, optional) — ID of the user that owns the contact.
  - `firstname` (`createContact.response.200.data.firstname`; string | null, optional)
  - `surname` (`createContact.response.200.data.surname`; string | null, optional)
  - `email` (`createContact.response.200.data.email`; string | null, optional)
  - `number` (`createContact.response.200.data.number`; string, optional)
  - `metadata` (`createContact.response.200.data.metadata`; object | null, optional)
  - `groups` (`createContact.response.200.data.groups`; array<object>, optional)
    - `id` (`createContact.response.200.data.groups.id`; integer, optional)
    - `name` (`createContact.response.200.data.groups.name`; string, optional)
  - `notes` (`createContact.response.200.data.notes`; array<object>, optional) — Notes on the contact. Only returned when getting or updating a single contact.
    - `id` (`createContact.response.200.data.notes.id`; integer, optional)
    - `content` (`createContact.response.200.data.notes.content`; string, optional)
    - `created_at` (`createContact.response.200.data.notes.created_at`; string, optional)
      - format `date-time`
    - `updated_at` (`createContact.response.200.data.notes.updated_at`; string, optional)
      - format `date-time`
  - `updated` (`createContact.response.200.data.updated`; string, optional)
    - format `date-time`
  - `created` (`createContact.response.200.data.created`; string, optional)
    - format `date-time`

### 201

Contact created.

#### Example

```json
{
  "data": {
    "id": 4040,
    "user": 5678,
    "firstname": "Sam",
    "surname": "Taylor",
    "email": "sam@example.com",
    "number": "+61412345678",
    "metadata": null,
    "groups": [
      {
        "id": 512,
        "name": "Customers"
      }
    ],
    "updated": "2024-03-11T02:14:07Z",
    "created": "2024-02-02T23:51:19Z"
  }
}
```

- `data` (`createContact.response.201.data`; object, optional)
  - example `{"id":4040,"user":5678,"firstname":"Sam","surname":"Taylor","email":"sam@example.com","number":"+61412345678","metadata":null,"groups":[{"id":512,"name":"Customers"}],"updated":"2024-03-11T02:14:07Z","created":"2024-02-02T23:51:19Z"}`
  - `id` (`createContact.response.201.data.id`; integer, optional)
  - `user` (`createContact.response.201.data.user`; integer, optional) — ID of the user that owns the contact.
  - `firstname` (`createContact.response.201.data.firstname`; string | null, optional)
  - `surname` (`createContact.response.201.data.surname`; string | null, optional)
  - `email` (`createContact.response.201.data.email`; string | null, optional)
  - `number` (`createContact.response.201.data.number`; string, optional)
  - `metadata` (`createContact.response.201.data.metadata`; object | null, optional)
  - `groups` (`createContact.response.201.data.groups`; array<object>, optional)
    - `id` (`createContact.response.201.data.groups.id`; integer, optional)
    - `name` (`createContact.response.201.data.groups.name`; string, optional)
  - `notes` (`createContact.response.201.data.notes`; array<object>, optional) — Notes on the contact. Only returned when getting or updating a single contact.
    - `id` (`createContact.response.201.data.notes.id`; integer, optional)
    - `content` (`createContact.response.201.data.notes.content`; string, optional)
    - `created_at` (`createContact.response.201.data.notes.created_at`; string, optional)
      - format `date-time`
    - `updated_at` (`createContact.response.201.data.notes.updated_at`; string, optional)
      - format `date-time`
  - `updated` (`createContact.response.201.data.updated`; string, optional)
    - format `date-time`
  - `created` (`createContact.response.201.data.created`; string, optional)
    - format `date-time`

### 401

Missing, malformed or invalid API credentials.

#### Example

```json
{
  "message": "Unauthenticated."
}
```

- `message` (`createContact.response.401.message`; string, required)

### 422

The request failed validation. `errors` lists the messages for each invalid field.

#### Example

```json
{
  "message": "The messages field is required.",
  "errors": {
    "messages": [
      "The messages field is required."
    ]
  }
}
```

- `message` (`createContact.response.422.message`; string, optional)
- `errors` (`createContact.response.422.errors`; map<array<string>>, optional)


Source: https://dev.touchsms.com.au/api/contacts/create/index.md