API Reference

MessageBird’s Contacts API (V2) allows you to create and manage a single omni-channel profile for any customer you message on any of MessageBird’s supported platforms. This means that regardless of which platform a customer is messaging you on, you will always be able to identify who they are. Contacts API V2 is available for all customers using Programmable Conversations to message their customers over Facebook Messenger, LINE, Telegram, WeChat, SMS, and WhatsApp.

API Endpoint

https://contacts.messagebird.com/v2

Endpoints Summary

// Contacts
GET /contacts
POST /contacts
GET /contacts/{id}
PATCH /contacts/{id}
DELETE /contacts/{id}

// Identifiers
POST /contacts/{id}/identifiers
DELETE /contacts/{id}/identifiers/{id}

// Imports
POST /import/contacts
GET  /import/contacts/{import_id}/status

Authorization

With each API call you'll need to set an access key to authenticate yourself. API keys can be created or retrieved through the MessageBird Dashboard.

To provide the access key, set the Authorization header in the form of AccessKey {accessKey}.

Formats and Headers

All API responses are in JSON. You're required to send the Accept header with the value application/json with each request.

POST and PUT requests to the API must contain a JSON-formatted payload in the request body.

Errors

MessageBird uses standard HTTP status codes to indicate success or failure of an API request. Codes in the 2xx range indicate that a request was successfully processed and codes in the 4xx range indicate that there was an error that resulted from the information sent (e.g. authentication, no balance or a missing or wrong parameter).

In the case of an error, the body of the response includes a JSON-formatted response that tells you exactly what is wrong.

Error Object Example

{
  "errors": [
    {
      "code": 2,
      "description": "Request not allowed (incorrect access_key)",
      "parameter": "access_key"
    }
  ]
}

Attributes

Attribute	Type	Description
errors[].code	integer	An integer that represents the error type.
errors[].description	string	A human-readable description of the error. You can use this to let the user know what they can do about the error.
errors[].parameter	string	The parameter in your request related to the error if the error is parameter specific.

The Contact object

A Contact represents an end-user or customer that you have been in touch with on a messaging platform. A single contact might be present across multiple platforms, e.g. you might have a customer "Jane Doe" and she can be reached on SMS, WhatsApp, and Telegram because she has reached out to your business across all of these platforms. Jane can exist as a single contact in the Contacts API to make repeated communication seamless, regardless of what platform you're talking over.

Attributes

Attribute	Type	Description
id	string	A unique random ID which is created on the MessageBird platform and is returned upon creation of the contact.
displayName	string	A display name (e.g. "{firstName} {lastName}", a username, or phone number) for the contact, typically used when displaying a contact in UI.
firstName	string	Optional. The first name of the contact.
lastName	string	Optional. The last name of the contact.
languages	Array	Optional. An array of language identifiers. Will be populated with ISO 639-1 codes for the language of this contact if the contact has messaged on a platform that provides locale data.
country	string	Optional. An identifier the country this contact resides in. Will be populated with an ISO 3166-1 code if the contact has messaged on a platform that provides country data.
avatar	string	Optional. A URL linking to an avatar for this contact.
gender	string	Optional. A gender identifier for the customer. Free text format.
status	string	The status of this contact, one of: active, merged.
profiles	Array of Profile	Optional. An array of the profiles that link this Contact to a specific channel.
attributes	JSON	Optional. Custom key-value attributes that can be assigned to the contact. Any valid JSON object is accepted, but the maximum size of the object is 10kB.
href	string	The URL for this contact resource.
createdAt	date	RFC3339 formatted timestamp of the creation time of the contact.
updatedAt	date	RFC3339 formatted timestamp of the time of the last update made to the contact.

Example Contact

