POST - Create request

The GDPR API allows you to create GDPR requests and get their status. This page documents the creation endpoint.

A request concerns a single user. Two types of request can be created :

A review request which generates a data report containing the user's data.
A remove request which triggers the removal of the user's data.

You can check the status of a request in two ways:

provide a callback URL in the request. This URL will be called once the request is done.
make a status request.

Note: GDPR request information is available via our Dashboard and APIs for 20 to 30 days after request creation. After this time, you will not be able to query its status anymore. Pending requests are always available.

Request structure

Route

The GDPR API exposes a POST endpoint that allows to create a GDPR request :

https://api.batch.com/1.0/BATCH_API_KEY/gdpr/request

Here is a valid cURL example:

curl -H "Content-Type: application/json" \
     -H "X-Authorization: BATCH_REST_API_KEY" \
     -X POST -d "@payload.json" "https://api.batch.com/1.0/BATCH_API_KEY/gdpr/request"

The BATCH_API_KEY value is either your Live, Dev or SDK Batch API key from the settings page of your app within the dashboard (Settings → General):

Please note Batch manages each platform separately, so you will have to call the API twice with a different Dev/Live API key if you want to target iOS and Android.

Headers

In order to authenticate with the API, you need to provide your company REST API Key as the value of the X-Authorization header. You can find it in ⚙ Settings → General.

Insufficient privileges issue: You may see that error in the REST API key field. This happens because the REST API key is only visible to managers. Make sure the managers of the account share that key with you or ask them to grant you access through the team manager.

Post data

The body of the request must contain a valid JSON payload describing the request to be executed, and information about the concerned user.

Here is a how a complete JSON payload looks like:

{
  "request_type": "review",
  "callback_url": "https://callback.site",
  "id": {
    "type": "custom_id",
    "value": "john.doe"
  }
}

Let's see the parameters in detail.

Id	Description
`request_type`	string - Required The request type. Acceptable values include: `review` or `remove` . E.g.`{"request_type":"review"}`
`callback_url`	string - Optional A callback that is called when the request is finished. E.g.`{"description":"https://callback.site"}`
`id`	Object - Required An object describing the identifier of the user concerned by the request. E.g.`[{"type":"custom_id","value":"john.doe"}]`
	`type`	String - Required The ID type. Acceptable values include: `custom_id` , `advertising_id` or `install_id` . E.g.`{"type":"custom_id"}`
	`value`	String - The ID value. E.g.`{"value":"john.doe"}`

NOTE: The callback URL allows you to be notified when the request processing is done. The call is performed with a POST method, the payload is the same than the one we return on the status route. The URL must be secured with HTTPS.

Responses

Success

If the POST to the API endpoint is successful you will receive an HTTP 202 confirmation and a unique token representing the request.

{ "token": "110e8400-e29b-11d4-b543-446655440000" }

Please keep this token: It will be useful to check the status and get the result of your request.

Failure

If the user in the POST data is currently being processed, the API will return a HTTP 409 Conflict status code.

If the POST data does not meet the API requirements you will receive an actionable error message. Contact us at support@batch.com if you need further support.

AUTHENTICATION_INVALID (Http status code: 401, Error code: 10)
API_MISUSE (Http status code: 403, Error code: 12)
ROUTE_NOT_FOUND (HTTP status code: 404, Error code: 20)
MISSING_PARAMETER (HTTP status code: 400, Error code: 30)
MALFORMED_PARAMETER (HTTP status code: 400, Error code: 31)
MALFORMED_JSON_BODY (HTTP status code: 400, Error code: 32)
SERVER_ERROR (HTTP status code: 500, Error code: 1)
MAINTENANCE_ERROR (HTTP status code: 503, Error code: 2)

Documentation > API > GDPR API