# Data Subject Requests

We currently support two data subject request types **`access`** & **`erasure` .**

 **Access** will let you determine if you have stored that data subjects identity anywhere in Poplar (&/or Share Local Media if you are also a SLM Solo, Shared or Insert client). 

**Erasure** will submit an erasure (deletion) request for a data subject's identity within your account. This will scan across mailings, orders, and audiences. Note: that erasure requests **do not** apply within your opt out list. When you submit an erasure request we will also automatically add the data subject identity to your opt out list to prevent them from being mailed by you in the future.

## Create Data Subject Request

<mark style="color:green;">`POST`</mark> `https://api.heypoplar.com/v1/dsr/request`

Use this endpoint to create a data subject request for one or more subject identities.

#### Headers

| Name                                            | Type   | Description                                                               |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer [ProductionAccessToken](https://docs.heypoplar.com/api/api/master) |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json                                                          |

#### Request Body

| Name                                                     | Type   | Description                                                                                             |
| -------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| api\_version                                             | string | <p>The API version of the request.</p><p></p><p>Supported values are:  <code>v1</code></p>              |
| regulation<mark style="color:red;">\*</mark>             | string | <p>The regulation for the DSR request.</p><p></p><p>Supported values are: <code>cpra</code></p>         |
| subject\_request\_id<mark style="color:red;">\*</mark>   | string | The unique UUID v4 identifier for this request.                                                         |
| subject\_request\_type<mark style="color:red;">\*</mark> | string | <p>The type of request.</p><p></p><p>Supported values are: <code>access</code> <code>erasure</code></p> |
| submitted\_time<mark style="color:red;">\*</mark>        | string | ISO8601 formatted datetime representing the time the request was made by the data subject.              |
| subject\_identities<mark style="color:red;">\*</mark>    | array  | An array of [subject identity objects.](#undefined)                                                     |

{% tabs %}
{% tab title="201: Created Data Subject Request Created" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="400: Bad Request Incorrectly formatted or missing data" %}

```json
{
  "error": {
     "name": "ValidationError"
     "message": {
       ...
     }
}
```

{% endtab %}

{% tab title="403: Forbidden Incorrect or missing auth header" %}

```json
{
  "error": "Missing or Invalid Authorization Header"
}
```

{% endtab %}
{% endtabs %}

### Subject Identity Objects

A subject data request requires an array of subject identity objects. A request can contain multiple subject identity objects but all subject identities should be for the same user. For example, a data subject request may contain a subject identity object for a user's email and one for their address.

Subject identity objects should contain the following fields:

<table><thead><tr><th width="225.33333333333331">Key</th><th width="164">Value Type</th><th>Description</th></tr></thead><tbody><tr><td><code>identity_type</code></td><td>string</td><td><strong>Required</strong><br><br>The type of identity.<br><br>Supported options are: <code>email</code> <code>address</code></td></tr><tr><td><code>identity_format</code></td><td>string</td><td><strong>Required</strong><br><br>The format of the identity value<br><br>Supported formats are: <code>raw</code></td></tr><tr><td><code>identity_value</code></td><td>string | object</td><td><strong>Required</strong><br><br>For address requests, an identity address object; For all other request types, the value string.</td></tr></tbody></table>

The `identity_value` object for address request should contain the following fields:

<table><thead><tr><th width="224">Key</th><th width="169.33333333333331">Value Type</th><th>Description</th></tr></thead><tbody><tr><td><code>full_name</code></td><td>string</td><td>Optional</td></tr><tr><td><code>first_name</code></td><td>string</td><td>Optional</td></tr><tr><td><code>last_name</code></td><td>string</td><td>Optional</td></tr><tr><td><code>address_1</code></td><td>string</td><td><strong>Required</strong> <br><br><em>Address number and street name</em></td></tr><tr><td><code>address_2</code></td><td>string</td><td>Optional <br><br><em>Apt/Suite/Unit/etc.</em></td></tr><tr><td><code>city</code></td><td>string</td><td><strong>Required</strong></td></tr><tr><td><code>state</code></td><td>string</td><td><strong>Required</strong></td></tr><tr><td><code>postal_code</code></td><td>string</td><td><strong>Required</strong></td></tr></tbody></table>

## Fetch Data Subject Request Status&#x20;

<mark style="color:blue;">`GET`</mark> `https://api.heypoplar.com/v1/dsr/request/:subject_request_id`

This endpoint allows you to query the status of a data subject request.

#### Path Parameters

| Name                                                   | Type   | Description                                    |
| ------------------------------------------------------ | ------ | ---------------------------------------------- |
| subject\_request\_id<mark style="color:red;">\*</mark> | string | The `subject_request_id` from the POST request |

{% tabs %}
{% tab title="200: OK Successful Deletion Request" %}

```json
{
  "controller_id": "87f42076-3bcc-4e93-a72a-a0703746ec98",
  "subject_request_id": "e93693d5-5d99-4c45-8993-b31684426a38",
  "request_status": "completed",
  "result": "deleted",
}
```

{% endtab %}

{% tab title="403: Forbidden Incorrect or missing auth header" %}

```json
{
  "error": "Missing or Invalid Authorization Header"
}
```

{% endtab %}

{% tab title="404: Not Found subject\_request\_id is incorrect or does not exist" %}

```javascript
{
  "error": {
    "name": "NotFound",
    "message": "Data Subject Request not found"
  }
}
```

{% endtab %}

{% tab title="200: OK Request in Progress" %}

```javascript
{
  "controller_id": "87f42076-3bcc-4e93-a72a-a0703746ec98",
  "expected_completion_time": "2022-11-19T19:48:43.514+00:00",
  "subject_request_id": "e93693d5-5d99-4c45-8993-b31684426a38",
  "request_status": "in_progress"
}
```

{% endtab %}

{% tab title="200: OK Successful Request – No Results Found" %}

```javascript
{
  "controller_id": "87f42076-3bcc-4e93-a72a-a0703746ec98",
  "subject_request_id": "e93693d5-5d99-4c45-8993-b31684426a38",
  "request_status": "completed",
  "result": "not_found",
}
```

{% endtab %}

{% tab title="200: OK Successful Access Request" %}

```javascript
{
  "controller_id": "87f42076-3bcc-4e93-a72a-a0703746ec98",
  "subject_request_id": "e93693d5-5d99-4c45-8993-b31684426a38",
  "request_status": "completed",
  "result": "found",
  "data": [
    {
      "category": "address",
      "email": "johndoe@example.com"
    },
    {
      "category": "address",
      "address_1": "1640 Riverside Drive",
      "city": "Hill Valley",
      "state": "CA",
      "postal_code": "91103"
    }
  ]
}
```

{% endtab %}
{% endtabs %}