> ## Documentation Index
> Fetch the complete documentation index at: https://segmentflow.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Privacy requests

> Export everything Segmentflow holds about a profile, and track your access and erasure requests.

When a person asks what data you hold about them (GDPR Art. 15) or asks you to erase it (Art. 17), you record a privacy request. The privacy request API lets you request a profile data export, follow its status, download it, and list every access and erasure request of your organization. The same requests show on the **Privacy requests** page under Settings in the dashboard.

Privacy requests keep working when your subscription has lapsed, so you can always meet your legal duties.

## Who can call it

Only organization owners and admins. With an API Key, the key's creator must be an owner or admin when the call is made, and the key needs the scope below. Other callers get `403`.

## Request an export

Send either `profileId` or `email`:

```bash theme={null}
curl -X POST https://api.segmentflow.ai/api/v1/privacy-requests/exports \
  -H "x-api-key: $SEGMENTFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com" }'
```

The response is `202` with the request's `id` and `status`. The export is built in the background, usually within a few minutes. A profile that doesn't exist, or that was erased, returns `404`.

### Repeated requests

A profile has at most one export being built at a time. While its export is `pending` or `running`, another request returns that same request with `created: false` and starts nothing new. Once the export is `ready`, `failed` or `expired`, a new request starts a new export with `created: true`.

## Follow the status

```bash theme={null}
curl https://api.segmentflow.ai/api/v1/privacy-requests/$REQUEST_ID \
  -H "x-api-key: $SEGMENTFLOW_API_KEY"
```

| `status` | Meaning |
| - | - |
| `pending`, `running` | The request is being worked on. |
| `ready` | The export can be downloaded until `expiresAt`. |
| `expired` | The export was deleted 7 days after it was built. Request a new one. |
| `completed` | The erasure finished, or an export request found no data held about the person, so there is nothing to export. |
| `failed` | The request failed; `failureReason` holds a code such as `build_failed`. |

`subject` holds the profile's `profileId` and `email` while the profile exists. After the profile is erased or deleted, `subject` is `null` and `subjectReference` is a masked identifier of the person, never their email.

## Download an export

```bash theme={null}
curl -X POST https://api.segmentflow.ai/api/v1/privacy-requests/$REQUEST_ID/download-link \
  -H "x-api-key: $SEGMENTFLOW_API_KEY"
```

The response holds a `url` that works for 5 minutes (`expiresIn` seconds) and a `fileName`. The file is a ZIP with one versioned JSON document.

The endpoint returns `409` when there is nothing to download yet or anymore. The error's `details.status` says why:

* `pending` or `running`: the export is still being built. Try again when its status is `ready`.
* `failed`: the export couldn't be built. Request a new export.
* `expired`: the export was deleted 7 days after it was built. Request a new export.
* `completed`: no data was held about the person, so there is no export. This happens for requests from Shopify's `customers/data_request` when no profile matches or the store's data was already deleted.

An erasure request has no download, and returns `404`, like a request of another organization.

## List requests

```bash theme={null}
curl "https://api.segmentflow.ai/api/v1/privacy-requests?limit=50" \
  -H "x-api-key: $SEGMENTFLOW_API_KEY"
```

Requests come newest first, access and erasure together. Pass the response's `nextCursor` as `cursor` to read the next page; it is `null` on the last page. `limit` is at most 100.

## Required scopes

* `privacy-requests:read` - list and retrieve privacy requests, and get export download links.
* `privacy-requests:write` - request profile data exports.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.