Authentication
All requests to the API are authenticated by providing your API key. The API key should be provided as an HTTP header named Api-Token.
Header
curl -H "Api-Token: YOUR_TOKEN" https://account.api-us1.com/api/3/
Your API key can be found in your account on the Settings page under the Developer tab. Each user in your QuarticOn CDXP account has their own unique API key.
Remember to keep your API key secret. Do not share it and take care not to expose it publicly in client-side code. |
Base URL
The API is accessed using a base URL that is specific to your account. In the examples provided in this documentation, we use the URL youraccountname.api-us1.com as a stand-in for your real account API URL. Your API URL can be found in your account on the My Settings page under the Developer tab. In addition, URL paths should begin with /api/3 to specify version 3 of the API. Generally, the URL will be in the form:
https://{account}.api-us1.com/api/3/{endpoint}
You have to log in into your account on QuarticOn CDXP, go to the page Settings → Developer and insert data appropriately:
All API calls should be made over HTTPS.
Rate Limits
Our API has a rate limit of 5 requests per second per account.
Property
The data type of the value stored in the field. Valid types are currency, date, datetime, number, text, and textarea.
Type Name | Description | Notes |
text | A short text field | Limited to 65,535. Longer strings will not be saved. |
textarea | A text field of any length |
|
number | An integer or decimal number | Number of decimals saved can be defined with the additional scale field. Scale can be set to 0 to denote integer values – this is the default. |
datetime | A valid ISO8601 date time string (e.g. 2021-08-13T17:51:44+00:00) |
|
date | A date string in the format YYYY-MM-DD (e.g. 2011-12-23) |
|
dropdown | A field to capture a single value from a predefined list of options. | Options need to be defined in the additional options field. |
multiselect | A field to capture multiple values from a predefined list of options. | Options need to be defined in the additional options field. |
currency | A value containing numbers representing a currency value. | The value is a three-character ISO 4217 currency code. The value defaults to "USD". |
How to synchronise contact database?
1. Create a contact
Here are the list of standard fields:
email string (required)
E-mail address of the new contact. Example: 'test@example.com'
firstName string
First name of the new contact.
lastName string
Last name of the new contact.
phone string
Phone number of the contact.
fieldValues array
Contact's custom field values [{field id, value}]
curl -X POST https://domena_klienta_api/api/3/contact/sync
-H "Api-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-d '{
"contact": {
"email": "johndoe@example.com",
"firstName": "John",
"lastName": "Doe",
"phone": "7223224221",
"fieldValues":[
{
"field":"1",
"value":"Contact Street"
},
{
"field":"2",
"value":"Contact zip Code"
},
{
"field":"3",
"value":"Contact City"
},
{
"field":"7",
"value":"Male"
}
]
}}'
2. List all custom fields
IDs of custom fields are provided in a separate xls document by QuarticOn Team. However you can generate the field.id by executing the following request:
curl --request GET \
--url 'https://youraccountname.api-us1.com/api/3/fields?limit=100' \
--header 'Accept: application/json' \
--header 'api-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
In the response you will find a Field id in Fields.ID.
3. Update a contact
curl -X PUT https://domena_klienta_api/api/3/contact/sync
-H "Api-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-d '{
"contact": {
"email": "johndoe@example.com",
"firstName": "John",
"lastName": "Doe",
"phone": "7223224221",
"fieldValues":[
{
"field":"1",
"value":"Contact Street"
},
{
"field":"2",
"value":"Contact zip Code"
},
{
"field":"3",
"value":"Contact City"
},
{
"field":"7",
"value":"Male"
}
]
}}'
4. Assigning a contact to the Account or LIST (Consent)
QuarticOn configures the accounts and lists in QuarticOn CDXP panel.
For assigning a contact to the account or list you need to get the Contact.ID.
Please execute the following request to get the Contact.ID based on e-mail address.
curl https://domena_klienta_api/api/3/contacts?email=second@somewhere.com
-H "Accept: application/json,
Api-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx "
4.1. Assigning to the account
IDs of accounts (there should be separated account per each shop or domain) are provided in a separate document by QuarticOn Team.
Please execute the following request due to assigning the contact to the account:
curl -X POST https://domena_klienta_api/api/3/accountContacts
-H "Api-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-d '{
"accountContact": {
"contact": contact.id,
"account": 1
}
}'
4.2 Consents; Subscribing to the lists
IDs of lists are provided in a separate document by QuarticOn Team:
Please execute the following request due to assigning the contact to the proper list:
Consent to market communication
Status = 0 Unconfirmed,
Status = 1 Subscribed,
Status = 2 Unsubscribed,
curl -X POST https://domena_klienta_api/api/3/contactLists
-H "Api-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-d '{
"contactList": {
"list": 1,
"contact": contact.id,
"status": 1
}
}'
5. Deleting
Please execute the following request due to delete the contact from the the system:
curl --request DELETE \
--url https://youraccountname.api-us1.com/api/3/contacts/contact.id \
--header 'Accept: application/json' \
--header 'api-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
Webhook – QuarticOn CDXP notifies about contact data change or events
Webhooks provide the ability to receive real-time data updates about your contact.
Choose to receive data based on certain actions (subscribes, unsubscribes, update, etc.) and have all applicable data sent to a URL of your choice. You can then use your own custom script to read, save, and do whatever you want with that data. This is a powerful option that allows you to keep all of your data in sync and opens up the possibility of all sorts of integration options.
With every webhook you create you can choose when it should actually fire. Perhaps you only want to receive data when a contact is added from the API. You can simply specify subscribe as the event and api as the source when you create your webhook. You can specify multiple events and sources for each webhook if you wish. All event and source options are listed below.
We strive to have “at least one” webhook event delivered. There are times that you could receive a webhook event more than once, so it’s important to create an idempotent system.
Adding Webhook from Quarticon CDXP panel
Webhooks are automated messages sent from the system when something happens. There should be at least one webhook configured for the event “Unsubscription”.
To set up webhook please login to the QuarticOn CDXP panel and click:
Settings ->Developer.
Then click in right corner at the top Manage Webhooks.
Here you can find all previously configured webhooks.
Click Add for adding a new one.
Every webhook has to be connected with lists – it is possible to choose one list or all lists. The exception is a webhook with creation of a new list;
Name – name of webhook;
URL – the address, where webhook is to be sent;
Type – the events which call out the webhook.
Key events are highlighted with yellow colour:
Webhook can be configured with API:
WEBHOOK OBJECT
name string required
A name (or label) to give this webhook.
url string required
The URL where the webhook will send the POST request when the event occurs.
events array of strings required
The event(s) that will trigger the webhook to fire.
sources array of strings required
The source(s) causing an event to occur.
The example of webhook request is below:
{
"contact":{
"customer_acct_name" : "",
"email": "jan@testowy.pl",
"first_name": "jan",
"id": 4,
"ip": "0.0.0.0",
"last_name":"test",
"orgname": "",
"phone":"+48555555555",
"tags":""
},
"list":[
{
"id": 0,
"name": "Lista testowa"
}
],
"tags":"",
"customer_acct_id": 0,
"customer_acct_name":"",
"date_time": "2022-07-18T05:59:35-05:00",
"initiated_by":"contact",
"initiated_from":"public",
"orgname":"",
"type": "unsubscribe"
}
Please find more here:
You can read more about webhooks here.