Skip to main content

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
return_fields No array

Defines additional contact fields, which should be returned in case of success. This makes sense for example, when you have duplicates.
request_ip No string

The IPv4 address which belongs to the contact, for example from the request which submitted a form. This field needs to be present when using "flood_limit" or "spam_protection".
This parameter has to be part of the contact object.
flood_limit No int

The maximum number of contacts which can be created from the same "request_ip" within an hour. (0 = disabled)
spam_protection No bool

When this is set, the "request_ip" will be checked against a spammer database.

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",	
      "request_ip" : "123.123.123.123",	
   },
   "duplicate_check_method" : "email",
   "duplicate_merge_method" : "update_add",
   "return_fields" : [
      "mail_status","mail","first_name","family_name",
   ],
   "flood_limit" : 5,
   "spam_protection" : true
}

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
return_fields No array

Defines additional contact fields, which should be returned in case of success. This makes sense for example, when you have duplicates.
request_ip No string

The IPv4 address which belongs to the contact, for example from the request which submitted a form. This field needs to be present when using "flood_limit" or "spam_protection".
This parameter has to be part of the contact object.
flood_limit No int

The maximum number of contacts which can be created from the same "request_ip" within an hour. (0 = disabled)
spam_protection No bool

When this is set, the "request_ip" will be checked against a spammer database.

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",
	  "request_ip" : "123.123.123.123", 
      },
      {
          "first_name" : "James",
          "family_name" : "Doe",
          "mail" : "jamesdoe@example.com",	
          "request_ip" : "123.123.123.123", 
      },
   ],
   "duplicate_check_method" : "email",
   "duplicate_merge_method" : "update_add",
   "return_fields" : [
      "mail_status","mail","first_name","family_name",
   ],
   "flood_limit" : 5,
   "spam_protection" : true
}

Response:

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

Example response in case of single contact creation error:

[
  {
     "id": 123,
     "email": "johndoe@example.com",
  },
  {    
     "email": "jamesdoe@example.com",
     "error": true,
     "message": "The error message"
  },
]

 

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",
  "return_fields" : [
     "mail_status","mail","first_name","family_name",
   ]
}

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 comments API

Retrieve contact comments [GET]

URI Parameter Required Requirements Description
range No int Defines the range of comments which should be returned. Starts from 0. Default = 0.
limit No int Defines the number of comments which should be returned. Default = 50. Upper limit = 50.
sort No string Defines the order of the results. Results are always ordered by id. Possible values: "asc" and "desc". Default = "asc".

Request:

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

Response:

{
  "range": 1,
  "limit": 10,
  "sort": "desc",
  "number_comments": 12,
  "number_ranges": 2,
  "comments": [
    {
      "id": 8,
      "contact_id": 93,
      "uid": 2,
      "created": 1627980505,
      "changed": 1627980505,
      "comment": "this is a comment",
    },
    {
      "id": 9,
      "contact_id": 93,
      "uid": 2,
      "created": 1627980614,
      "changed": 1627980728,
      "comment": "this is another comment",
    }
  ]
}

 

Add contact comment [POST]

Request:

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

Request body:

{
  "comment": "this is a comment"
}

Response:

{
  "success": "true",
  "comment_id": 5,
}

 

Update contact comment [PUT]

Request:

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

Request body:


{
  "id": 5,
  "comment": "this is an updated comment"
}

Response:

{
  "success": "true",
}

 

Delete contact comments [DELETE]

Request:

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

Request body:

[123,555]

Response:

{
  "success": "true",
}

 

Available 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
5 = confirmed (manually)
6 = confirmed (import)
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]
created integer Contact's creation date as unix timestamp (Read only)
uid integer User ID of contact's owner
owner mixed When field is read, an object will be returned which contains:
uid: integer (user ID)
mail: string (user's email address)

When field is set, it accepts either integer (uid) or string (mail).

 

Available Fields Types (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')
 

Related articles