{
  "id": "f4a4af42f9894b56b6f7b3418443b2e1",
  "href": "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1",
  "displayName": "Jane Tester",
  "firstName": "Jane",
  "lastName": "Tester",
  "identifiers": [
    {
      "id": "d4095cbec4be475c862f329b109e961e",
      "type": "emailaddress",
      "value": "jane.tester@messagebird.com"
    },
    {
      "id": "5abffd64e6aa445fa9947449e44c49f0",
      "type": "phonenumber",
      "value": "3112345678"
    }
  ],
  "languages": [
    "en",
    "nl"
  ],
  "timezone": "UTC+1",
  "country": "NL",
  "avatar": "https://example.com/avatar.png",
  "gender": "f",
  "profiles": [
    {
      "id": "de93f56a2d7442d3b1e9048637c7382e",
      "channelId": "d759a993508e42e49fa74afc0687cc4b",
      "identifier": "3112345678"
    }
  ],
  "attributes": {
    "membership": "platinum",
    "status": "vip",
    "customerNumber": "1234"
  },
  "status": "active",
  "createdAt": "2019-05-08T12:23:19Z",
  "updatedAt": "2019-05-08T12:23:19Z"
}

The Identifier object

An Identifier is a value used by other platforms to Identify a contact. This can be a generic identifier such as a phone number or email address that are used with multiple platforms, as well as some platform specific identifiers such as your Facebook ID.

Attributes

Attribute	Type	Description
id	string	A unique random ID used to identify this identifier on the MessageBird platform.
type	string	The type of identifier.
value	string	The identifier of the user on the provided channel.

Types

Here is a list of possible identifier types. This list will expand as we add new channels.

Type	Description
phonenumber	A valid MSISDN used by channels like WhatsApp and SMS.
emailaddress	Email Address used by channels identifying with email.
facebook	Facebook user ID, Can only be used with the Facebook channel.
wechat	WeChat user ID. Can only be used with the WeChat channel.
line	Line user ID. Can only be used with the Line channel.
telegram	Telegram user ID. Can only be used with the Telegram channel.
instagram	Instagram user ID. Can only be used with the Instagram channel.
twitter	Twitter user ID. Can only be used with the Twitter channel.

The Profile object

The Profile object is a link between your contact on MessageBird and one of your configured messaging channels, e.g. a Facebook page, Telegram bot, or WhatsApp Business Account. Identifiers depend on the platform, for example, a WhatsApp channel identifier is an MSISDN registered to a user's account on WhatsApp, a Facebook identifier is a page-scoped ID value provided by Facebook.

There is no limit to the number of profiles a contact can have. Some platforms, such as Facebook Messenger, have a different user identifier per page. This means your contact can have a profile for each configured channel even if some of those channels belong to the same platform.

Attributes

Attribute	Type	Description
id	string	A unique random ID used to identify this profile on the MessageBird platform.
channelId	string	The id of the MessageBird channel for this profile.
identifier	string	The platform-specific identifier of the user on the provided channel.

List all Contacts

Retrieves all contacts for this account. By default, contacts are sorted by the createdAt field so that all new contacts appear first.

Parameters

No parameters are required; however, filters and pagination can be provided through the following optional query parameters:

Parameter	Type	Description	Example
ids	string	Comma separated list of contact ids to filter.	ids=idA,idB,idC
channelId	string	Only return contacts that have a profile associated with this channel.	channelId=2ccb501a4b0e440a8779103478292f84
identifierExact	string	Only return contacts with this Identifier associated to the contact.	identifierExact=jane.tester@messagebird.com
status	string	Contact status. active or merged. Default: active.	status=active
limit	integer	The number of maximum objects to return on each request. Default: 20	limit=10
offset	integer	The number of objects to skip from the first. Default: 0	offset=120

Definition

GET https://contacts.messagebird.com/v2/contacts

Example request

curl "https://contacts.messagebird.com/v2/contacts?channelId=d759a993508e42e49fa74afc0687cc4b&status=active&offset=40&limit=10" \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
  -H 'Content-Type: application/json; charset=utf-8'

Example response

{
    "totalCount": 43,
    "count": 3,
    "offset": 10,
    "limit": 10,
    "items": [
        {
            "id": "f4a4af42f9894b56b6f7b3418443b2e1",
            "href": "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1",
            "displayName": "Jane Tester",
            "firstName": "Jane",
            "lastName": "Tester",
            "identifiers": [
                {
                    "id": "d4095cbec4be475c862f329b109e961e",
                    "type": "emailaddress",
                    "value": "jane.tester@messagebird.com"
                },
                {
                    "id": "5abffd64e6aa445fa9947449e44c49f0",
                    "type": "phonenumber",
                    "value": "3112345678"
                }
            ],
            "languages": [
                "en",
                "nl"
            ],
            "timezone": "UTC+1",
            "country": "NL",
            "avatar": "https://example.com/avatar.png",
            "gender": "f",
            "profiles": [
                {
                    "id": "de93f56a2d7442d3b1e9048637c7382e",
                    "channelId": "d759a993508e42e49fa74afc0687cc4b",
                    "identifier": "3112345678"
                }
            ],
            "attributes": {
                "membership": "platinum",
                "status": "vip",
                "customerNumber": "1234"
            },
            "status": "active",
            "createdAt": "2019-05-08T12:23:19Z",
            "updatedAt": "2019-05-08T12:23:19Z"
        },
        {
            "...": "..."
        },
        {
            "...": "..."
        }
    ]
}

Create a Contact

Create a new contact with the provided data and profiles.

Definition

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

Example request

curl -X POST "https://contacts.messagebird.com/v2/contacts" \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "displayName": "Jane Tester",
    "firstName": "Jane",
    "lastName": "Tester",
    "avatar": "https://example.com/avatar.png",
    "languages": [
      "en",
      "nl"
    ],
    "country": "NL",
    "timezone": "UTC+1",
    "gender": "f",
    "attributes": {
      "membership": "platinum",
      "status": "vip",
      "customerNumber": "1234"
    }
  }'

Example response

{
    "id": "f4a4af42f9894b56b6f7b3418443b2e1",
    "href": "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1",
    "displayName": "Jane Tester",
    "firstName": "Jane",
    "lastName": "Tester",
    "identifiers": [
        {
            "id": "d4095cbec4be475c862f329b109e961e",
            "type": "emailaddress",
            "value": "jane.tester@messagebird.com"
        },
        {
            "id": "5abffd64e6aa445fa9947449e44c49f0",
            "type": "phonenumber",
            "value": "3112345678"
        }
    ],
    "languages": [
        "en",
        "nl"
    ],
    "timezone": "UTC+1",
    "country": "NL",
    "avatar": "https://example.com/avatar.png",
    "gender": "f",
    "profiles": [],
    "attributes": {
        "membership": "platinum",
        "status": "vip",
        "customerNumber": "1234"
    },
    "status": "active",
    "createdAt": "2019-05-08T12:23:19Z",
    "updatedAt": "2019-05-08T12:23:19Z"
}

View a Contact

Find an existing contact by id.

Definition

GET https://contacts.messagebird.com/v2/contacts/{id}

Example request

curl "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1" \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
  -H 'Content-Type: application/json; charset=utf-8'

Example response

{
  "id": "f4a4af42f9894b56b6f7b3418443b2e1",
  "href": "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1",
  "displayName": "Jane Tester",
  "firstName": "Jane",
  "lastName": "Tester",
  "identifiers": [
    {
      "id": "d4095cbec4be475c862f329b109e961e",
      "type": "emailaddress",
      "value": "jane.tester@messagebird.com"
    },
    {
      "id": "5abffd64e6aa445fa9947449e44c49f0",
      "type": "phonenumber",
      "value": "3112345678"
    }
  ],
  "languages": [
    "en",
    "nl"
  ],
  "timezone": "UTC+1",
  "country": "NL",
  "avatar": "https://example.com/avatar.png",
  "gender": "f",
  "profiles": [
    {
      "id": "de93f56a2d7442d3b1e9048637c7382e",
      "channelId": "d759a993508e42e49fa74afc0687cc4b",
      "identifier": "3112345678"
    }
  ],
  "attributes": {
    "membership": "platinum",
    "status": "vip",
    "customerNumber": "1234"
  },
  "status": "active",
  "createdAt": "2019-05-08T12:23:19Z",
  "updatedAt": "2019-05-08T12:23:19Z"
}

