DocumentationExperience PlatformPrivacy Service Guide

Privacy jobs endpoint

Last update: Thu Nov 07 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer

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

NOTE
If you are trying to manage consent or opt-out requests from customers, refer to the consent endpoint guide.

List all jobs list

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. When listing resources, the Privacy Service API returns up to 1000 jobs and paginates the response. Use other query parameters (page, size, and date filters) to filter the response. You can separate multiple parameters using ampersands (&).

TIP
Use additional query parameters to further filter results for specific queries. For example, you can discover how many privacy jobs were submitted over a given period of time and what their status is using the status, fromDate, and toDate query parameters.
GET /jobs?regulation={REGULATION}
GET /jobs?regulation={REGULATION}&page={PAGE}
GET /jobs?regulation={REGULATION}&size={SIZE}
GET /jobs?regulation={REGULATION}&page={PAGE}&size={SIZE}
GET /jobs?regulation={REGULATION}&fromDate={FROMDATE}&toDate={TODATE}&status={STATUS}
Parameter
Description
{REGULATION}

The regulation type to query for. Accepted values include:

  • apa_aus
  • ccpa
  • cpa_usa
  • cpra_usa
  • ctdpa_usa
  • dpdpa
  • fdbr_usa
  • gdpr
  • hipaa_usa
  • icdpa_usa
  • lgpd_bra
  • mcdpa_usa
  • mhmda_usa
  • ndpa_usa
  • nhpa_usa
  • njdpa_usa
  • nzpa_nzl
  • ocpa_usa
  • pdpa_tha
  • ql25
  • tdpsa_usa
  • ucpa_usa
  • vcdpa_usa

See the overview on supported regulations for more information on the privacy regulations that the above values represent.

{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 100 and the maximum is 1000. Exceeding the maximum causes the API to return a 400-code error.
{status}

The default behavior is to include all statuses. If you specify a status type, the request returns only privacy jobs that match that status type. The accepted values include:

  • processing
  • complete
  • error
{toDate}
This parameter limits results to those processed before a specified date. From the date of the request, the system can can look back 45 days. However, the range cannot be more than 30 days.
It accepts the format YYYY-MM-DD. The date you provide is interpreted as the termination date expressed in Greenwich Mean Time (GMT).
If you do not provide this parameter (and a corresponding fromDate), the default behavior returns jobs that data back over the last seven days. If you use toDate, you must also use the fromDate query parameter. If you do not use both, the call returns a 400 error.
{fromDate}
This parameter limits results to those processed after a specified date. From the date of the request, the system can can look back 45 days. However, the range cannot be more than 30 days.
It accepts the format YYYY-MM-DD. The date you provide is interpreted as the request’s date of origin expressed in Greenwich Mean Time (GMT).
If you do not provide this parameter (and a corresponding toDate), the default behavior returns jobs that data back over the last seven days. If you use fromDate, you must also use the toDate query parameter. If you do not use both, the call returns a 400 error.
{filterDate}
This parameter limits results to those processed on a specified date. It accepts the format YYYY-MM-DD. The system can look back over last 45 days.

Request

The following request retrieves a paginated list of all jobs within an 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: {ORG_ID}'

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 create-job

IMPORTANT
Privacy Service is only meant for data subject and consumer rights requests. Any other usage of Privacy Service for data cleanup or maintenance is not supported or allowed. Adobe has a legal obligation to fulfill them in a timely manner. As such, load-testing on Privacy Service is not allowed as it is a production only environment and creates an unnecessary backlog of valid privacy requests.
A hard daily upload limit is now in place to help prevent abuse of the service. Users found to abuse the system will have their access to the service disabled. A subsequent meeting will then be held with them to address their actions and discuss the acceptable use for Privacy Service.

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.

NOTE
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:

IMPORTANT
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 access-delete

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: {ORG_ID}' \
  -d '{
    "companyContexts": [
      {
        "namespace": "imsOrgID",
        "value": "{ORG_ID}"
      }
    ],
    "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","profileService"],
    "expandIds": false,
    "priority": "normal",
    "mergePolicyId": 124,
    "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 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 users 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.
mergePolicyId
When making privacy requests for Real-Time Customer Profile (profileService), you can optionally provide the ID of the specific merge policy that you want to use for ID stitching. By specifying a merge policy, privacy requests can include audience information when returning data on a customer. Only one merge policy can be specified per request. If no merge policy is provided, segmentation information is not included in the response.
regulation (Required)

The regulation for the privacy job. The following values are accepted:

  • apa_aus
  • ccpa
  • cpra_usa
  • gdpr
  • hipaa_usa
  • lgpd_bra
  • nzpa_nzl
  • pdpa_tha
  • vcdpa_usa

See the overview on supported regulations for more information on the privacy regulations that the above values represent.

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 check-status

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.

IMPORTANT
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: {ORG_ID}'

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

recommendation-more-help
9cbf7061-a312-49f7-aaf8-a10885d53580