Requests

A Requests refers to a Data Subject Request that is a important facet of privacy laws like GDRP in Europe or CPRA in California. Most of the privacy laws give certain data rights to consumers like right of access or deletion.

The /dsar/requests endpoint of the API exposes the requests managed by Didomi for your organization. For a full reference of the endpoint and the resources that it returns, visit https://api.didomi.io/docs/.

Create a Request

When end-users want to express one of their rights, you can create a request to register the end-user application by calling the endpoint POST /dsar/requests.

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 protected]"
        }
    ],
    /**
    * 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 protected]",
        "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 he submitted the request.

To create a request with approval workflow, you can send a POST request on /dsar/requests and set the status to unverified.

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 protected]"
        }
    ],
    "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 request, you can send a PATCH request on /dsar/requests/{id}.

💡 When updating a request, we authorized edition only for status, metadata and extra_message_variables properties.

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.

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}}.