Contacts
GET /contacts
Sending GET request to this url, returns collection of CONTACTS resources.
You can narrow down list of resources by passing proper query parameters (list of which you can find below in request params section). You can basically search by:
- email,
- name,
- createdOn
- changedOn
- campaignId.
`email` and `name` fields can be a pattern (like @wp.pl) and we will try to match this phrase.
`createdOn` field have it's own subfields: `from` and `to`. You can specify only one of them or both. Date format must be send in Y-m-d format.
`campaignId`field can contain more than one id's - just separate them by comma [,].
If you use more than one of above fields we will combine them using AND logic.
You can specify which page of results you want and how many results per page should be there. You can also specify sort-order using one or more of allowed fields (listed below in request params section).
Last but not least you can even specify which fields from resource you want to get. If you pass param `fields` with list of fields (separated by comma [,]) we will return list of resources with only those fields (we will always add resource id to ensure that you can use that data later on).
changedOn
is never null. If the contact has never been updated, the field will be equal to createdOn
value.
NOTE: Resources returned by this method do not include custom fields assigned to the contact. To get the custom fields, please use the GET /contacts/{contactId} method.
Returns status code
200
Request url
/contacts?query[email]=@wp.pl&fields=name,email,campaign&sort[createdOn]=desc&page=4&perPage=30
Request params
Field name | Field type | Field description | |||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
query | hash | Used to search only resources that meets criteria. You can specify multiple parameters, then it uses AND logic.
| |||||||||||||||||||||||||||
fields | string | List of fields that should be returned. Id is always returned. Fields should be separated by comma | |||||||||||||||||||||||||||
sort | hash | Enable sorting using specified field (set as a key) and order (set as a value). You can specify multiple fields to sort by.
| |||||||||||||||||||||||||||
page | integer | Specify which page of results return. | |||||||||||||||||||||||||||
perPage | integer | Specify how many results per page should be returned | |||||||||||||||||||||||||||
additionalFlags | string | Additional flags parameter with value 'exactMatch' will search contacts with exact value of email and name provided in query string. Without that flag matching is done via standard 'like' comparison, what could be sometimes slow. |
Example Response
[
{
"contactId": "V",
"href": "https://api.getresponse.com/v3/contacts/V",
"name": "John Smith",
"email": "jsmith@example.com",
"note": "best contact ever",
"dayOfCycle": null,
"origin": "iphone",
"createdOn": "2014-09-29T12:25:55+0000",
"changedOn": "2014-10-29T12:25:55+0000",
"campaign": {
"campaignId": "V",
"name": "Test campaign",
"href": "https://api.getresponse.com/v3/campaigns/V"
},
"timeZone": "America/St_Johns",
"ipAddress": "127.0.0.1",
"activities": "https://api.getresponse.com/v3/contacts/V/activities",
"scoring": 10
},
{
"contactId": "p",
"href": "https://api.getresponse.com/v3/contacts/p",
"name": "Jane Smith",
"email": "janesmith@exampl.com",
"note": null,
"origin": "sale",
"createdOn": "2014-06-29T00:55:11+0000",
"changedOn": "2014-06-29T00:55:11+0000",
"campaign": {
"campaignId": "V",
"name": "Test campaign",
"href": "https://api.getresponse.com/v3/campaigns/V"
},
"timeZone": "America/Juneau",
"ipAddress": "127.0.0.1",
"activities": "https://api.getresponse.com/v3/contacts/p/activities",
"scoring": null
}
]
POST /contacts
Sending a POST request to this url, will create a new CONTACT resource.
In order to create a new CONTACT, you need to send CONTACT resource in BODY of the request (remember that you need to serialize body into JSON string)
Because adding a contact to a campaign is not an instant process (there is a queue involved) you will receive a 202 Accepted response.
Contact processing usually takes less than one minute. If you can not see recently added contact on the contact list, make sure to check list of Bounced and Unconfirmed contacts. Please refer to our FAQ's section related to contacts for more details.
Please note that adding a contact through the API does not trigger sending a subscription notification to the account owner.
Returns status code
202
Example Request Body
{
"name": "Jan Kowalski",
"email": "jan.kowalski@wp.pl",
"dayOfCycle": "10",
"campaign": {
"campaignId": "jf7e3jn"
},
"tags": [
{
"tagId": "Xw"
},
{
"tagId": "Nn"
}
],
"scoring": 25,
"customFieldValues": [
{
"customFieldId": "n",
"value": [
"white"
]
}
],
"ipAddress": "89.206.36.193"
}
Body params
Field name | Field type | Field description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
name | string | Name of the contact (length 2-128) | |||||||||
email (required) | string | Email of the contact (must be unique per campaign) | |||||||||
dayOfCycle | integer | Day of autoresponder cycle | |||||||||
campaign (required) | object | Target campaign resource that this contact should be added to. You must specify campaignId inside this resource!
| |||||||||
customFieldValues | collection | Collection of customFieldValues that should be assign to contact
| |||||||||
ipAddress | string | IP address of a contact (IPv4 or IPv6) | |||||||||
scoring | integer | Contact scoring, pass null to disable scoring for this contact | |||||||||
tags | collection | Collection of tags that should be assigned to the contact
|
Possible Errors
POST /contacts/{contactId}
Sending POST request to this url allows to change property of an contact. You need to attach CONTACT resource in the request body. You can send only those field that should be changed. In case of custom fields and tags we REPLACE all contact custom fields/tags with those you send with this request. If campaign is updated then contact will be moved from old campaign to new while retaining it's activity history and statistics from previous campaign.
Returns status code
200
Example Request Body
{
"name": "Jan Kowalski",
"note": "test",
"dayOfCycle": "10",
"campaign": {
"campaignId": "pv2e"
},
"tags": [
{
"tagId": "Xw"
},
{
"tagId": "Nn"
}
],
"customFieldValues": [
{
"customFieldId": "n",
"value": [
"white"
]
}
]
}
Body params
Field name | Field type | Field description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
name | string | Name of the contact (length 2-128) | |||||||||
campaign | object | Move contact to this campaign. Contacts activities and statistics from previous campaign will remain
| |||||||||
note | string | Additional note about an contact | |||||||||
dayOfCycle | integer | Day of autoresponder cycle, 0-9999 | |||||||||
scoring | integer | Contact scoring, pass null to disable scoring for this contact | |||||||||
tags | collection | Collection of tags that should be assign to contact
| |||||||||
customFieldValues (required) | collection | Collection of customFieldValues that should be assign to contact
|
Example Response
{
"contactId": "V",
"href": "https://api.getresponse.com/v3/contacts/V",
"campaign": {
"campaignId": "V",
"name": "asdbasdfbsdbsd",
"href": "https://api.getresponse.com/v3/campaigns/V"
},
"name": "John Smith",
"email": "jsmith@example.com",
"note": null,
"origin": "iphone",
"dayOfCycle": "175",
"createdOn": "2014-09-29 12:25:55",
"changedOn": null,
"geolocation": {
"latitude": "54.3608",
"longitude": "18.6583",
"continentCode": "EU",
"countryCode": "PL",
"region": "82",
"postalCode": null,
"dmaCode": null,
"city": "Gdansk"
},
"timeZone": "America/St_Johns",
"ipAddress": "102.170.128.19",
"scoring": 10,
"tags": [
{
"tagId": "Xw"
},
{
"tagId": "Nn"
}
],
"customFieldValues": [
{
"customFieldId": "V",
"href": "https://api.getresponse.com/v3/custom-fields/p",
"value": [
"84"
]
},
{
"customFieldId": "p",
"href": "https://api.getresponse.com/v3/custom-fields/n",
"value": [
"mercedes"
]
},
{
"customFieldId": "rs",
"href": "https://api.getresponse.com/v3/custom-fields/T",
"value": [
"white",
"black"
]
}
],
"activities": "https://api.getresponse.com/v3/contacts/V/get-activities"
}
Possible Errors
DELETE /contacts/{contactId}
Calling this url will remove this contact from your account. If you have the same contact in multiple campaigns this will remove only one which is attached to particular campaign
You can use this action to manually unsubscribe contact. Just add query parameter 'messageId' to the request (eg. /contacts/05lx?messageId=7tgd5). This will act in the same way like when user clicks unsubscribe link in the message with id '7tgd5'. You can also provide IP Address for that request (/contacts/05lx?messageId=7tgd5&ipAddress=195.100.100.1) we will log this as the user unsubscribe IP address. This feature comes in handy when you have custom footer in your newsletters and you want to handle unsubscription process yourself.
Returns status code
204
Request url
/contacts/V?messageId=jT6&ipAddress=195.100.100.1
Request params
Field name | Field type | Field description |
---|---|---|
messageId | string | ID of message |
ipAddress | string | User unsubscribe IP address |
GET /contacts/{contactId}
Sending GET request to this url, returns single CONTACT resource. You must specify contactId in the request URL.
The only query parameter you can specify is `fields` which allows you to narrow down list of fields that will be return in resource body (we will always add resource id to ensure that you can use that data later on). You can specify which field to return by passing them as a list separated by comma [,]
Returns status code
200
Request url
/contacts/V?fields=name,email,campaigns
Request params
Field name | Field type | Field description |
---|---|---|
fields | string | List of fields that should be returned. Id is always returned. Fields should be separated by comma |
Example Response
{
"contactId": "V",
"href": "https://api.getresponse.com/v3/contacts/V",
"name": "John Smith",
"email": "jsmith@example.com",
"note": null,
"origin": "iphone",
"dayOfCycle": "175",
"createdOn": "2014-09-29 12:25:55",
"changedOn": null,
"campaign": {
"campaignId": "V",
"name": "asdbasdfbsdbsd",
"href": "https://api.getresponse.com/v3/campaigns/V"
},
"geolocation": {
"latitude": "54.3608",
"longitude": "18.6583",
"continentCode": "EU",
"countryCode": "PL",
"region": "82",
"postalCode": null,
"dmaCode": null,
"city": "Gdansk"
},
"timeZone": "America/St_Johns",
"ipAddress": "102.170.128.19",
"tags": [],
"customFieldValues": [
{
"customFieldId": "V",
"href": "https://api.getresponse.com/v3/custom-fields/V",
"value": [
"84"
]
},
{
"customFieldId": "p",
"href": "https://api.getresponse.com/v3/custom-fields/p",
"value": [
"mercedes"
]
},
{
"customFieldId": "rs",
"href": "https://api.getresponse.com/v3/custom-fields/rs",
"value": [
"white",
"black"
]
}
],
"activities": "https://api.getresponse.com/v3/contacts/V/activities",
"scoring": 10
}
GET /contacts/{contactId}/activities
NOTE: Fields in "resource" object are set for activity related to: newsletters, splittests, autoresponders and rss-newsletters. Values are null for other types of messages.
By default, only activities from the last 14 days are returned. To get earlier data, use query[createdOn]
parameter.
Returns status code
200
Request url
/contacts/V/activities?query[createdOn][from]=2012-12-12&query[createdOn][to]=2015-12-12
Request params
Field name | Field type | Field description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
query | hash | Used to search only resources that meets criteria. You can specify multiple parameters, then it uses AND logic.
| |||||||||
fields | string | List of fields that should be returned. Fields should be separated by comma | |||||||||
page | integer | Specify which page of results return. | |||||||||
perPage | integer | Specify how many results per page should be returned |
Example Response
[
{
"activity": "send",
"subject": "Integration Test GetResponse",
"createdOn": "2015-09-14T09:55:52+0000",
"previewUrl": "http://www.grnewsletters.com/archive/campaign_name55f6b0ff01/Test-2135303.html",
"resource": {
"resourceId": "TX44E",
"resourceType": "newsletters",
"href": "https://api.getresponse.com/v3/newsletters/TX44E"
}
},
{
"activity": "send",
"subject": "Integration Test GetResponse",
"createdOn": "2015-09-14T09:54:47+0000",
"previewUrl": "http://www.grnewsletters.com/archive/campaign_name55f6b0ff01/Test-2134803.html",
"resource": {
"resourceId": null,
"resourceType": null,
"href": null
}
}
]
POST /contacts/{contactId}/custom-fields
The method allows adding and updating contacts custom field values. This method does not remove custom fields.
Returns status code
200
Example Request Body
{
"customFieldValues": [
{
"customFieldId": "n",
"value": [
"white"
]
}
]
}
Body params
Field name | Field type | Field description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
customFieldValues (required) | collection | Collection of customFieldValues that should be upserted to contact
|
Example Response
{
"customFieldValues": [
{
"customFieldId": "n",
"value": [
"white"
]
}
]
}
Possible Errors
POST /contacts/{contactId}/tags
The method allows assigning tags to contact. This method does not unassign them.
Returns status code
200
Example Request Body
{
"tags": [
{
"tagId": "n"
}
]
}
Body params
Field name | Field type | Field description | ||||||
---|---|---|---|---|---|---|---|---|
tags (required) | collection | Collection of tags that should be assigned to contact
|
Example Response
{
"tags": [
{
"tagId": "n",
"name": "best",
"href": "https://api.getresponse.com/v3/tags/n",
"color": ""
},
{
"tagId": "c",
"name": "tools",
"href": "https://api.getresponse.com/v3/tags/c",
"color": ""
}
]
}