Create a GDPR request

POST/v1/gdpr/requests

US Region: https://public-api.sessionboard.com · EU Region: https://public-api-eu.sessionboard.com

Submit a GDPR data access or erasure request for one email address, and process it synchronously against the organization's data.

For requestType: erasure the call returns once the erasure has run. Read status to find out what happened — it is recorded by the erasure itself and is never assumed:

complete — the email matched at least one record and erasure ran against it.
no_records_found — nothing in this organization matched the email. Nothing was erased. Treat this as an outcome to escalate, not a fulfilled request.

response carries the identifiers that were matched, and on requests processed recently also counts, users_scrubbed and users_retained — the compliance evidence of what the erasure actually did. A user account shared with another organization is retained rather than scrubbed, and appears in users_retained.

A 502 means the erasure did not run and nothing was recorded or erased; retry the request.

Request example

curl --request POST \
  --url 'https://public-api.sessionboard.com/v1/gdpr/requests' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "requestType": "erasure",
  "identityType": "email",
  "identityValue": "jane.doe@example.com"
}'

const response = await fetch('https://public-api.sessionboard.com/v1/gdpr/requests', {
  method: 'POST',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "requestType": "erasure",
    "identityType": "email",
    "identityValue": "jane.doe@example.com"
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.request(
    "POST",
    "https://public-api.sessionboard.com/v1/gdpr/requests",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "requestType": "erasure",
        "identityType": "email",
        "identityValue": "jane.doe@example.com"
    },
)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/gdpr/requests",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => '{
  "requestType": "erasure",
  "identityType": "email",
  "identityValue": "jane.doe@example.com"
}',
    CURLOPT_HTTPHEADER => [
        "x-access-token: <api-token>",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

func main() {
  req, _ := http.NewRequest("POST", "https://public-api.sessionboard.com/v1/gdpr/requests", strings.NewReader(`{
  "requestType": "erasure",
  "identityType": "email",
  "identityValue": "jane.doe@example.com"
}`))
  req.Header.Add("x-access-token", "<api-token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://public-api.sessionboard.com/v1/gdpr/requests"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"requestType\": \"erasure\",\n  \"identityType\": \"email\",\n  \"identityValue\": \"jane.doe@example.com\"\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Try it

Response headers

Authorizations

x-access-tokenstringheader
Organization API token. Generate from Organization Settings → API Tokens.
AuthorizationBearer <token>headeror
OAuth 2.1 access token. Obtained via the OAuth PKCE flow at /oauth/token.

Send one of these. See Authentication.

Request body

application/jsonrequired

requestTypestringrequired
The type of GDPR request.
Allowed values
"erasure", "access"
identityTypestringrequired
The type of identity to look up.
Allowed values
"email"
identityValuestringrequired
The identity value (e.g., an email address).

Example

{
  "requestType": "erasure",
  "identityType": "email",
  "identityValue": "jane.doe@example.com"
}

Responses

200`application/json`

The request was recorded and, for an erasure, processed. Check status for the outcome.

A GDPR data access or erasure request, and the record of what it did.

idstring
Identifier of the stored request. Quote this when evidencing a DSAR.
org_idstring
request_typestring
Allowed values
"erasure", "access"
identity_typestring
Allowed values
"email"
identity_valuestring
statusstring
Outcome of the request.
- complete — at least one record matched and was processed.
- no_records_found — nothing in this organization matched the email, so nothing was erased.
- pending — the request is stored but has not finished processing.
Allowed values
"complete", "no_records_found", "pending"
matching_user_existsboolean
True when the email matched at least one record of any kind.
responseobject
What the request matched and what happened to it. people, users_scrubbed, users_retained and counts are present on requests processed recently and absent on older records; an absent field means "not recorded", not "zero".
Show child attributes
- usersinteger[]
  User accounts identified for this email.
- org_usersstring[]
  Organization membership records removed.
- event_usersinteger[]
  Event participation records removed.
- contact_recordsstring[]
  Contact records marked deleted.
- peoplestring[]
  Person records whose personal data was scrubbed in place.
- users_scrubbedinteger[]
  User accounts whose personal data was de-identified.
- users_retainedobject[]
  User accounts left intact because they still belong to another organization, with the reason recorded.
- countsobject
  Per-category totals for the arrays above.
  Show child attributes
  - org_usersinteger
  - event_usersinteger
  - contact_recordsinteger
  - peopleinteger
  - users_identifiedinteger
  - users_scrubbedinteger
  - users_retainedinteger
created_atstring
updated_atstring

400

Bad request

401

Unauthorized

502

The erasure service could not be reached. Nothing was recorded and nothing was erased — retry.

Response examples

{
  "id": "<string>",
  "org_id": "<string>",
  "request_type": "erasure",
  "identity_type": "email",
  "identity_value": "<string>",
  "status": "complete",
  "matching_user_exists": true,
  "response": {
    "users": [
      123
    ],
    "org_users": [
      "<string>"
    ],
    "event_users": [
      123
    ],
    "contact_records": [
      "<string>"
    ],
    "people": [
      "<string>"
    ],
    "users_scrubbed": [
      123
    ],
    "users_retained": [
      {}
    ],
    "counts": {
      "org_users": 123,
      "event_users": 123,
      "contact_records": 123,
      "people": 123,
      "users_identified": 123,
      "users_scrubbed": 123,
      "users_retained": 123
    }
  },
  "created_at": "<string>",
  "updated_at": "<string>"
}