# Requests A Request refers to a Data Subject Request that is an important facet of privacy laws like GDPR in Europe or CPRA in California. Most privacy laws give certain data rights to consumers like the right of access or deletion. The `/dsar/requests` endpoint of the API exposes `requests` managed by Didomi for your organization. For a full reference of the endpoint and the resources that it returns, visit . ## Create a Request When end-users want to express one of their rights, you can create a request to register the end-user request by calling the endpoint **POST** `/dsar/requests`. ```json POST https://api.didomi.io/dsar/requests?organization_id={{organization_id}} { "organization_user_id": "organization_user_id", "user_right_id": "cpra_access_my_data", "status": "verified", "request_fields": [ { "field_id": "email", /** * This value is required to send emails to the end-user */ "value": "email@address.com" } ], /** * Fill in the user property in order to set user's information at its creation. * If no user exists with the organization_user_id provided, * Didomi will be creating this new user on your behalf * with data provided in user property */ "user": { "email": "email@address.com", "metadata": {}, "id": "String", "country": "String" }, "source": { "type": "DSAR", "country": "String" } } ``` | Entity | Type | Mandatory | Description | | ---------------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `organization_user_id` | String | Yes | ID of your end-user. An email is recommended so our system can send emails to your end-users each time you change the request status. | | `user_right_id` | Enum | Yes | ID of the User Right activated by the end-user. Value should be of the following `cpra_access_my_data`, `cpra_delete_my_data` or `cpra_opt_out`. | | `status` | Enum | Yes | Status of the Privacy Request. Status can be either `unverified`, `verified`, `work_in_progress`, `fulfilled`, `archived`, `refused`. | | `request_fields` | Array | No | Group of additional fields that can be requested to the end-user to submit a Privacy Request. Includes `email` authentication field that needs to be filled in with end-user email address. This will allow our system to send them emails while you are proceeding with the request. | | `source.type` | String | Yes | Type of widget from which the request has been created (for a privacy request, type will always be `DSAR`). | ### Country When a privacy request is created from a Privacy request widget, our SDK will apply the end-user location to the created request. You can reproduce the same workflow when using Didomi API by setting the `country` property either in `user` or `source` entity. | Property | Type | Mandatory | Description | | ---------------- | ------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user.country` | String | No | It corresponds to the user country. If the user does not exist yet in Didomi DB, we will create it and apply the value of `user.country` to the `country` property in Users ressource. | | `source.country` | String | No | It corresponds to the country from where the request has been formulated. You can attach a country to a request by setting `source.country`. | ## Create a Request with approval workflow Didomi supports email approval method where a request needs to be approved before being considered as `verified`. To require identity confirmation, you can set the status to `unverified` and this will send an email to the user after the user submits the request. To create a request with approval workflow, you can send a **POST** request on `/dsar/requests` and set the status to `unverified`. ```json POST https://api.didomi.io/dsar/requests?organization_id={{organization_id}} { "organization_user_id": "organization_user_id", "user_right_id": "cpra_access_my_data", "status": "unverified", "request_fields": [ { "field_id": "email", /** * This value is mandatory to use Didomi as the sender of communication * with your end-users throughout the whole request process. * For instance, it will send confirmation identity email to your end-user * if the status is set to unverified while creating the request */ "value": "email@address.com" } ], "source": { "type": "DSAR" } } ``` ## Update a Request You can update requests in order to match the actual state of the request within your processing workflow or to attach further information to your request. To update a request, you can send a **PATCH** request on `/dsar/requests/{id}`. 💡 When updating a request, we authorize editing only for `status`, `metadata` and `extra_message_variables` properties. ```json PATCH https://api.didomi.io/dsar/requests/{id} { "status": "NEW STATUS", "metadata": {}, "extra_message_variables": { "download_link": "YOUR LINK" } } ``` Provide a download link to your end-user by filling in the property `download_link` while you are updating the status of a **data access** request to `fulfilled`. ## Query a list of Requests To fetch the list of Privacy Requests of your organization, you can send a **GET** request on `https://api.didomi.io/dsar/requests`. ```json GET https://api.didomi.io/dsar/requests?organization_id={{organization_id}} [ { "id": "String", "created_at": "Date", "updated_at": "Date", "organization_id": "String", "organization_user_id": "String", "status": "String", "metadata": {}, "source_id": "String", "validation_id": "String", "user_right_id": "String", "regulation_id": "String", "expires_at": "Date", "domain": null, "source": { "id": "String", "created_at": "Date", "updated_at": "Date", "type": "DSAR", "key": null, "deployment_id": null, "country": "String" }, "validation": { "id": "String", "created_at": "Date", "updated_at": "Date", "type": "email", "approve_url": "String" }, "request_fields": [ { "id": "String", "created_at": "Date", "updated_at": "Date", "request_id": "String", "field_id": "email", "value": "String", "field": { "id": "email", "created_at": "Date", "updated_at": "Date", "organization_id": null, "user_right_id": null, "label": { "en": "Email address *" }, "placeholder": { "en": "Enter your email address" }, "description": { "en": "In order to proceed ..." }, "hint": { "en": "We are the responsible party ..." }, "type": "email", "usage": "auth", "validations": [ "required", "email" ], "subscribers": [ "trim_value", "to_lower_case" ] } } ] } ] ``` You can also query a specific request by ID. To fetch a request, you can send a **GET** request on `https://api.didomi.io/dsar/requests/{{id}}`.