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) |
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) |
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) |
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) |
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. |
title2 | CHAR(4) |
Possible values: dr : Dr. |
first_name | CHAR(255) | First name |
family_name | CHAR(255) | Family name |
company | CHAR(255) | Company |
job_title | CHAR(255) | Job title |
CHAR(255) | Primary email | |
mail_status | integer |
Note: You need special permissions in order for this to have an effect! Possible values: |
mail2 | CHAR(255) | Secondary email |
phone_type | CHAR(6) |
Possible values: work : Work |
phone | CHAR(255) | Primary phone number |
phone2_type | CHAR(6) |
Possible values: work : Work |
phone2 | CHAR(255) | Secondary phone number |
fax | CHAR(255) | Fax number |
skype | CHAR(255) | Skype name |
fb | CHAR(255) | |
CHAR(255) | ||
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') |