• iOS
  • Android
  • Windows
  • Cordova
  • Web
  • Unity
  • Adobe Air
  • Dashboard
  • API
  • Guides
  • FAQ
  • API > GDPR API

    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.

    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 or Dev Batch API key from the settings page of your app within the dashboard (⚙ Settings → General).

    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.

    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.

    IdDescription
    request_typestring - Required
    The request type.
    Acceptable values include: review or remove.
    E.g.{"request_type":"review"}
    callback_urlstring - Optional
    A callback that is called when the request is finished.
    E.g.{"description":"https://callback.site"}
    idObject - Required
    An object describing the identifier of the user concerned by the request.
    E.g.[{"type":"custom_id","value":"john.doe"}]
    typeString - The ID type.
    Acceptable values include: custom_id, advertising_id or install_id.
    E.g.{"type":"custom_id"}
    valueString - 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)
    • 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)