1. Advanced Functions
  2. API documentation
  3. Contact API

Contact API

With the contact API you can manage your contact objects easily. It offers a full CRUD implementation for contact objects and offers methods to add, remove and update contact taxonomy. 

 

URL

You can access the contact REST API with the following base URL:

https://<system_id>.<server_id>.quentn.com/public/api/V1/contact

 

Retrieve a contact [GET]

URI Parameter Required Requirements Description
fields No list List of contact fields to return.Example: family_name,phone,mail

 

Request:

GET https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>?fields=<fields> HTTP/1.1

Response:

{
  "id": 123,
  "first_name": "John",
  "family_name": "Doe",
  "mail": "johndoe@example.com",
  "terms": [1,2,3]
}

Contact Id will always be returned. If parameter fields is omitted, the following fields will be returned by default: id,first_name,family_name,mail. 

Retrieve contacts by mail [GET]

URI Parameter Required Requirements Description
fields No list List of contact fields to return.Example: family_name,phone,mail

 

Request:

GET https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_mail>?fields=<fields> HTTP/1.1

Response:

[{
  "id": 123, 
  "mail": "johndoe@example.com", 
},
{
  "id": 124, 
  "mail": "johndoe@example.com", 
}]

Please note that multiple contacts can possess the same Email address. Therefore the result is always returned as an array - even if only one contact was found.

Create contact [POST]

Request Parameter Required Requirements Description
contact Yes object

Contact object must contain either a valid mail field or a full address including the following fields: first_name, family_name, ba_street, ba_city, ba_postal_code. 

Here is a full list of available contact fields. 
duplicate_check_method No string

Defines the method that will be used to check for duplicate contacts to merge with. Possible values are:

auto : A probability algorithm will be used to search for duplicates (Default)
email : Primary email address will be used to search for duplicates
none : No duplicate check will be performed (not recommended)
duplicate_merge_method No string

Defines the method that will be used to merge the conact if a duplicate was found. Possible values are:

update_add: missing fields will be added, existing fields will be overwritten (Default)
update : Given fields overwrite existing fields (with value), missing fields (no value) won't be added
add : only missing fields will be added

 

Request:

POST https://<system_id>.<server_id>.quentn.com/public/api/V1/contact HTTP/1.1

Request body:

{
   "contact" : {
      "first_name" : "John",
      "family_name" : "Doe",
      "mail" : "johndoe@example.com",		
   },
   "duplicate_check_method" : "email",
   "duplicate_merge_method" : "update_add"
}

Response:

{
  "id": 123,
}

Create multiple contacts in one call [POST]

Request Parameter Required Requirements Description
contacts Yes object

Contacts object must contain at least one contact object with a valid mail field.  

Here is a full list of available contact fields. 
duplicate_check_method No string

Defines the method that will be used to check for duplicate contacts to merge with. Possible values are:

auto : A probability algorithm will be used to search for duplicates (Default)
email : Primary email address will be used to search for duplicates
none : No duplicate check will be performed (not recommended)
duplicate_merge_method No string

Defines the method that will be used to merge the conact if a duplicate was found. Possible values are:

update_add: missing fields will be added, existing fields will be overwritten (Default)
update : Given fields overwrite existing fields (with value), missing fields (no value) won't be added
add : only missing fields will be added

 

Request:

POST https://<system_id>.<server_id>.quentn.com/public/api/V1/contacts HTTP/1.1

Request body:

{
   "contacts" : {
      {
          "first_name" : "John",
          "family_name" : "Doe",
          "mail" : "johndoe@example.com",	
      },
      {
          "first_name" : "James",
          "family_name" : "Doe",
          "mail" : "jamesdoe@example.com",	
      },
   },
   "duplicate_check_method" : "email",
   "duplicate_merge_method" : "update_add"
}

Response:

{
  {
     "id": 123,
     "email": "johndoe@example.com",
  },
  {
     "id": 124,
     "email": "jamesdoe@example.com",
  },
}

Update contact [PUT]

Request:

PUT https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id> HTTP/1.1

Request body:

{
  "first_name": "John",
  "family_name": "Doe",
  "mail": "johndoe@example.com"
}

Response:

{
  "success": "true",
}

Delete contact [DELETE]

Request:

DELETE https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id> HTTP/1.1

Response:

{
  "success": "true",
}

Contact tags API

There are multiple ways to retrieve and set contact's tags.E.g. you could just use the above CRUD methods to set and retrieve contact's terms field. However there are situations where you may want to just add or delete a tag without (re-)setting the whole terms field.

Get contact terms[GET]

Request:

GET https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>/terms HTTP/1.1

Response:

[
  {
    "id" : 12,
    "name" : "ExampleTag",
    "description" : "Example description text"
  },
  {
    "id" : 13,
    "name" : "Sample",
    "description" : "",
  }
]

Set contact terms [POST] (DEPRECATED)

Note: by using this POST method you will overwrite the whole terms field. If you just want to add contact tags, please use the PUT method. 

Request:

POST https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>/terms HTTP/1.1

Request body:

[12,13,65]

Response:

{
  "success": "true",
}

Add contact terms [PUT]

Request:

PUT https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>/terms HTTP/1.1

Request body:

[123,555]

Response:

{
  "success": "true",
}

Delete contact terms [DELETE]

Request:

DELETE https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>/terms HTTP/1.1

Request body:

[123,555]

Response:

{
  "success": "true",
}

Contact fields

 

Field name Data type Description
title CHAR(1)

Possible values:

m : Mr. 
f : Mrs.
title2 CHAR(4)

Possible values:

dr : Dr.
prof : Prof.
first_name CHAR(255) First name
family_name CHAR(255) Family name
company CHAR(255) Company
job_title CHAR(255) Job title
mail CHAR(255) Primary email
mail_status integer

Note: You need special permissions in order for this to have an effect!

Possible values:
1 = blocked
2 = unsubscribed
3 = unknown (default)
4 = single opt in
7 = confirmed
mail2 CHAR(255) Secondary email
phone_type CHAR(6)

Possible values:

work : Work
home : Home
mobile : Mobile
other : other
phone CHAR(255) Primary phone number
phone2_type CHAR(6)

Possible values:

work : Work
home : Home
mobile : Mobile
other : other
phone2 CHAR(255) Secondary phone number
fax CHAR(255) Fax number
skype CHAR(255) Skype name
fb CHAR(255) Facebook
twitter CHAR(255) Twitter
ba_street CHAR(255) Street (Billing Address)
ba_street2 CHAR(255) Street 2 (Billing Address)
ba_city CHAR(255) City (Billing Address)
ba_postal_code CHAR(20) Postal Code (Billing Address)
ba_state CHAR(20) State (Billing Address)
ba_country CHAR(2) Country as ISO 3166-1 alpha-2. Example: DE for Germany 
date_of_birth DATETIME Date of birth as ISO 8601. Example: 2004-02-12T15:19:21+00:00 
terms LIST Contact term id's. Example: [1,2,3]

 

Custom fields

Field type Data type Description
text String Please check the individual maximum field size (ranges from 8 to 255 characters)
List selection (single value) String  
List selection (multiple values) Array Example: ["selection_a","selection_c"]
Float number Float Always use dot (.) as decimal seperator.
Integer number Integer  
Datetime mixed Expects either a unix timestamp (e.g. '1594034942'), or an ISO 8601 formatted date (e.g. '2007-12-24T18:21Z')