API Reference

MessageBird’s Contacts API helps you manage contacts that are identified by a unique random ID. Using this ID, you can create, view, update, or delete contacts. This API works as a collection of customer-specific contacts that allows you to group them and assign custom values that you can later use when sending SMS template messages.

The Contacts API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.

API Endpoint

All URLs referenced in MessageBird's Voice Calling API documentation have the base URL in the code snippet on the right side:

API Endpoint

https://rest.messagebird.com/contacts

Available HTTP methods

The MessageBird API uses HTTP verbs to understand if you want to read (GET), delete (DELETE) or create (POST) an object. When your web application cannot do a POST or DELETE, we provide the ability to set the method through the query parameter _method.

Available HTTP Methods

POST /contacts
GET /contacts
GET /contacts/{contactId}
GET /contacts/{contactId}/groups
GET /contacts/{contactId}/messages
PATCH /contacts/{contactId}
DELETE /contacts/{contactId}

The contact object

This object represents a contact at MessageBird.com

Attributes

Attribute	Type	Description
id	string	A unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
href	string	The URL of the created object.
msisdn	integer	The phone number of contact.
firstName	string	The first name of the contact.
lastName	string	The last name of the contact.
customDetails.custom1-customDetails.custom4	string	Custom fields of the contact.
groups	hash	The hash with groups the contact belongs to. Further explanation in the table below.
messages	hash	The hash with messages sent to contact. Further explanation in the table below.
createdDatetime	datetime	The date and time of the creation of the contact in RFC3339 format (Y-m-d\TH:i:sP).
updatedDatetime	datetime	The date and time of the last update of the contact in RFC3339 format (Y-m-d\TH:i:sP).

Object example

{
  "id": "61afc0531573b08ddbe36e1c85602827",
  "href": "https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827",
  "msisdn": 31612345678,
    "firstName": "John",
    "lastName": "Doe",
  "customDetails": {
    "custom1": "",
    "custom2": "",
    "custom3": "",
    "custom4": ""
  },
  "groups": {
    "totalCount": 0,
    "href": "https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827/groups"
  },
  "messages": {
    "totalCount": 0,
    "href": "https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827/messages"
  },
  "createdDatetime": "2016-04-29T09:42:26+00:00",
  "updatedDatetime": "2016-04-29T09:42:26+00:00"
}

The groups hash

Attribute	Type	Description
totalCount	integer	The total count of groups that contact belongs to.
href	string	URL which can be used to retrieve list of groups contact belongs to.

The messages hash

Attribute	Type	Description
totalCount	integer	The total count of messages sent to contact.
href	string	URL which can be used to retrieve list of messages sent to contact.

Create a contact

Creates a new contact object. MessageBird returns the created contact object with each request.

Required parameters

Parameter	Type	Description
msisdn	string	The phone number of the contact. Required

Optional parameters

Parameter	Type	Description
firstName	string	The first name of the contact.
lastName	string	The last name of the contact.
custom1-custom4	string	Custom fields of the contact.

Definition

POST https://rest.messagebird.com/contacts

Example request

curl -X POST https://rest.messagebird.com/contacts \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -d "msisdn=31612345678"

Returns

Returns a contact object if the request was successful. If the request failed, an error object will be returned.

Example response

{
  "id": "61afc0531573b08ddbe36e1c85602827",
  "href": "https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827",
  "msisdn": 31612345678,
  "firstName": "John",
  "lastName": "Doe",
  "customDetails": {
    "custom1": "",
    "custom2": "",
    "custom3": "",
    "custom4": ""
  },
  "groups": {
    "totalCount": 0,
    "href": "https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827/groups"
  },
  "messages": {
    "totalCount": 0,
    "href": "https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827/messages"
  },
  "createdDatetime": "2016-04-29T09:42:26+00:00",
  "updatedDatetime": "2016-04-29T09:42:26+00:00"
}

View a contact

Retrieves the information of an existing contact. You only need to supply the unique contact ID that was returned upon creation or receiving.

Required parameters

Parameter	Type	Description
id	string	A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required

Optional parameters

Parameter	Type	Description
msisdn	string	Alternatively you can provide an msisdn instead of an id to view a contact. Does not work for other methods. Not Required
name	string	Another options is providing a name instead of an id to view (a) contact(s). Does not work for other methods. Not Required

Definition

GET https://rest.messagebird.com/contacts/{contactId}

Example request

curl -X GET https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827 \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Returns

Returns a contact object if the request was successful. If the request failed, an error object will be returned.

Example response

{
  "id": "61afc0531573b08ddbe36e1c85602827",
  "href": "https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827",
  "msisdn": 31612345678,
  "firstName": "John",
  "lastName": "Doe",
  "customDetails": {
    "custom1": "",
    "custom2": "",
    "custom3": "",
    "custom4": ""
  },
  "groups": {
    "totalCount": 0,
    "href": "https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827/groups"
  },
  "messages": {
    "totalCount": 0,
    "href": "https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827/messages"
  },
  "createdDatetime": "2016-04-29T09:42:26+00:00",
  "updatedDatetime": "2016-04-29T09:42:26+00:00"
}

Update a contact

Updates an existing contact. You only need to supply the unique id that was returned upon creation.

Required parameters

Parameter	Type	Description
id	string	A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required

Definition

PATCH https://rest.messagebird.com/contacts/{contactId}

Example request

curl -X PATCH https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827 \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -d "msisdn=31612345679"

Returns

Returns an HTTP header of 200 OK and the contact object if the request was successful. If the request failed, an error object will be returned.

Example response

{
  "id": "61afc0531573b08ddbe36e1c85602827",
  "href": "https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827",
  "msisdn": 31612345679,
  "firstName": "John",
  "lastName": "Doe",
  "customDetails": {
    "custom1": "",
    "custom2": "",
    "custom3": "",
    "custom4": ""
  },
  "groups": {
    "totalCount": 0,
    "href": "https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827/groups"
  },
  "messages": {
    "totalCount": 0,
    "href": "https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827/messages"
  },
  "createdDatetime": "2016-04-29T09:42:26+00:00",
  "updatedDatetime": "2016-04-29T09:42:26+00:00"
}

Delete a contact

Deletes an existing contact. You only need to supply the unique id that was returned upon creation.

Required parameters

Parameter	Type	Description
id	string	A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required

Definition

DELETE https://rest.messagebird.com/contacts/{contactId}

Example request

curl -X DELETE https://rest.messagebird.com/contacts/61afc0531573b08ddbe36e1c85602827 \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Returns

Returns an HTTP header of 204 No Content and an empty response if the request was successful. If the request failed, an error object will be returned.

Example response

[empty]

Is this page useful?

Next upGroups

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings