Create a contact

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.

POST

https://app.touchsms.com.au/api/v2/contacts

Authorization

basicAuth
HTTP
required

Request body JSON required

number
string
required
Mobile number, ideally in E.164 format.

maxLength: 20 · minLength: 5
firstname
optional
string
surname
optional
string
email
optional
string
format: email
group
optional
string
Add the contact to the group with this name. The group is created if it does not exist.
groups
optional
array of
integer
IDs of groups to add the contact to.
update_if_exists
optional
boolean
Create only. If a contact with this number exists, update it instead of creating a new one.
metadata
optional
object
Custom fields. These must be configured on your account first.

Returns

200

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

JSON

data
optional
object
- id
  optional
  integer
- user
  optional
  integer
  ID of the user that owns the contact.
- firstname
  optional
  string | null
- surname
  optional
  string | null
- email
  optional
  string | null
- number
  optional
  string
- metadata
  optional
  object | null
- groups
  optional
  array of
  object
  id
  optional
  integer
  name
  optional
  string
- notes
  optional
  array of
  object
  Notes on the contact. Only returned when getting or updating a single contact.
  
  id
  optional
  integer
  content
  optional
  string
  created_at
  optional
  string
  format: date-time
  updated_at
  optional
  string
  format: date-time
- updated
  optional
  string
  format: date-time
- created
  optional
  string
  format: date-time
}

201

Contact created.

JSON

data
optional
object
- id
  optional
  integer
- user
  optional
  integer
  ID of the user that owns the contact.
- firstname
  optional
  string | null
- surname
  optional
  string | null
- email
  optional
  string | null
- number
  optional
  string
- metadata
  optional
  object | null
- groups
  optional
  array of
  object
  id
  optional
  integer
  name
  optional
  string
- notes
  optional
  array of
  object
  Notes on the contact. Only returned when getting or updating a single contact.
  
  id
  optional
  integer
  content
  optional
  string
  created_at
  optional
  string
  format: date-time
  updated_at
  optional
  string
  format: date-time
- updated
  optional
  string
  format: date-time
- created
  optional
  string
  format: date-time
}

401

Missing, malformed or invalid API credentials.

JSON

message
string
required

422

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

JSON

message
optional
string
errors
optional
map of
array<string>