Contacts API

MessageBird provides an API to manage contacts.

Contacts are identified by a unique random ID. Using this ID you can create, view, update or delete contacts.

URI

https://rest.messagebird.com/contacts

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

AttributeTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
hrefstringThe URL of the created object.
msisdnintegerThe phone number of contact.
firstNamestringThe first name of the contact.
lastNamestringThe last name of the contact.
customDetails.custom1-customDetails.custom4stringCustom fields of the contact.
groupshashThe hash with groups the contact belongs to. Further explanation in the table below.
messageshashThe hash with messages sent to contact. Further explanation in the table below.
createdDatetimedatetimeThe date and time of the creation of the contact in RFC3339 format (Y-m-dTH:i:sP).
updatedDatetimedatetimeThe date and time of the last update of the contact in RFC3339 format (Y-m-dTH: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

AttributeTypeDescription
totalCountintegerThe total count of groups that contact belongs to.
hrefstringURL which can be used to retrieve list of groups contact belongs to.

The messages hash

AttributeTypeDescription
totalCountintegerThe total count of messages sent to contact.
hrefstringURL 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

ParameterTypeDescription
msisdnstringThe phone number of the contact. Required

Optional parameters

ParameterTypeDescription
firstNamestringThe first name of the contact.
lastNamestringThe last name of the contact.
custom1-custom4stringCustom 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

ParameterTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required

Optional parameters

ParameterTypeDescription
msisdnstringAlternatively you can provide an msisdn instead of an id to view a contact. Does not work for other methods. Not Required
namestringAnother 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

ParameterTypeDescription
idstringA 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

ParameterTypeDescription
idstringA 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]
cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings