Personal Data API beta

Notification icon

Please note that any information on this page that doesn't specifically relate to the API description, including the introduction to the GDPR, comes without warranty and cannot be considered legal advice. You should work with a lawyer to achieve adequate GDPR compliance.

The General Data Protection Regulation (GDPR) is a regulation from the European Union which became enforceable on 25th May 2018 as a replacement for the 1995 Data Protection Directive. It requires companies all over the world to give European citizens more control over their personal data. Personal data under GDPR is all data that relates to an individual and identifiable person.

In GDPR terminology, Controllers are companies that determine the purpose for which data is processed. Often they have a direct relationship with their customers and collect and process their data. If you have a website, such as an online shop or even just a blog, you are a Controller. To learn more about your obligations as a Controller, such as the need to bake Privacy-by-Design into your product, you can read the full text of the law online or one of the many third-party pieces covering the regulation.

A Processor is an entity that stores or processes personal data on behalf of a Controller. Processors include most API providers you have integrated into your application. If you have integrated MessageBird's APIs and send personal data in messages or use your customer's phone numbers, MessageBird is a Processor.

Your customer is a Data Subject under GDPR. They have individual rights, which include the right to access (Article 15 GDPR) and data portability (Article 20 GDPR), right to rectification (Article 16 GDPR), right to erasure (often called right to be forgotten - Article 17 GDPR) and right to restrict processing (Article 18 GDPR).

If your customer practices their right to access, as a Controller you need to provide any data you keep about them, including data that your Processors have stored. Also, if they want to invoke their right to erasure, you must delete any data that you are not legally required to keep, e.g. for accounting purposes, and also instruct your Processors to remove whatever personal data they hold. To help you fulfill your obligations, Processors have started offering specific GDPR-related APIs for programmatic submission of access and erasure requests.

MessageBird provides the Personal Data API documented below through which you can send data requests based on multiple identifiers through which we can search for information about a specific Data Subject, including telephone numbers, email addresses, and IP addresses. All APIs work asynchronously and send their result to a webhook URL when we have either collected all data for an access request or when we deleted all data based on the right to erasure.

URL

https://rest.messagebird.com/personaldata

Available HTTP Methods

The /get, /delete and POST /requests requests are asynchronous since gathering or removing data can take some time. The API call initiates processing which continues in the background. Completion will be reported to an HTTP callback, or webhook, you provide. The /list and GET /requests requests show all requests that are in progress.

Available HTTP Methods

POST /personaldata/get (deprecated)
POST /personaldata/delete (deprecated)
GET /personaldata/list (deprecated)
GET /personaldata/requests
POST /personaldata/requests

Request object

AttributeTypeDescription
idstringRequest ID.
fieldstringThe personal data type used to find the data.
Possible values of the field attribute are:
phone_number
email
ipv4
ipv6
address
name
chat api contact ID
valuestringThe value of the personal data.
callbackobjectAn object of Callback type.
reasonstringA free text with the reason for the request.
kindstringKIND_PERSONAL_GET : GET personal data of an individual identified by field value, default
KIND_PERSONAL_DELETE : DELETE personal data of an individual identified by the field value
KIND_USER_GET : GET all data for the user
KIND_USER_DELETE : DELETE all data for the user
statestringSTATE_SENT
STATE_FAILED
STATE_DONE
STATE_CALLBACK_OK
STATE_CALLBACK_FAIL
read-only
dataArchiveUrlstringHTTPS link to the data archive, only populated when kind is KIND_PERSONAL_GET and state STATE_DONE
read-only.
signatureKeystringThe key used to sign the callback, base64-encoded
read-only.
createdAtdatetimeThe date and time of creation in RFC3339Nano format
read-only.
updatedAtdatetimeThe date and time of last state update in RFC3339Nano format
read-only.

Callback object

AttributeTypeDescription
httpstringHTTPS endpoint address which accepts POST requests.
Must respond with HTTP 200.

The user is required to supply exactly one attribute in the Callback object.

Make a Request

For /delete, /get and POST /requests use the same parameters.

Parameters:

AttributeTypeDescription
fieldstringThe personal data type used to find the data.
Possible values of the field attribute are:
phone_number
email
ipv4
ipv6
address
name
chat api contact ID
mandatory for requests of kind=KIND_PERSONAL_GET or kind=KIND_PERSONAL_DELETE
valuestringThe value of the personal data.
mandatory for requests of kind=KIND_PERSONAL_GET or kind=KIND_PERSONAL_DELETE
callbackobjectAn object of Callback type.
mandatory
reasonstringA free text with the reason for the request.
kindstringFor POST /requests specify the kind of the request using this property:
KIND_PERSONAL_GET default
KIND_PERSONAL_DELETE
KIND_USER_GET
KIND_USER_DELETE

Example requests with cURL

Requesting data MessageBird holds of an individual that has the phone number "+3162372342" and is probably your customer:

Requesting all personal data that MessageBird holds of you as a company:

Example Request

$ curl -H "Content-Type: application/json"
-H Authorization: AccessKey your-key-here'
-X POST -d '{"field":"phone_number","value":"+3162372342","reason":"testing 123","kind":"KIND_PERSONAL_GET"}' https://rest.messagebird.com/personaldata/requests

Example Request

$ curl -H "Content-Type: application/json"
-H 'Authorization: AccessKey your-key-here'
-X POST -d '{"reason":"testing 123","kind":"KIND_USER_GET"}' https://rest.messagebird.com/personaldata/requests

Response

If the request was received successfully, a 201 Created response with the complete Request object is returned. You should store the id and signatureKey in order to match and verify the callback you’ll receive with the request you sent.

Response

201 Created

Callback responses

The Personal Data API sends a callback response once it finishes processing the request. The callback contains the Request ID, which was automatically generated by MessageBird for the request, and a result message. Get requests include a URL top to a ZIP file which contains the requested data.

AttributeTypeDescription
requestIdstringRequest ID.
requestKindstringKIND_PERSONAL_GET : GET personal data identified by field value, default
KIND_PERSONAL_DELETE : DELETE personal data identified by the field value
KIND_USER_GET : GET all data for the user
KIND_USER_DELETE : DELETE all data for the user
resultstringAn informative string on the status of the request.
datastringURL to the data archive when the kind is KIND_PERSONAL_GET, not populated otherwise.
Note: If the data retrieval process did not yield any personal data, the archive URL will be empty.

Callback Signature

When executing the callback, the header X-MessageBird-Signature is set. This header contains:

  • A unix epoch timestamp of when the callback got executed.
  • An HMAC SHA256 of the timestamp and the request body combined, hashed using signatureKey.

The header content is formatted as:

Header Content

t=1527080073,v1=1239e7e23c3e8b12aebbfc4b34fea7b989cd5002398995f5f056d5edfb62e009

where t=<unix epoch> and v1=<payload hmac sha256 signature>.

How to compute the callback signature

Parse the X-MessageBird-Signature header content by splitting it on the character , then splitting each token on character = to retrieve the timestamp and the signature as string.

Prepare the payload to sign by concatenating the timestamp to the request body separating them with a dot:

Example

<timestamp>.<request body>

List ongoing requests

A request to /list will show all requests made with the API and their status.

AttributeTypeDescription
requestsarrayAn array of objects with Request type.
cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings