Contacts

A contact is a record in the user database that contains at least an e-mail address and is not associated with any survey on the account.

To add a respondent to a survey, a contact must be created. A contact is a link between a respondent entity and a survey.

Both contacts and respondents do not have to be unique within a user account.

Operations on respondents are located in the next section called Respondents

List of operations for the resource

Name	URL	Description
List of contacts	`/contacts`	Returns a list of contacts. Contacts are sorted alphabetically by email address.
Searching for contacts	`/contacts/search`	Searches for contacts by criteria passed in the `POST` array.
Adding a contact	`/contacts/add`	Adds a contact to the contact list of the logged-in user.
Adding a contact (offline distribution)	`/contacts/add-offline`	Adds a contact to the contact list (for offline distribution, email is not required).

Description of response parameters

Name/path	Description	Possible values
`id`	Contact ID
`email`	E-mail address
`label1`	Value of the first optional attribute. The attribute is active if it has been defined in the user account.
`label2` ....`label15`	Value of subsequent optional attributes (from 2 to 15). The attribute is active if it has been defined in the user account.

List of contacts

URL

(GET) https://app.customerhero.com/api/v2/contacts

Optional parameters (POST)

Name	Description
`limit`	Limit on the number of completions
`offset`	List offset

Example response

{
	"total":"20",
	"list":[{
		"id":100824,
		"email":"jan@kowalski.pl",
		"label1":"Jan",
		"label2":"Kowalski",
		"label3":"600 700 800",
		"label4":"",
		"label5":""
	},{
		...
	}]
}

Returned errors

401 Unauthorized – If the user references a foreign resource.
404 Not Found – If no contacts are found.

Searching for contacts

URL

(GET) https://app.customerhero.com/api/v2/contacts/search

Optional parameters (POST)

Name	Description
`limit`	Limit on the number of completions
`offset`	List offset
`email`	Searching for a respondent by email address
`label1`	Searching for a respondent by the value of attribute 1
`labeln`	Searching for a respondent by the value of attribute n

Example response

{
	"total":"20",
	"list":[{
		"id":100824,
		"email":"jan@kowalski.pl",
		"label1":"Jan",
		"label2":"Kowalski",
		"label3":"600 700 800",
		"label4":"",
		"label5":""
	},{
		...
	}]
}

Returned errors

401 Unauthorized – If the user references a foreign resource.

Adding contacts

URL

(GET) https://app.customerhero.com/api/v2/contacts/add

Parameters (POST)

Name	Description
`email`	E-mail address (mandatory parameter)
`label1`	Value of attribute 1
`labeln`	Value of attribute n

Example response

{ 
"id_contact":"149768" 
}

Returned errors

406 Not Acceptable – If mandatory parameters are not passed.

Adding offline contacts (without an e-mail address)

URL

(GET) https://app.customerhero.com/api/v2/contacts/add

Parameters (POST)

Name	Description
`user_token`	User token (mandatory parameter)
`label1`	Value of attribute 1
`labeln`	Value of attribute n

Example response

{ 
"id_contact":"149768" 
}

Returned errors

406 Not Acceptable – If mandatory parameters are not passed.