Personal Data API beta
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.
Request object
| Attribute | Type | Description |
|---|---|---|
| id | string | Request ID. |
| field | string | The personal data type used to find the data. Possible values of the field attribute are: phone_number ipv4 ipv6 address name chat api contact ID |
| value | string | The value of the personal data. |
| callback | object | An object of Callback type. |
| reason | string | A free text with the reason for the request. |
| kind | string | KIND_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 |
| state | string | STATE_SENT STATE_FAILED STATE_DONE STATE_CALLBACK_OK STATE_CALLBACK_FAIL read-only |
| dataArchiveUrl | string | HTTPS link to the data archive, only populated when kind is KIND_PERSONAL_GET and state STATE_DONE read-only. |
| signatureKey | string | The key used to sign the callback, base64-encoded read-only. |
| createdAt | datetime | The date and time of creation in RFC3339Nano format read-only. |
| updatedAt | datetime | The date and time of last state update in RFC3339Nano format read-only. |
Callback object
| Attribute | Type | Description |
|---|---|---|
| http | string | HTTPS 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:
| Attribute | Type | Description |
|---|---|---|
| field | string | The personal data type used to find the data. Possible values of the field attribute are: phone_number ipv4 ipv6 address name chat api contact ID mandatory for requests of kind=KIND_PERSONAL_GET or kind=KIND_PERSONAL_DELETE |
| value | string | The value of the personal data. mandatory for requests of kind=KIND_PERSONAL_GET or kind=KIND_PERSONAL_DELETE |
| callback | object | An object of Callback type. mandatory |
| reason | string | A free text with the reason for the request. |
| kind | string | For 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
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.
| Attribute | Type | Description |
|---|---|---|
| requestId | string | Request ID. |
| requestKind | string | KIND_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 |
| result | string | An informative string on the status of the request. |
| data | string | URL 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:
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:
List ongoing requests
A request to /list will show all requests made with the API and their status.
| Attribute | Type | Description |
|---|---|---|
| requests | array | An array of objects with Request type. |