Update a Contact

Update properties of an existing contact by id. As this is a PATCH request, only fields that require changes need to be provided in the request.

The languages array field will be updated by replacing the entire array with what is provided in the request.

The attributes field will be updated as an RFC7386 merge patch. Existing attributes will be merged with new attributes provided in the patch request. If a key exists in the existing attributes and the patched attributes, it will be overwritten with the value from the patched attributes. Deleting an attribute is possible by setting it's value to null in the patch request.

Definition

PATCH https://contacts.messagebird.com/v2/contacts/{id}

Example request

curl -X PATCH "https://contacts.messagebird.com/v2/contacts/0b0f86191edb46cbb47c108f2c11d5a6" \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "displayName": "Jane from MessageBird",
    "languages": ["en", "fr"],
    "attributes": {
      "company": "MessageBird",
      "team": "Product Engineering"
    }
  }'

Example response

{
  "id": "f4a4af42f9894b56b6f7b3418443b2e1",
  "href": "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1",
  "displayName": "Jane Tester",
  "firstName": "Jane",
  "lastName": "Tester",
  "identifiers": [
    {
      "id": "d4095cbec4be475c862f329b109e961e",
      "type": "emailaddress",
      "value": "jane.tester@messagebird.com"
    },
    {
      "id": "5abffd64e6aa445fa9947449e44c49f0",
      "type": "phonenumber",
      "value": "3112345678"
    }
  ],
  "languages": [
    "en",
    "nl"
  ],
  "timezone": "UTC+1",
  "country": "NL",
  "avatar": "https://example.com/avatar.png",
  "gender": "f",
  "profiles": [
    {
      "id": "de93f56a2d7442d3b1e9048637c7382e",
      "channelId": "d759a993508e42e49fa74afc0687cc4b",
      "identifier": "3112345678"
    }
  ],
  "attributes": {
    "membership": "platinum",
    "status": "vip",
    "customerNumber": "1234"
  },
  "status": "active",
  "createdAt": "2019-05-08T12:23:19Z",
  "updatedAt": "2019-05-08T12:23:19Z"
}

Update or Create Contact

This method looks for an existing contact with passed identifiers and updates it with new ones from the request. If contact with such identifiers does not exist, it will create one. It returns updated or created contact ID and a flag that indicates if a contact was created. If updateContact argument set to false, contact fields will not be updated if the contact already exists. Pass false if you are unsure.

Use it if you don't know if a contact exists, otherwise use PATCH contact.

Attributes

Attribute	Type	Description
updateContact	boolean	Weather to update contact if exists or not
contact.id	string	A unique random ID which is created on the MessageBird platform and is returned upon creation of the contact.
contact.displayName	string	A display name (e.g. "{firstName} {lastName}", a username, or phone number) for the contact, typically used when displaying a contact in UI.
contact.firstName	string	Optional. The first name of the contact.
contact.lastName	string	Optional. The last name of the contact.
contact.email	string	DEPRECATED (Use Identifiers instead). The primary registered email address for this contact.
contact.phone	string	DEPRECATED (Use Identifiers instead). The primary registered phone number for this contact.
contact.languages	Array	Optional. An array of language identifiers. Will be populated with ISO 639-1 codes for the language of this contact if the contact has messaged on a platform that provides locale data.
contact.country	string	Optional. An identifier the country this contact resides in. Will be populated with an ISO 3166-1 code if the contact has messaged on a platform that provides country data.
contact.avatar	string	Optional. A URL linking to an avatar for this contact.
contact.gender	string	Optional. A gender identifier for the customer. Free text format.
contact.status	string	The status of this contact, one of: active, merged.
contact.profiles	Array of Profile	Optional. An array of the profiles that link this Contact to a specific channel.
contact.identifiers	Array of Identifier	Optional. An array of the identifiers that link this Contact.
contact.attributes	JSON	Optional. Custom key-value attributes that can be assigned to the contact. Any valid JSON object is accepted, but the maximum size of the object is 10kB.
contact.href	string	The URL for this contact resource.
contact.createdAt	date	RFC3339 formatted timestamp of the creation time of the contact.
contact.updatedAt	date	RFC3339 formatted timestamp of the time of the last update made to the contact.

