Title	Implementing the Collection Point with REST API

URL Name	UUID-b039d8c3-091a-a89b-ce4e-e26e68fcffa1

Content

The main purpose of the JavaScript SDK is to provide a quick means for implementing OneTrust Collection Points. The SDK makes use of an Open RESTful API architecture to communicate with OneTrust's systems.

An alternative to implementing the SDK is to write your own code to interact with our APIs directly. This enables you to create your own custom workflows and use the service in applications where JavaScript is not supported.

Note

For more information about OneTrust's API end points and calls, see the OneTrust Developer Portal.

Using the Consent Receipts API to Create Transactions

The Consent Receipts API allows an external application to submit a request to store consent transactions for individual Collection Points. Each Collection Point must first be set up in OneTrust to generate a valid request token.

Consent Receipts API Request Body

The following is the supported payload data when making POST calls on https://{BASEURL}/request/v1/consentreceipts.

{
  "identifier": "mail@mail.com",
  "identifierType": "Email",
  "generateInstantLinkToken", "true"         
  "dsDataElements":{                        
    "DataElement1Name": "Value",
    "DataElement2Name": "Value"
  },
  "language": "en-GB", 
  "interactionDate": "2019-05-14T01:34:33Z",                      
  "consentDate": "2019-05-14T01:34:33Z",
  "withdrawnDate" : "2018-03-01T09:00:00",  
  "customPayload":{                         
    "key1": "value1",
    "key2": "value2"
  },
  "requestInformation": "{JWT TOKEN}",      
  "purposes": [
  {
    "Id": "{GUID}",                        
    "TransactionType": "OPT_OUT",
    "ExpiryDate": "2020-01-01",
    "purposeNote": {  
        "noteId": "aa978afe-bbe9-4419-8fa9-f3691f1046c3",
        "noteType": "UNSUBSCRIBE_REASON", 
        "noteLanguage": "en-us",
        "noteText": "Reason 1",
                      }
    "CustomPreferences": [               
    {
      "Id": "{GUID}",
      "Options": [                      
      "{GUID}",                         
      "{GUID}"
      ]
    }
    ]
  },
  {
    "Id": "{GUID}",
    "CustomPreferences": [
    {
      "Id": "{GUID}",
      "Options": [
      "{GUID}",
      "{GUID}",
      "{GUID}"
      ]
    }
  ]
  }
  ]
}

Payload Data	Description
identifier	Required value for the DS identifier. The type is based on the Collection Point data element type and is not validated upon submit.
identifierType	Only supported on API type Collection Points that are set up for Dynamic Configuration. This value is required for Dynamic Configuration Collection Points. The value (e.g. "Email") must match one of the identifier data elements defined on the Data Elements list. Note This data should only be sent for Dynamic Configuration Collection Points.
dsDataElements (Optional)	Optional for capturing data element values from the Collection Point. Data Elements must be defined on the Collection Point or they will be ignored.
language (Optional)	Used to set the language for the data subject. Supports ISO code formats. Language only or language-culture code will be accepted.
interactionDate (Optional)	Only supported on API type Collection Points. Used to record the date and time of the user interaction with a Collection Point. When used in combination with a declared TransactionType, multiple different TransactionTypes can be posted and every transaction will be recorded as having happened on the interactionDate. When using interactionDate, no other dates should be included in the post. If interactionDate and one of the other dates is sent in the same post, it will generate an error. Receipts can be posted out of date order utilizing the Interaction Date on the Consent Receipts API, which can be particularly useful when sending historical consent data. This means that new incoming receipts, with an earlier Interaction Date than the last date recorded against each specific data subject profile, will create a transaction but will not update the Purpose Status. For example, if you post a WITHDRAWN receipt with an interaction date of May 3rd, followed by a NOT_GIVEN receipt for the same purpose with an earlier interaction date of May 2nd, the data subject profile would show a Purpose Status of WITHDRAWN based on the more recent interaction date. Note It is recommended that the interactionDate be used in lieu of consentDate and withdrawnDate.
customPayload (Optional)	Stores any custom data in key value pairs against the receipt. The total size of the customPayload data should not exceed 4000 characters.
requestInformation	Token generated by Collection Point. Must be used without alteration.
Purposes	The list of Purposes that consent is being given for or changed.
Purpose Id	Required value. Include only the GUIDs for Purposes that are being consented to unless using Transaction Type. Will set the consent status to either ACTIVE or PENDING status, depending on Collection Point Double Opt In setting.
TransactionType (Optional)	Only supported on API type Collection Points. Supported Values: PENDING, CONFIRMED, WITHDRAWN, EXPIRED, NOTGIVEN, EXTEND, OPT_OUT, HARD_OPT_OUT, NO_CHOICE, CHANGE_PREFERENCES, CANCEL, NO_OPT_OUT. Acceptable values may also be determined by other settings on the Collection Point. For example, PENDING will only be accepted if the Collection Point is set for Double Opt In. NO_CHOICE is currently only available for Cookie Consent type Collection Points.
ExpiryDate (Optional)	Optional explicit expiration date after which the purpose of collection is no longer valid and no further consent is collected against it. If a value is entered, it will override the consent length on the Purpose. The date should be set in the future relative to the current date and time. After the expiration date has been reached, a scheduled task will run to update the consent status to Expired. Note There may be a delay of up to 12 hours after the expiration date has been reached for the Expired status to be reflected in the data subject profile. In addition, the expiration date is not set for purposes in WITHDRAWN status. The purpose remains in WITHDRAWN status if consent was withdrawn prior to the expiration date.
purposeNote	Optional data that can include the noteId, noteType, noteLanguage, and noteText.
noteId (Optional)	UUID of a reason template. This ID must be valid or it will be ignored. Use this ID only if you want to link the note to a reason template.
noteType (Optional)	Type of the reason template. If used, the value must be UNSUBSCRIBE_REASON.
noteLanguage (Optional)	ISO code for the language of the note text.
noteText (Optional)	Text of the note to be stored with a maximum of 500 characters. If including purposeNote in your payload, this value must be present.
CustomPreferences (Optional)	Optional value based on Purpose Preferences linked to the Purpose.
Options	Purpose Preferences can be single or multi-select, optional or required, but this is not validated by the API. Setting more than one value on single select will be accepted but may result in problems when the DS logs in to a Preference Center that includes this data. Include only the GUIDs for options to be opted in to.
generateInstantLinkToken (Optional)	Flag to generate an instant access magic link token for the Preference Center that expires after one year, with a default value of false. Note This flag requires an API type collection point.

