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

{
    "fieldMapping": ["email", "name", "ip", "age", "your_custom_field_1_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, 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:

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

Contacts

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

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.

Example request payload

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

The above request creates 2 contacts, each with two custom fields.

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.