Show Menu
TOPICS×

Privacy jobs

This document covers how to work with privacy jobs using API calls. Specifically, it covers the use of the /job endpoint in the Privacy Service API. Before reading this guide, refer to the getting started section for important information that you need to know in order to successfully make calls to the API, including required headers and how to read example API calls.
If you are trying to manage consent or opt-out requests from customers, refer to the consent endpoint guide .

List all jobs

You can view a list of all available privacy jobs within your organization by making a GET request to the /jobs endpoint.
API format
This request format uses a regulation query parameter on the /jobs endpoint, therefore it begins with a question mark ( ? ) as shown below. The response is paginated, allowing you to use other query parameters ( page and size ) to filter the response. You can separate multiple parameters using ampersands ( & ).
GET /jobs?regulation={REGULATION}
GET /jobs?regulation={REGULATION}&page={PAGE}
GET /jobs?regulation={REGULATION}&size={SIZE}
GET /jobs?regulation={REGULATION}&page={PAGE}&size={SIZE}

Parameter
Description
{REGULATION}
The regulation type to query for. Accepted values are gdpr , ccpa , lgpd_bra , and pdpa_tha .
{PAGE}
The page of data to be displayed, using 0-based numbering. The default is 0 .
{SIZE}
The number of results to display on each page. The default is 1 and the maximum is 100 . Exceeding the maximum causes the API to return a 400-code error.
Request
The following request retrieves a paginated list of all jobs within an IMS Organization, starting from the third page with a page size of 50.
curl -X GET \
  https://platform.adobe.io/data/core/privacy/jobs?regulation=gdpr&page=2&size=50 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'

Response
A successful response returns a list of jobs, with each job containing details such as its jobId . In this example, the response would contain a list of 50 jobs, starting on the third page of results.

Accessing subsequent pages

To fetch the next set of results in a paginated response, you must make another API call to the same endpoint while increasing the page query parameter by 1.

Create a privacy job

Before creating a new job request, you must first collect identifying information about the data subjects whose data you want to access, delete, or opt out of sale. Once you have the required data, it must be provided in the payload of a POST request to the /jobs endpoint.
Compatible Adobe Experience Cloud applications use different values for identifying data subjects. See the guide on Privacy Service and Experience Cloud applications for more information on required identifiers for your application(s). For more general guidance on determining which IDs to send to Privacy Service, see the document on identity data in privacy requests .
The Privacy Service API supports two kinds of job requests for personal data:
While access and delete requests can be combined as a single API call, opt-out requests must be made separately.

Create an access/delete job

This section demonstrates how to make an access/delete job request using the API.
API format
POST /jobs

Request
The following request creates a new job request, configured by the attributes supplied in the payload as described below.
curl -X POST \
  https://platform.adobe.io/data/core/privacy/jobs \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -d '{
    "companyContexts": [
      {
        "namespace": "imsOrgID",
        "value": "{IMS_ORG}"
      }
    ],
    "users": [
      {
        "key": "DavidSmith",
        "action": ["access"],
        "userIDs": [
          {
            "namespace": "email",
            "value": "dsmith@acme.com",
            "type": "standard"
          },
          {
            "namespace": "ECID",
            "type": "standard",
            "value":  "443636576799758681021090721276",
            "isDeletedClientSide": false
          }
        ]
      },
      {
        "key": "user12345",
        "action": ["access","delete"],
        "userIDs": [
          {
            "namespace": "email",
            "value": "ajones@acme.com",
            "type": "standard"
          },
          {
            "namespace": "loyaltyAccount",
            "value": "12AD45FE30R29",
            "type": "integrationCode"
          }
        ]
      }
    ],
    "include": ["Analytics", "AudienceManager"],
    "expandIds": false,
    "priority": "normal",
    "analyticsDeleteMethod": "anonymize",
    "regulation": "ccpa"
}'

Property
Description
companyContexts (Required)
An array containing authentication information for your organization. Each listed identifier includes the following attributes:
  • namespace : The namespace of an identifier.
  • value : The value of the identifier.
It is required that one of the identifiers uses imsOrgId as its namespace , with its value containing the unique ID for your IMS Organization.
Additional identifiers can be product-specific company qualifiers (for example, Campaign ), which identify an integration with an Adobe application belonging to your organization. Potential values include account names, client codes, tenant IDs, or other application identifiers.
users (Required)
An array containing a collection of at least one user whose information you would like to access or delete. A maximum of 1000 user IDs can be provided in a single request. Each user object contains the following information:
  • key : An identifier for a user that is used to qualify the separate job IDs in the response data. It is best practice to choose a unique, easily identifiable string for this value so it can easily be referenced or looked up later.
  • action : An array that lists desired actions to take on the user's data. Depending on the actions you want to take, this array must include access , delete , or both.
  • userIDs : A collection of identities for the user. The number of identities a single user can have is limited to nine. Each identity consists of a namespace , a value , and a namespace qualifier ( type ). See the appendix for more details on these required properties.
For a more detailed explanation of users and userIDs , see the troubleshooting guide .
include (Required)
An array of Adobe products to include in your processing. If this value is missing or otherwise empty, the request will be rejected. Only include products that your organization has an integration with. See the section on accepted product values in the appendix for more information.
expandIDs
An optional property that, when set to true , represents an optimization for processing the IDs in the applications (currently only supported by Analytics). If omitted, this value defaults to false .
priority
An optional property used by Adobe Analytics that sets the priority for processing requests. Accepted values are normal and low . If priority is omitted, the default behavior is normal .
analyticsDeleteMethod
An optional property that specifies how Adobe Analytics should handle the personal data. Two possible values are accepted for this attribute:
  • anonymize : All data referenced by the given collection of user IDs is made anonymous. If analyticsDeleteMethod is omitted, this is the default behavior.
  • purge : All data is removed completely.
