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]

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]

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:

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" : [
      "email-status","mail","first_name","family_name",
   ],
   "flood_limit" : 5,
   "spam_protection" : true
}

Response:

{
  "id": 123,
}

Create multiple contacts in one call [POST]

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" : [
      "email-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" : [
     "email-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 fields

Custom fields