Mapping a Single API

Single APIs can be used if the third party system is able to perform an atomic operation with just one API. For example, we can use “Single API” if the use case is to create or update data for a Consent or Data Subject Type in a third party system, then if that system supports creating or updating data using a single REST API.

1. Select Single API from the Add New Rest API dropdown list to begin adding migration criteria and setting up the integration.
   
   
   
   
2. In the Settings tab, click Add Criteria to add the criteria to be applied on the map. Click the dropdown button on a selected criteria to add a value. You can select multiple criteria as needed. Data Transfer will be carried out by running this particular REST API only if all the Migration Criteria are satisfied.
   
   
   
   If you selected a Single Line text form field as one of your migration criteria, you can set the condition to any of the following:

• • Equal or Not Equal - if the value is “Equal to [Form Field Value]” or “Not Equal to [Form Field Value],” then the system executes the integration if the criteria is met.
    
    
  • Null or Not Null - If the value is “Null” or “Not Null,” the input field will be disabled and will be shown as null or not null, then the system will execute the integration if the criteria is met.
    
    

3. Select whether the Integration Data Flow (1) is for CPM to a Third Party or vice versa:

• • CPM to a Third Party system - This indicates that the consent data is sent from CPM to the Third Party system. Create/Update REST APIs should be set accordingly for this option.
    
    You can enable the Sync back to the System of Origin checkbox to send the mapped data back to the system where the consent originally came from. This feature enables you to send tokens back to the Third Party system. Note that this feature is only applicable to CPM to Third Party Rapid API integration. In addition, enabling this feature may cause an infinite loop. 
    
    
  • Third Party system to CPM - This indicates that the consent data is brought over from the Third Party system and recorded in CPM. REST APIs to fetch the data should be set accordingly for this option.
    

Then select a use case for API Usage (2) from the list. Each use case can pair to any API method:

• • Create or Update Consents - Select this to create or update Consents/Data Subjects from CPM to third party systems.
    
    
  • Delete Consents in systems - Select this to delete Consents/Data Subjects from CPM to third party systems.

NOTE: The trigger to execute any REST API in CPM to Third Party Rapid API is creation of new Consents and Data Subjects or change of details for a Data Subject record. Currently, the “Delete” operation is not executed when a Consent or Data Subject is deleted. This will be supported in the future.

Then, set the mapping (3) to Not Required if the current API call is not required, or set it to Required to execute the API calls at all times if there are updates.



The Run Jobs section (4)  allows customers to set the Rapid API execution to Batch Processing or Real-time execution. The Real-time Processing executes the REST API once for each Consent created and can only be enabled by the TrustArc support. Select Batch Processing to collect the Consents received and execute REST API once for all those Consents.

We recommend Batch Processing operation as it uses a lesser number of REST API calls to the Third Party system. You can set it to run every 15 minutes to 72 hours.

NOTE: Third Party to CPM Rapid API integration only supports Batch Processing whereas CPM to Third Party Rapid API integration supports both Batch Processing and Real-time execution.

In the CPM to Third Party batch integration, you may send the Consent data or Data Subject data from CPM to the Third Party system either in the JSON body as an array of records or as a CSV file. Similarly, in Third Party to CPM batch integration, you may receive the Consent data or Data Subject data from the Third Party system either in the JSON body as an array of records or as a CSV file. 

4. In the URL tab, select the HTTPS Method to use in the workflow (1).
   
   
   

• • GET - Select this to read data from the third party system.
  • PUT - Select this to update or create data in the third party system.
  • POST - Select this to create a new row in the third party system.
  • DELETE - Select this to delete data in the third party system.
  • PATCH - Select this to modify the data in the third party system.
    

Enter the custom API URL (2) and Variables in the URL (3). To use Variables in the URL input, it must be formatted specifically as [[${variable}]]. For example, https://www.website.com/[[${variable}]] once the variable is entered in the Variables section. Note that these variables are different from URL Parameters. URL Parameters are entered in the next Tab.