Response

The following response will be returned by the API:

{"instantLinkToken": "{JWT TOKEN}","receipt": "{JWT TOKEN}"
}

Response	Description
receipt	A JWT which contains the record of the transaction.
instantLinkToken	This token can be appended to the Preference Center login URL for a data subject login.

Modifying Preferences via the Consent Receipts API

You can pass the Consent Receipts API with the CHANGE_PREFERENCES transaction type to modify existing Purpose Preference option selections for existing data subjects. Using this transaction type allows you to explicitly opt a data subject in or out of individual preference choices without having to include all existing choices within the payload.

Things to Know

When passing the CHANGE_PREFERENCES transaction type, the following are important notes to keep in mind:

The CHANGE_PREFERENCES transaction type is only available for API type Collection Points.
There are significant differences in the Purpose Preference payload when passing this transaction type, so exercise care when implementing.
You can either declare OPT_IN as a TransactionType parameter or leave it blank to opt a data subject in to a Purpose Preference option.
Do not include the IDs for items that you are not modifying.
If there is no existing consent record for the data subject (i.e. the CHANGE_PREFERENCES transaction type is the first transaction for the data subject for these Purposes), then the consent record will be created with an ACTIVE status, and the preferences applied.
The CHANGE_PREFERENCES transactionType should only be used to modify preferences for an existing data subject with a purpose in Active status, or to create a new data subject record.

Example Payload

{
2  "identifier": "changepref@otprivacy.com",
3  "requestInformation": "{JWT}",
4  "purposes": [
5    {
6      "Id": "6ede4731-b0d3-44f9-8eca-0b82d211e084",
7      "TransactionType":"CHANGE_PREFERENCES",
8      "CustomPreferences": [
9        {
10          "Id": "a3f54f53-0747-4d98-b428-0b2316162122",
11          "Choices": [
12              {
13            "OptionId":"614bafbc-60e0-46c7-9f0f-411fcd83cbc3",
14            "TransactionType":"OPT_OUT"
15              },
16              {
17            "OptionId":"4c8bdec4-552d-4a72-9029-a218124b8c19",
18            "TransactionType":"OPT_OUT"
19              }
20            
21          ]
22        }
23        
24      ]
25    }
26  ]
27}

Bypassing the Double Opt-In Workflow

You can bypass the Double Opt-In workflow for an individual data subject interaction by passing the following parameter on the Consent Receipts API:

“doubleOptIn”: false

When a POST call is made with the additional parameter, a transaction type of CONFIRMED rather than PENDING will be generated. The data subject will then be given an ACTIVE status for all Purposes on the Collection Point.

Note

The Double Opt-In Confirmation email or custom workflow events where the identifier is not an email address will not be triggered.

Attachment

Article Total View Count 18,329

Language	English

Is Primary Language

Implementing the Collection Point with REST API

Note

Using the Consent Receipts API to Create Transactions

Consent Receipts API Request Body

Note

Note

Note

Note

Response

Modifying Preferences via the Consent Receipts API

Things to Know

Example Payload

Bypassing the Double Opt-In Workflow

Note