GR API Docs

How to schedule a contact import ​

You can schedule a contact import via the POST /import method.

How the method works ​

To import contacts via API, you need a JSON file containing your contact details. This way you can create and update contacts with their custom fields.

What you'll need ​

To schedule a contact import, you'll need to pass the following information:

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.

Field Mapping ​

json
{
    "fieldMapping": ["email", "name", "ip", "age", "your_custom_field_1_name", "tag:your_tag_name" ...],
}

Field mapping specifies what properties to assign to your contacts during an import. It's the equivalent of column headers in a CSV file used to import contacts in a GetResponse account. It must include an email field. Other contact properties, like name and ip, as well as custom field names or tag names, can also be included in the mapping.

To assign a custom field to a contact you need to provide its value on the corresponding field of the contact array on the contacts list.

In the API, each custom field has a name. To retrieve the list of your custom fields, you can 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 and city.

Note: Import API uses custom field names, not IDs.

To assign a tag to a contact you need to properly define it in the fieldMapping by adding a tag: prefix to a tag name.

To retrieve the list of your tags, you can call the GET /tags. You can also add a new tag while importing - just write its new name after a tag: prefix.

Contacts ​

json
{
  "contacts": [
     ["joe@example.com", "Joe", "127.0.0.1", 55, "Joe's value for custom_field_1", "1",...],
     ["john@example.com", "John", "192.168.0.1", 20, "John`s value for custom_field_1", "0", ...]
  ]
}

The contacts container is a place where the contacts dataset should be specified. Each contact is represented by a separate array. Contact's property values should be placed on the corresponding indexes as their names in fieldMapping.

Note: Multi-value custom fields are not fully supported. You can assign only a single value during import.

To assign a tag to a contact, you need to fill the corresponding contact's property values with a string value of either '1' or '0'. A value of '1' indicates that a tag, with a name defined in the fieldMapping, will be attached to the corresponding contact, while a value of '0' means it will not be attached. Currently, there is no possibility to remove tag from a contact using this method.

Note: Import API uses tag names, not ID's.

Example request payload ​

json
{
  "campaignId": "cd2",
  "fieldMapping": ["email", "name", "ip", "age", "customer_group", "tag:your_new_or_existing_tag_name"],
  "contacts": [
     ["joe@example.com", "Joe", "127.0.0.1", 55, "A", "1"],
     ["john@example.com", "John", "192.168.0.1", 20, "B", "0"]
  ]
}

The above request creates 2 contacts, each with two custom fields. The first one will also have a tag named your_new_or_existing_tag_name attached.

Response ​

A successful API request returns the HTTP code 201 Created. The response body contains importId, statistics, and status. Statistics won't show complete results at this stage because your import has yet to start. To keep track of your import status, use GET /import (provide the importId from the response), or subscribe to an Import finished webhook.

Limits ​

  • Request can be as big as 20MB. Larger payloads will be rejected.
  • You can have one active import to one campaign (list) at a time.
  • You can have two active imports in total. The following statuses indicate active imports: uploaded, to_review, review and approved
  • You can create up to 20 imports per 24 hours.