5. In the Params tab, enter a Key and select a Value from the dropdown list, as applicable for URL Parameters. The Key and Values defined here are added to the URL as URL Parameters. Values can be one of the Form Fields or Metadata shown in the dropdown or static strings.
   
   
   You can click Add Param to add more parameters or Remove All to delete all the parameters you listed. You can also click the Delete button on each parameter to delete them individually.
   
   CPM also supports Run Time mapping. The two values supported are Current Run Time and Last Run Time.
   
   
   
   The system runs the Batch API at (hh:mm) for 15 minute intervals. For example, hh:00, hh:15, hh:30, and hh:45. For the 00:15 minute run, the Current Run Time looks like yyyy:mm:dd hh:15:00 (in UTC format) and the Last Run Time looks like yyyy:mm:dd hh:00:00 (in UTC format).

6. In the Headers tab, enter a Key and select a Value from the dropdown list, as applicable.
   
   
   
   In this Headers tab, you can add all the Keys and Values that need to be sent in the REST API’s header. The value for the key can be a static string such as “abc” or it can be a metadata or a Consent field. If Consent data fields or Consent metadata fields are mapped, then the values for these variables are substituted at the time of the REST API execution.
   
   
7. In the Body tab, you can enter the Body of the REST API. You can click {} Edit in Code to input payload as the JSON body or use the Edit in Table feature to input the body. In this case, the hierarchy inside the JSON can be added using “.”. You may see an Array Key or File Key field.

• • Array Key corresponds to where the Consent Data starts in the Body as an Array. 
  • File Key corresponds to where the Consent Data starts in the Body as a CSV file.

To send properties inside the Array, use arrayKey[0].property. To send data inside the CSV file, use fileKey[0].property.



Click Add Attribute to add more attributes. You can click Remove All to delete all the attributes you listed or the Delete button on each attribute to delete them individually.

The Change Format functionality enables you to change format if the mapped field types are Checkbox, Toggle Switch, Group Checkbox, and Group Toggle Switch to any field type. If a checkbox on the CPM form is Opt-in checkbox and the corresponding checkbox in a Third Party system is Opt-out checkbox, then “Change Format” allows mapping between these.

8. If you select Third Party Integration to CPM as Integration Data Flow, CPM dynamically adds the Response Mapping tab, where you can map the Rapid API output to Consent Form fields. CPM uses this mapping to create the Consent data from the output of the Rapid API. Here, you may see Array Key or File Key field. 

• • Array Key corresponds to where the Consent Data starts in the output of the REST API as an Array. 
  • File Key corresponds to where the Consent Data starts in the output of the REST API as a CSV file. 

Click Settings to select the Double Opt-in setting to use. You can select from the following options, then click Save Settings:

• • Do Not Execute Double Opt-in - This is the default setup, where CPM does not send Double Opt-in notification regardless if the Jurisdiction is declared in the consent form.
    
    
  • Execute by Consent Status and Jurisdiction - If this is selected, then the user has to map the Consent Status field by making it mandatory, auto-populated, and cannot be deleted. If the user re-selects other options, then the status is automatically removed and the user will manually add it back, if needed. Then, the status will no longer be mandatory.
    
    
  • Execute by Jurisdiction - If selected, CPM executes Double Opt-in regardless of the consent status, as long as the Jurisdiction is enabled for Double Opt-in in the Jurisdiction page and in the consent form.
    
    
    

9. Then, click Save to save the integration set up or you can also click Save & Add Another API to add more APIs.
   
   
10. You can click View Consent Form or View Data Subject Type to open the consent form or data subject type in another tab.
    
    
    
    
11. To test the Integration you mapped, click the Consent Form URL in the Publish tab of the consent form to submit the Consent.
    
    
    
    
12. To check the integration logs during testing or live data transfer, go to Consent & Preferences > Setup > Logs > Integration Transfers.
    
    Sample Successful API Call
    
    
    Sample Failed API Call