How to sync your contacts with a CRM or a Marketing Automation tool

Since THRON collects and leverages customer interests in order to help you increasing your lead generation, it might be useful to retrieve all the information collected on contacts and perform an export or implement a sync procedure towards a CRM or marketing automation tool to keep it always synchronized with the present state of  the art in THRON.

To achieve these purposes, THRON provides specific APIs.

 

Requirements

In order to invoke contact management APIs you will have to use the token of a THRON Custom Application Manager so before going on, make sure you have enabled at least one application of this type and you have granted such application with the permission to manage contacts; this can be done from the management screen of the specific application.

Then you will have to obtain the application's token, hence you will have to authenticate using the app's credentials. Further information can be found here.

 

Contacts synchronization

The first thing to do is to obtain the whole list of contacts present in THRON. To do that you will have to use the export web service. This service is used to export all contacts matching given criteria. For each contact, the request will return the following information:

  • itags: all the tags linked to the specific contact;
  • keys: all the identities collected on the specific contact (e.g: THRON username, e-mail address)
  • createdDate: the date on which the contact has been created;
  • accessedDate: the date of the latest contact's interaction with THRON;
  • oldIds: all the deviceIds used by the contact;
  • contactType: the type of contact. Can be ANONYMOUS or IDENTIFIED;
  • name: the full name of the contact;
  • id: the current contactId.

The resultset is paginated (max page size is 200 elements), after the first request the service returns a " nextPage" parameter which provides an identifier to be used on the subsequent request in order to get the following elements. If the " nextPage" is missing it means that you are on the last page of the result set.

The url of the web service is structured as follows:

//<clientId>-view.thron.com/contactunit/xcontact/resources/sync/export/<clientId>

In the body of the request you can paste the following JSON, filling required parameters:


{
    "criteria": {
        "contactType": ""
    },
    "options": {
        "itags": true,
        "keys": true
    },
    "nextPage": "",
    "pageSize": 0
}     

 

Where:

  • contactType: is used to filter the specific contact type to be retrieved. Available values are ANONYMOUS, IDENTIFIED.
  • itags: set this parameter to true if you wish to retrieve tags.
  • keys: set this parameter to true if you wish to retrieve identities.

 

For a proper synchronization between the different tools make sure to include the THRON's contactId as a contact-related information in your CRM. This will make searches easier.

At the same time, rely on your CRM/MA tool's API to extract the list of contacts generated so far, and make sure you provide all the information to THRON to keep both instruments aligned. In particular, contact profiling tags in the CRM can be included as tags in the TARGET classification, and can be used to tag the contact in THRON. Identities can be added to the contact via a dedicated API, in particular make sure you add the CRM ID to the contact in THRON, in order to speed up searches.

To do that, the first thing to do is to retrieve the ID of your TARGET classification. This can be done via classification/list request. The url is structured as follows:

//<clientId>-view.thron.com/api/xintelligence/resources/classification/list/<clientId>

In the body of the request you can paste the following JSON:


{
    "criteria": {
        "active": true,
        "removed": false,
        "classificationType": [
          "TARGET" 
        ]
    }
}    

Look for the "id" parameter in the response, it corresponds to the classificationId of your TARGET classification. 

Now, make sure to map all the tags of your CRM with your TARGET taxonomy. To create a new tag you will have to use  the itagdefinition/insert request. The url of the request is structured as follows:

//<clientId>-view.thron.com/api/xintelligence/resources/itagdefinition/insert/<clientId>/<classificationId>

In the body of the request, you can paste the following JSON, filling required parameters:


{
"value": {
  "parentId": "<tagId of the parent tag>",
   "names": [
     {
        "lang":"EN",
        "label": "<label for the tag>"
}
    ],
    "pos":0,
    "prettyId": "<prettyId for the tag>",
    "categorized": true
  }
}    

 Where:

  • parentId: If you want to place the new tag within another tag you will have to provide its tagId here;
  • names: an array of objects containing the names of the tag for each language;
    • lang: the language code (e.g. EN);
    • label: the actual name of the tag;
  • pos: the position of the tag in the tree;
  • prettyId: the name of the tag to be used on API requests.

To assign a tag to a specific contact you can refer to the procedure illustrated in this article.

Finally, to add specific identities collected by the CRM to a specific contact, you must use the contact/addKey request.

The url is structured as follows:

//<clientId>-view.thron.com/contactunit/xcontact/resources/contact/addKey/<clientId>

In the body of the request you can paste the following JSON, filling required parameters:


{
  "contactId": "<contactId here>",
  "ik": {
    "key": "<name of the identity here>",
    "value": "<value of the identity here>"
  }
}    

In particular, be sure to assign to each THRON contact the identity of his/her ID in the CRM. This will allow you to significantly speed up your searches and more quickly trace back to a single customer view of a contact.

 

Check contacts update status

Once the first synchronization has been put in place, you will have to keep the lists always up-to date. To do that you have to use the updatedContacts web service. This service is used to retrieve the list of contacts which have been modified within a specific time range.

In the response you will get the following information for each contact that has been updated in the give time range:

  • removed: if this boolean is true, it means the contact has been deleted.
  • itags: all the tags linked to the specific contact;
  • keys: all the identities collected on the specific contact (e.g: THRON username, e-mail address)
  • createdDate: the date on which the contact has been created;
  • accessedDate: the date of the latest contact's interaction with THRON;
  • oldIds: the contact ids before profiling (typically its deviceIds when anonymous);
  • contactType: the type of contact. Can be ANONYMOUS or IDENTIFIED;
  • name: the full name of the contact;
  • id: the current contactId.

The resultset is paginated (max page size is 200 elements), after the first request the service returns a " nextPage" parameter which provides an identifier to be used on the subsequent request in order to get the following elements. If the " nextPage" value is empty it means that you are on the last page of the result set. A 10 minutes interval between two initial requests should be considered; no wait is needed when requesting subsequent pages.

The url of the web service is structured as follows:

 

//<clientId>-view.thron.com/contactunit/xcontact/resources/sync/updatedContacts/<clientId>

 

In the body of the request you can paste the following JSON, filling required parameters: 


{
    "criteria": {
        "fromDate": "",
        "toDate": "",
        "contactType": ""
    },
    "options": {
        "itags": false,
        "keys": true
    },
    "nextPage": "",
    "pageSize": 0
}    

 

Where:

 

  • fromDate: it is the starting date of the time interval to be considered. It has to be expressed in the form: yyyy-mm-dd. The value of this parameter cannot be older than two months. If you need to retrieve content older than two months you will have to perform an extract request.
  • toDate: the end date of the time interval to be considered. It has to be expressed in the form: yyyy-mm-dd.
  • contactType: is used to filter the specific contact type to be retrieved. Available values are ANONYMOUS, IDENTIFIED.
  • itags: set this parameter to true if you wish to retrieve tags.
  • keys: set this parameter to true if you wish to retrieve identities.

 

Notes: Dates are recorded into platform with the UTC format so that each user can retrieve it according to its timezone. 

 

Was this article helpful?
0 out of 0 found this helpful

Have any question?

Open a ticket
Comments