GR API Docs

Adding multiple contacts ​

You can add contacts via the POST /contacts/batch 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 ellipsis) 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).

Tags ​

Tags allow you to label contacts based on information you have about them. For example, they can help you organize contacts into "VIP customer" and "first-time buyer". In the API, each tag has a unique identifier. To retrieve the list of your tags, you need to call the GET /tags method. A response might look like this:

json
[
    {
        "tagId": "bRGx8",
        "name": "first-time buyer",
        "href": "https://apireference.getresponse.com/v3/tags/bRGx8",
        "color": "",
        "createdAt": "2023-08-02T09:32:31+0000"
    },
    {
        "tagId": "PxMnD",
        "name": "VIP customer",
        "href": "https://apireference.getresponse.com/v3/tags/PxMnD",
        "color": "",
        "createdAt": "2021-12-16T12:40:46+0000"
    }
]

Adding a contact ​

Use the POST /contacts/batch 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
{
    "campaignId": "p86zQ",
    "contacts": [
        {
            "name": "John Example",
            "email": "example@example.com"
        },
        {
            "name": "John MoreExample",
            "email": "moreexample@example.com"
        }
    ]
}

A request with the above payload will create a new contacts in the campaign p86zQ. The contacts will not be added to an autoresponder cycle, will not have any custom fields set, will not be geolocated..

Complete JSON payload ​

The following is an example using all fields:

json
{
    "campaignId": "p86zQ",
    "email": "example@example.com",
    "contacts": [
        {
            "name": "John Example",
            "email": "example@example.com",
            "customFieldValues": [
                {
                    "customFieldId": "y8jnp",
                    "value": ["18-29"]
                },
                {
                    "customFieldId": "z9Kgt",
                    "value": ["Podunk"]
                }
            ],
            "tags": {
                "ids": ["bRGx8", "PxMnD"]
            },
            "dayOfCycle": 0,
            "scoring": 1,
            "ipAddress": "192.168.0.1"
        },
        {
            "name": "John MoreExample",
            "email": "moreexample@example.com"
        }
    ]
}

The first new contact will:

  • Have name set to John Example
  • Have email set to example@example.com
  • Be added to the autoresponder cycle on day 0
  • Contact score set to 1
  • 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.
  • Have two tags:
    • first-time buyer
    • VIP customer

The second new contact will:

  • Have name set to John MoreExample
  • Have email set to moreexample@example.com

All new contacts must have an email address. All other fields are optional. Additionally, different contacts can have fields assigned to them. For example, you can add 100 contacts with tags and 100 with custom fields.

Response and processing ​

If the request is successful, the API returns the HTTP code 202 Accepted. This means that the contacts has been preliminarily validated and added to the queue. It may take a few minutes to process the queue and add the contacts to the list. If your contacts 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 use 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.

Batch API Throttling ​

Batch API is subject to special limits and throttling. You can make 80 calls per time frame (10 minutes) and only 1 call per second. The allowed batch size is 1000 contacts.

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 or tag 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.