Definition

POST https://contacts.messagebird.com/v2/ops/contacts/upsert

Example request

curl -X POST "https://contacts.messagebird.com/v2/ops/contacts/upsert" \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "updateContact": true,
    "contact": {
      "displayName": "Jane Tester",
      "firstName": "Jane",
      "lastName": "Tester",
      "avatar": "https://example.com/avatar.png",
      "languages": [
        "en",
        "nl"
      ],
      "country": "NL",
      "timezone": "UTC+1",
      "gender": "f",
      "attributes": {
        "membership": "platinum",
        "status": "vip",
        "customerNumber": "1234"
      }
    }
  }'

Example response

{
    "contactId": "f4a4af42f9894b56b6f7b3418443b2e1",
    "created": true
}

Delete a Contact

Deletes a contact and its profiles. You only need to supply the unique id that was returned upon creation.

This request will hard delete the all conversations and conversation's messages that belongs to the contact ID.

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://contacts.messagebird.com/v2/contacts/{id}

Example request

curl -X DELETE https://rest.messagebird.com/v2/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]

Merge contacts

Merge contact into another contact. It can be used to combine data from two different contacts, which should represent the same user. The one that's passed in the URL will be the active one.

Note that if merged contact had active conversations, they will be merged as well.

Attributes

Attribute	Type	Description
origin	string	A unique random ID of the original contact. Required
destination	string	A unique random ID of the destination contact. Required

Definition

POST https://contacts.messagebird.com/v2/ops/contacts/merge

Example request

curl -X POST "https://contacts.messagebird.com/v2/ops/contacts/merge" \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "origin": "5ff77bdc2f004451986be7e03894d52b",
    "destination": "f4a4af42f9894b56b6f7b3418443b2e1"

Example response

{
  "id": "f4a4af42f9894b56b6f7b3418443b2e1",
  "href": "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1",
  "displayName": "Jane Tester",
  "firstName": "Jane",
  "lastName": "Tester",
  "identifiers": [
    {
      "id": "d4095cbec4be475c862f329b109e961e",
      "type": "emailaddress",
      "value": "jane.tester@messagebird.com"
    },
    {
      "id": "5abffd64e6aa445fa9947449e44c49f0",
      "type": "phonenumber",
      "value": "3112345678"
    }
  ],
  "languages": [
    "en",
    "nl"
  ],
  "timezone": "UTC+1",
  "country": "NL",
  "avatar": "https://example.com/avatar.png",
  "gender": "f",
  "profiles": [
    {
      "id": "de93f56a2d7442d3b1e9048637c7382e",
      "channelId": "d759a993508e42e49fa74afc0687cc4b",
      "identifier": "3112345678"
    }
  ],
  "attributes": {
    "membership": "platinum",
    "status": "vip",
    "customerNumber": "1234"
  },
  "status": "active",
  "createdAt": "2019-05-08T12:23:19Z",
  "updatedAt": "2019-05-08T12:23:19Z"
}

List all identifiers of a contact

Definition

GET https://contacts.messagebird.com/v2/contacts/{id}/identifiers

Example request

curl "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1/identifiers" \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
  -H 'Content-Type: application/json; charset=utf-8'

Example response

{
    "count" : 1,
    "offset" : 0,
    "limit" : 20,
    "items": [{
      "id": "35964e692de14a8ca79ef0facb8d6c28",
      "type": "emailaddress",
      "value": "mark@gmail.com",
      "createdAt": "2019-05-08T12:23:19Z"
    }]
  }

