Mit der Kontakt-API kannst du deine Kontaktobjekte einfach verwalten. Sie bietet eine vollständige CRUD-Implementierung für Kontaktobjekte und bietet Methoden zum Hinzufügen, Entfernen und Aktualisieren der Kontakttaxonomie.

URL

Du kannst auf die Kontakt-REST-API mit der folgenden Basis-URL zugreifen:

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]
}

Die Kontakt-ID wird immer zurückgegeben. Wenn der Parameter fields weggelassen wird, werden standardmäßig die folgenden Felder zurückgegeben: 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", 
}]

Bitte beachte, dass mehrere Kontakte die gleiche E-Mail-Adresse besitzen können. Daher wird das Ergebnis immer als Array zurückgegeben - auch wenn nur ein Kontakt gefunden wurde.

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. When field comment is provided, a new comment will be added. 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. When field comment is provided, a new comment will be added for the corresponding contact. 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

Es gibt mehrere Möglichkeiten, die Tags von Kontakten abzurufen und zu setzen, z.B. kannst du einfach die oben genannten CRUD-Methoden verwenden, um das Feld "Begriffe" des Kontakts zu setzen und abzurufen. Es gibt jedoch Situationen, in denen du vielleicht nur ein Tag hinzufügen oder löschen möchtest, ohne das gesamte Feld "Begriffe" (erneut) zu setzen.

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)

Hinweis: Wenn du diese POST-Methode verwendest, überschreibst du das gesamte Begriffsfeld. Wenn du nur Kontakt-Tags hinzufügen möchtest, verwende bitte die PUT-Methode.

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",
}

Verfügbare Kontaktfelder

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).

Kontaktfeld-Typen (eigene Kontaktfelder)

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')

URL

Retrieve a contact [GET]

Retrieve contacts by mail [GET]

Create contact [POST]

Create multiple contacts in one call [POST]

Update contact [PUT]

Delete contact [DELETE]

Contact tags API

Get contact terms [GET]

Set contact terms [POST] (DEPRECATED)

Add contact terms [PUT]

Delete contact terms [DELETE]

Contact comments API

Retrieve contact comments [GET]

Add contact comment [POST]

Update contact comment [PUT]

Delete contact comments [DELETE]

Verfügbare Kontaktfelder

Kontaktfeld-Typen (eigene Kontaktfelder)

Verwandte Beiträge