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 nameField typeField description
queryhashUsed to search only resources that meets criteria. You can specify multiple parameters, then it uses AND logic.
KeyPossible values if fixed
email*
name*
createdOn[from]Y-m-d
createdOn[to]Y-m-d
changedOn[from]Y-m-d
changedOn[to]Y-m-d
campaignId*
originwebform, import, landing_page, api, email, panel, iphone, forward, survey, sale, copy, leads
fieldsstringList of fields that should be returned. Id is always returned. Fields should be separated by comma
sorthashEnable sorting using specified field (set as a key) and order (set as a value). You can specify multiple fields to sort by.
KeyPossible values if fixed
emailasc,desc
nameasc,desc
createdOnasc,desc
changedOnasc,desc
campaignIdasc,desc
pageintegerSpecify which page of results return.
perPageintegerSpecify how many results per page should be returned
additionalFlagsstringAdditional 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
    }
]

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 nameField typeField description
namestringName of the contact (length 2-128)
email (required)stringEmail of the contact (must be unique per campaign)
dayOfCycleintegerDay of autoresponder cycle
campaign (required)objectTarget campaign resource that this contact should be added to. You must specify campaignId inside this resource!
Field nameField typeField description
campaignId (required)stringCampaign Id
customFieldValuescollectionCollection of customFieldValues that should be assign to contact
Field nameField typeField description
customFieldId (required)stringId of customField
value (required)setList of assigned values (one or more - depending on custom field type, 1 - 255 chars)
ipAddressstringIP address of a contact (IPv4 or IPv6)
scoringintegerContact scoring, pass null to disable scoring for this contact
tagscollectionCollection of tags that should be assigned to the contact
Field nameField typeField description
tagId (required)stringId of tag

Possible Errors


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 nameField typeField description
namestringName of the contact (length 2-128)
campaignobjectMove contact to this campaign. Contacts activities and statistics from previous campaign will remain
Field nameField typeField description
campaignId (required)stringCampaign Id
notestringAdditional note about an contact
dayOfCycleintegerDay of autoresponder cycle, 0-9999
scoringintegerContact scoring, pass null to disable scoring for this contact
tagscollectionCollection of tags that should be assign to contact
Field nameField typeField description
tagId (required)stringId of tag
customFieldValues (required)collectionCollection of customFieldValues that should be assign to contact
Field nameField typeField description
customFieldId (required)stringId of customField
value (required)setList of assigned values (one or more - depending on customField type, 1 - 255 chars)

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


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 nameField typeField description
messageIdstringID of message
ipAddressstringUser unsubscribe IP address

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 nameField typeField description
fieldsstringList 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
}

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 nameField typeField description
queryhashUsed to search only resources that meets criteria. You can specify multiple parameters, then it uses AND logic.
KeyPossible values if fixed
createdOn[from]YYYY-mm-dd
createdOn[to]YYYY-mm-dd
fieldsstringList of fields that should be returned. Fields should be separated by comma
pageintegerSpecify which page of results return.
perPageintegerSpecify 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
        }
    }
]

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 nameField typeField description
customFieldValues (required)collectionCollection of customFieldValues that should be upserted to contact
Field nameField typeField description
customFieldId (required)stringId of customField
value (required)setList of assigned values (one or more - depending of customField type, length 1-128)

Example Response

{
    "customFieldValues": [
        {
            "customFieldId": "n",
            "value": [
                "white"
            ]
        }
    ]
}

Possible Errors


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 nameField typeField description
tags (required)collectionCollection of tags that should be assigned to contact
Field nameField typeField description
tagId (required)stringId of tag

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

Possible Errors