Get a specific identifier of a contact

Definition

GET https://contacts.messagebird.com/v2/contacts/{id}/identifiers/{identifier_id}

Example request

curl "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1/identifiers/35964e692de14a8ca79ef0facb8d6c28" \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
  -H 'Content-Type: application/json; charset=utf-8'

Example response

{
    "id": "35964e692de14a8ca79ef0facb8d6c28",
    "type": "emailaddress",
    "value": "mark@gmail.com",
    "createdAt": "2019-05-08T12:23:19Z"
  }

Add an Identifier to an existing Contact

Link a identifier of a provided type to an existing Contact. Use this endpoint to add any known identifiers to a contact (such as email, phone, etc.).

Definition

POST https://contacts.messagebird.com/v2/contacts/{id}/identifiers

Example request

curl -X POST "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1/identifiers" \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "type": "emailaddress",
    "value": "mark@gmail.com"
  }'

Example response

{
    "id": "35964e692de14a8ca79ef0facb8d6c28",
    "type": "emailaddress",
    "value": "mark@gmail.com",
    "createdAt": "2019-05-08T12:23:19Z"
  }

Delete an identifier from a contact

Deletes the referenced identifier and the profiles linked to it.

Definition

DELETE https://contacts.messagebird.com/v2/contacts/{id}/identifiers/{identifier_id}

Example request

curl -X DELETE "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1/identifiers/35964e692de14a8ca79ef0facb8d6c28" \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
  -H 'Content-Type: application/json; charset=utf-8'

Import Contacts

This endpoint allows you to upload up to 100k of contacts in a csv file format. The required structure of a file is shown below. When you’re uploading a csv file, keep in mind that the headers must be set according to the headers fields below.

File header fields

Header	Type	Description
phone	string	Optional. The primary registered phone number for this contact.
email	string	Optional. The primary registered email address for this contact.
firstName	string	Optional. The first name of the contact.
lastName	string	Optional. The last name of the contact.
displayName	string	A display name (e.g. "{firstName} {lastName}", a username, or phone number) for the contact, typically used when displaying a contact in UI.
custom:key	string	Any custom attributes you want to include in the contact, where key is a unique key in the contacts Attribute object. Eg: custom:account_id

Definition

POST https://contacts.messagebird.com/v2/import/contacts

Example request

curl -X POST https://contacts.messagebird.com/v2/import/contacts \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy" \
-H 'Content-Type: text/csv' \
-H 'Content-Disposition: form-data; name="contacts"; filename="contacts.csv"' \
-d '@test.csv'

Sample CSV File

phone,email,firstName,lastName,displayName,custom:membership,custom:status,custom:customerNumber
+31612345678,johandoe@messagebird.com,John,Doe,John Doe,silver,,1111
+3112345678,,Jane,Tester,Jane Tester,platinum,vip,1234

Response

When a file is uploaded, its id and tracking URL are created accordingly. The status of the importing contacts should be tracked with the url output.

Example response

{
  "id":"123123123123"
  "href":"https://contacts.messagebird.com/v2/import/contacts/123123123123/status"
}

Track an Imported File

To track the imported file, provide the unique random id that is returned when the file was imported.

Required parameters

Parameter	Type	Description
id	string	A unique random id created on the MessageBird platform that is returned when a file is imported. Required

Definition

GET https://contacts.messagebird.com/v2/import/contacts/{import_id}/status

Example request

curl "https://contacts.messagebird.com/v2/import/contacts/{import_id}/status" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy"

Response

If the request is successful, it will return 200—this means the id exists; the response body will be as below. If the request fails, it means that the id could not be found.

Attributes	Type	Description
status	string	Status of the tracking. It can be completed, failed, queued or in progress
message	string	Describing the status of importing the file

Example response

{
  status: “in progress”,
  message: “importing”
}

Is this page useful?

Next upIntegrations

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