regulation (Required)
The regulation for the request. Must be one of the following four values:
  • gdpr
  • ccpa
  • lgpd_bra
  • pdpa_tha
Response
A successful response returns the details of the newly created jobs.
{
    "jobs": [
        {
            "jobId": "6fc09b53-c24f-4a6c-9ca2-c6076b0842b6",
            "customer": {
                "user": {
                    "key": "DavidSmith",
                    "action": [
                        "access"
                    ]
                }
            }
        },
        {
            "jobId": "6fc09b53-c24f-4a6c-9ca2-c6076be029f3",
            "customer": {
                "user": {
                    "key": "user12345",
                    "action": [
                        "access"
                    ]
                }
            }
        },
        {
            "jobId": "6fc09b53-c24f-4a6c-9ca2-c6076bd023j1",
            "customer": {
                "user": {
                    "key": "user12345",
                    "action": [
                        "delete"
                    ]
                }
            }
        }
    ],
    "requestStatus": 1,
    "totalRecords": 3
}

Property
Description
jobId
A read-only, unique system-generated ID for a job. This value is used in the next step of looking up a specific job.
Once you have successfully submitted the job request, you can proceed to the next step of checking the job's status .

Check the status of a job

You can retrieve information about a specific job, such as its current processing status, by including that job's jobId in the path of a GET request to the /jobs endpoint.
Data for previously created jobs is only available for retrieval within 30 days of the job's completion date.
API format
GET /jobs/{JOB_ID}

Parameter
Description
{JOB_ID}
The ID of the job you want to look up. This ID is returned under jobId in successful API responses for creating a job and listing all jobs .
Request
The following request retrieves the details of the job whose jobId is provided in the request path.
curl -X GET \
  https://platform.adobe.io/data/core/privacy/jobs/6fc09b53-c24f-4a6c-9ca2-c6076b0842b6 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'

Response
A successful response returns the details of the specified job.
{
    "jobId": "6fc09b53-c24f-4a6c-9ca2-c6076b0842b6",
    "requestId": "15700479082313109RX-899",
    "userKey": "David Smith",
    "action": "access",
    "status": "complete",
    "submittedBy": "{ACCOUNT_ID}",
    "createdDate": "10/02/2019 08:25 PM GMT",
    "lastModifiedDate": "10/02/2019 08:25 PM GMT",
    "userIds": [
        {
            "namespace": "email",
            "value": "dsmith@acme.com",
            "type": "standard",
            "namespaceId": 6,
            "isDeletedClientSide": false
        },
        {
            "namespace": "ECID",
            "value": "1123A4D5690B32A",
            "type": "standard",
            "namespaceId": 4,
            "isDeletedClientSide": false
        }
    ],
    "productResponses": [
        {
            "product": "Analytics",
            "retryCount": 0,
            "processedDate": "10/02/2019 08:25 PM GMT",
            "productStatusResponse": {
                "status": "complete",
                "message": "Success",
                "responseMsgCode": "PRVCY-6000-200",
                "responseMsgDetail": "Finished successfully."
            }
        },
        {
            "product": "Profile",
            "retryCount": 0,
            "processedDate": "10/02/2019 08:25 PM GMT",
            "productStatusResponse": {
                "status": "complete",
                "message": "Success",
                "responseMsgCode": "PRVCY-6000-200",
                "responseMsgDetail": "Success dataSetIds = [5dbb87aad37beb18a96feb61], Failed dataSetIds = []"
            }
        },
        {
            "product": "AudienceManager",
            "retryCount": 0,
            "processedDate": "10/02/2019 08:25 PM GMT",
            "productStatusResponse": {
                "status": "complete",
                "message": "Success",
                "responseMsgCode": "PRVCY-6054-200",
                "responseMsgDetail": "PARTIALLY COMPLETED- Data not found for some requests, check results for more info.",
                "results": {
                  "processed": ["1123A4D5690B32A"],
                  "ignored": ["dsmith@acme.com"]
                }
            }
        }
    ],
    "downloadURL": "http://...",
    "regulation": "ccpa"
}

Property
Description
productStatusResponse
Each object within the productResponses array contains information about the current status of the job with respect to a specific Experience Cloud application.
productStatusResponse.status
The job's current status category. See the table below for a list of available status categories and their corresponding meanings.
productStatusResponse.message
The job's specific status, corresponding to the status category.
productStatusResponse.responseMsgCode
A standard code for product response messages received by Privacy Service. The details of the message are provided under responseMsgDetail .
productStatusResponse.responseMsgDetail
A more detailed explanation of the job's status. Messages for similar statuses may vary between products.
productStatusResponse.results
For certain statuses, some products may return a results object that provides additional information not covered by responseMsgDetail .
downloadURL
If the status of the job is complete , this attribute provides a URL to download the job results as a ZIP file. This file is available to download for 60 days after the job completes.

Job status categories

The following table lists the different possible job status categories and their corresponding meaning:
Status category
Meaning
complete
Job is complete and (if required) files are uploaded from every application.
processing
Applications have acknowledged the job and are currently processing.
submitted
Job is submitted to every applicable application.
error
Something failed in the processing of the job - more specific information may be obtained by retrieving individual job details.
A submitted job might remain in a processing state if it has a dependent child job that is still processing.

Next steps

You now know how to create and monitor privacy jobs using the Privacy Service API. For information on how to perform the same tasks using the user interface, see the Privacy Service UI overview .