Adding contacts via the POST /contacts method is one of the most commonly used features of the GetResponse API.

Prerequisites:

  • An activated GetResponse account
  • The API Key for the account
  • A tool that allows you to make HTTP requests, such as Postman or Hurl.it

In this case study, we will:

  • Find a campaign ID accepted by the POST /contacts method.
  • Prepare a custom field list.
  • Call the POST /contacts method using the prepared data.
  • Go over some common errors that might be returned by the API.

The basics

API endpoint

There are 3 different URLs for the GetResponse APIv3:

Note: Enterprise customers should contact their account managers to find out which of the two GetResponse Enterprise endpoints they should use.

Headers

Request

Authentication

All APIv3 requests require an authentication header, which depends on the selected authentication method:

  • X-Auth-Token for API Key-based authentication
  • Authorization
    • Basic to get or refresh token in selected OAuth requests
    • Bearer for OAuth token authenticated requests

Authentication errors are returned with HTTP status code 401 and authorization errors with HTTP status code 403.

Content-Type

POST requests require the Content-Type header to be set to application/json.

X-Domain

The X-Domain header is required only for GetResponse Enterprise customers. It should not be used by Email, Max, and Pro customers.

If required, the X-Domain header must be set to the domain associated with the given GetResponse Enterprise account, e.g. X-Domain: example.com. It must not contain the www. prefix or the URI scheme (such as http://).

Response

Throttling

Since all API calls are throttled, every response includes a few additional headers:

  • X-RateLimit-Limit - the total number of requests available per time frame
  • X-RateLimit-Remaining - the number of requests left in the current time frame
  • X-RateLimit-Reset - seconds left in the current time frame

HTTP status code 429 indicates that you have reached the throttling limit. You need to wait for the duration specified in X-RateLimit-Reset header before making another request.

Pagination

Paginated resources are returned with custom headers:

  • CurrentPage
  • TotalPages
  • TotalCount - the total number of resources found for the specified conditions

Identifiers - IDs

All resource identifiers used in the API are string values, not numbers.

Campaign ID

There are two ways to find API-compatible campaign IDs: through the web panel and through the API.

To find the campaign ID through the web panel
  1. Log in to your account.
  2. Expand the campaign dropdown list in the top corner of the page and select Campaign List or go to https://app.getresponse.com/campaign_list.html
  3. Find the target campaign for your contacts.
  4. Below the campaign name, find the TOKEN value (a string of alphanumeric characters).
To 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, custom fields are ordinary resources, which means that each of them has a unique identifier. To retrieve the list of custom fields, we need to call the GET /custom-fields method. A response might look like this:

[
  {
    "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:

{
  "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:

{
  "name": "John Doe",
  "email": "example@example.com",
  "dayOfCycle": "0",
  "campaign": {
    "campaignId": "p86zQ"
  },
  "customFieldValues": [
    {
      "customFieldId": "y8jnp",
      "value": ["18-29"]
    },
    {
      "customFieldId": "z9Kgt",
      "value": ["Podunk"]
    }
  ],
  "ipAddress": "192.0.2.111"
}

The new contact will:

  • Have name set to John Doe
  • Have email set to example@example.com
  • Be added to the autoresponder cycle at 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.0.2.111, which will be used to geolocate the contact

Response and processing

If the request is successful, the API returns HTTP code 202 Accepted. This means that the contact has been validated and added to the queue. It may take a few minutes to process the queue and add the contact to the list.

Double opt-in

By default, all campaigns are set to double opt-in. This means that the 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 sample error:

{
  "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.

Internal server error - HTTP 500 - Code 1

Use the link provided in the Support section of this document to contact our Support team. Please include your API Key as well as the request and response data.

General validation error - HTTP 400 - Code 1000

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

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 - 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

An email address can be used only once within a given campaign. You can add the same contact to different campaigns, however.

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 specifying the contact's day of cycle is dayOfCycle. The API uses a lenient approach against unknown fields in requests, so using cycle_day will not cause an error. Instead, the field will be ignored and the contact will not be added to the autoresponder cycle.

Support

API Support is provided through the DevZone support channel. Please do not hesitate to contact us with any problems with or questions about the integration.