You can programmatically trigger email invitations using our API. This option is frequently used as an integration point with Salesforce or other CRMs. A common use case is to trigger a follow up email after closing a customer support request.

To enable the API endpoint for your survey, navigate to Setup and click the Data Sources link:

Toggle the API option.

You’ll find the API endpoint and access token listed on the Summary page:

The API expects a POST request, with the provided Authorization token.

There are two valid formats for the body of the API request: a single recipient, or multiple recipients.

Single recipient request

For a single recipient, here is an example request body: 

POST /api/v1/surveys/PARAM/replies
Headers:
Content-Type: application/json
Authorization:Token token=TOKEN
{
  "person": {
    "email": "first @last.com",
    "first_name": "First",
    "last_name": "Last",
    "fields": {
      "Account Manager": ["Jane Doe"],
      "Products": ["Acme M500", "Acme B7500"]
    }
  },
  "account": {
    "name": "Account Name"
  },
  "facets": {
    "Job ID": "1234"
  },
  "delay": 24
}

Successful response:

{
  "Reply": {
    "id": 1,
    "facets": {
      "Job ID": "1234"
    }
  },
  "person": {
    "id": 2,
    "first_name": "First",
    "last_name": "Last",
    "email": "first@last.com",
    "fields": {
      "Account Manager": ["Jane Doe"],
      "Products": ["Acme M500", "Acme B7500"]
    }
  },
  "account": {
    "id": 3,
    "name": "Account Name"
  },
  "run_at": "2000-01-01T00:00:00.000Z"
}

 

  • A successful response will include all the current data for the matching Person and Account. 
  • If a delay was set, the run_at attribute will report when delivery is estimated.

This API endpoint can also accept up to 100 records at once. Each element has the same options as the singleton example above. You must only wrap each in an array:


POST /api/v1/surveys/PARAM/replies
Headers:
Content-Type: application/json
Authorization:Token token=TOKEN
{
  "replies": [
    {
      "person": {
        "email": "first@person.com"
      }
    },
    {
      "person": {
        "email": "second@person.com"
      }
    }
  ]
}

Successful response:

{
  "replies": [
    {
      "status": "ok",
      "reply": {
        "id": 1,
      }
      "person": {
        "id": 2,
        "email": "first@person.com"
      }
    },
    {
      "status": "ok",
      "reply": {
        "id": 3,
      }
      "person": {
        "id": 4,
        "email": "second@person.com"
      }
    }
  ]
}

You can also add facets  to the POST request body as follow:

{
  "replies": [
    {
      "person": {
        "email": "sulema_mraz@example.net",
        "first_name": "Sulema",
        "last_name": "Mraz",
        "fields": {
          "company_name": "Lindgren, Kihn and Dickinson",
          "industry": "Hospitality",
          "departments": "Baby"
        }
      },
      "facets": {
        "product": "Fantastic Wool Computer",
        "price": 91.74,
        "promotion_code": "StellarDiscount323014"
      },
      "delay": 0
    }
  ]
}

Multiple recipients requests

Below is an example of a request body for a multiple-person request:

{
  "replies": [
    {
      "person": {
        "first_name": "Melvina",
        "last_name": "Ward",
        "email": "melvina_ward@example.org",
        "fields": {
          "company_name": "Schneider, Nolan and Rosenbaum",
          "industry": "Investment Banking",
          "departments": "Kids & Automotive"
        }
      },
      "facets": {
        "product": "Sleek Paper Lamp",
        "price": 60.79,
        "promotion_code": "KillerPromotion909616"
      },
      "delay": 0
    },
    {
      "person": {
        "first_name": "Augustus",
        "last_name": "Windler",
        "email": "augustus_windler@example.com",
        "fields": {
          "company_name": "Conn Group",
          "industry": "Food Production",
          "departments": "Beauty, Electronics & Kids"
        }
      },
      "facets": {
        "product": "Mediocre Iron Pants",
        "price": 91.53,
        "promotion_code": "GoodSavings710289"
      },
      "delay": 0
    },
    {
      "person": {
        "first_name": "Refugio",
        "last_name": "Senger",
        "email": "refugio_senger@example.org",
        "fields": {
          "company_name": "Orn, Bradtke and Mertz",
          "industry": "Online Media",
          "departments": "Music & Garden"
        }
      },
      "facets": {
        "product": "Incredible Aluminum Chair",
        "price": 22.21,
        "promotion_code": "StellarSale637270"
      },
      "delay": 0
    }
  ]
}


Error cases:

  • Unprocessable requests will return with a 422 header code.
  • Too many replies - if you send a request with too many person records. Default limit is 100
  • Email Suppressed - You have disabled this customer from receiving emails
  • Recipient opted out - The customer has opted out of further communications
  • Email address bounced - The email address has been identified as a bounce
  • Touch limit exceeded - If you have enabled the touch limit on your survey, this error message indicates the recipient has already received an email in the allotted period
  • "Content header type not defined" - Add a header for it, as in Content-Type: application/json
  • Capitalization and spacing must match the above examples 
Did this answer your question?