GR API Docs

Adding contacts ​

You can add contacts via the POST /contacts method.

Campaign ID ​

In GetResponse, you add contacts to a specific campaign (list). To do this, first obtain the campaign (list) ID.

There are two ways to find the API-compatible campaign (list) ID:

  • By looking it up in the List settings in your account
  • Through the API.

Find the campaign (list) ID in List settings

  1. Log into your account.
  2. Click Contacts or use this shortcut to display your contact lists.
  3. Scroll to find the list.
  4. Click the Actions icon (vertical elipsis) and select Settings.
  5. In the General tab, you can find the LIST TOKEN value under the List name field.

Find the campaign ID through the API

  1. Call the GET /campaigns method.
  2. Find the target campaign within the JSON response.

API-compatible campaign IDs are returned in the campaignId fields.

Custom fields ​

Custom fields allow you to add and store any additional information about your contacts.

In the API, each custom field has a unique identifier. To retrieve the list of your custom fields, you need to call the GET /custom-fields method. A response might look like this:

json
[
    {
        "customFieldId": "y8jnp",
        "href": "https://api.getresponse.com/v3/custom-fields/y8jnp",
        "name": "age",
        "fieldType": "single_select",
        "valueType": "string",
        "type": "single_select",
        "hidden": "false",
        "values": [
            "18-29",
            "30-44",
            "45-59",
            "60+",
            "<18"
        ]
    },
    {
        "customFieldId": "z9Kgt",
        "href": "https://api.getresponse.com/v3/custom-fields/z9Kgt",
        "name": "city",
        "fieldType": "text",
        "valueType": "string",
        "type": "text",
        "hidden": "false",
        "values": []
    }
]

This response includes 2 custom fields: age (field ID y8jnp) and city (field ID z9Kgt).

Adding a contact ​

Use the POST /contacts method to add contacts.

Remember that all methods accept and return JSON data only.

Basic JSON payload ​

For the following example, let’s use the campaign ID p86zQ:

json
{
  "email": "example@example.com",
  "campaign": {
    "campaignId": "p86zQ"
  }
}

A request with the above payload will create a new contact in the campaign p86zQ and set the contact’s email to example@example.com. The contact will not be added to an autoresponder cycle, will not have any custom fields set, will not be geolocated, and will receive the default name: “Friend”.

Complete JSON payload ​

The following is an example using all fields:

json
{
    "name": "John Smith",
    "email": "example@example.com",
    "dayOfCycle": "0",
    "campaign": {
        "campaignId": "p86zQ"
    },
    "tags": ["y8inp", "y8inq"],
    "customFieldValues": [
        {
            "customFieldId": "y8jnp",
            "value": ["18-29"]
        },
        {
            "customFieldId": "z9Kgt",
            "value": ["Podunk"]
        }
    ],
    "ipAddress": "192.168.0.1"
}

The new contact will:

  • Have name set to John Smith
  • Have email set to example@example.com
  • Be added to the autoresponder cycle on day 0
  • Be added to the campaign p86zQ
  • Have two custom fields:
    • age, set to 18-29
    • city, set to Podunk
  • Have the IP address 192.168.0.1, which will be used to geolocate the contact.

Response and processing ​

If the request is successful, the API returns the HTTP code 202 Accepted. This means that the contact has been preliminarily validated and added to the queue. It may take a few minutes to process the queue and add the contact to the list. If your contact didn't appear on the list, there's a possibility that it was rejected at a later stage of processing.

Double opt-in ​

If your list is set to double opt-in, a contact has to click a link in a confirmation message to be added to your list. Unconfirmed contacts are not returned by the API and can be found using Search Contacts only.

Errors ​

Error response ​

Let’s consider this example error:

json
{
  "httpStatus": 400,
  "code": 1000,
  "codeDescription": "General error of validation process, more details should be in context section",
  "message": "Custom field invalid",
  "moreInfo": "https://apidocs.getresponse.com/en/v3/errors/1000",
  "context": [
    "Empty value. ID: y8jnp"
  ],
  "uuid": "5a42dd48-7f57-4919-9b32-391e594ce375"
}

Take note of the following fields:

  • codeDescription - general error code description
  • message - error message
  • moreInfo - link to our API Docs with additional information about error details
  • context - field and/or value that caused the problem, additional error details, etc.

Common errors ​

General validation error - HTTP 400 - Code 1000

Request data is invalid. Detailed information about the error is provided in the context field.

Related resource not found - HTTP 400 - Code 1001

Make sure that the campaign ID and custom field IDs are correct.

Resource state forbids that kind of action - HTTP 400 - Code 1002

Please refer to the context section in the error response for a detailed explanation. Reasons may include:

  • Contact is blacklisted in the campaign, account, or global blacklist.
  • Email address is invalid - the domain does not exist or user cannot be found.
  • Contact has been deleted or bounced.

Parameter has wrong format - HTTP 400 - Code 1003

Make sure that all values are properly formatted. Pay special attention to value in customFieldValues - it has to be an array, even if you want to set only one value.

Required field empty - HTTP 400 - Code 1005

Only two fields are required when adding a new contact - email and campaignId (nested in campaign). Make sure to set both of them.

Another resource with the same value of unique property - HTTP 409 - Code 1008

A given email address can only be added once to a campaign. You can, however, still add the same contact to different campaigns.

Common mistakes ​

Numeric campaign ID

For the campaignId value, use the alphanumeric TOKEN provided under the campaign name in Campaign List. DO NOT use the 8-digit campaign number.

Custom field name in customFieldValues

customFieldId has to contain the custom field ID returned by GET /custom-fields. DO NOT use the custom field name.

cycle_day field

The correct field name for adding a contact to a specific day in an autoresponder cycle is dayOfCycle. The API uses a lenient approach against unknown fields in requests, so using cycle_day will not produce an error. Instead, the field will be ignored and the contact will not be added to the autoresponder cycle.