API Quickstart Guide

Getting Started with AutoReach API

API access is only available in the AutoReach Campaign Management Enterprise License. Before you dive in, ensure you have an active account with AutoReach and your Client ID and Client Secret, which will be provided by the AutoReach team. If you haven't received these, please contact [e-mail].

Generating Your Token

You'll need to create a token for authentication before you can make API requests. Here's how you can do it using curl:

curl --request POST \
 --url https://autoreach.us.auth0.com/oauth/token \
 --header 'content-type: application/json' \
 --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"https://www.autoreach.app/","grant_type":"client_credentials"}'

Make sure to replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with the actual Client ID and Client Secret provided by the AutoReach team. This process will yield a token that you'll use to authenticate your API requests.

The Base URL

All your API requests should be directed to: https://www.autoreach.app/api/v1/

Key API Endpoints

Here are the main API endpoints you'll be working with:

Campaigns:

GET /api/v1/campaigns: Retrieves all campaigns.

• Note: that currently our methods do not support the building and manipulation of a campaign. You can just have a running list and records will just automatically flow in and flow out from that list.

Custom Fields:

GET /api/v1/custom_fields: Retrieves all custom fields.

Lists:

GET /api/v1/lists: Retrieves all lists.

Members:

• GET /api/v1/members: Retrieves all members.
• POST /api/v1/members: Adds a new member.
• PUT /api/v1/members/{id}: Modifies a specific member.
• DELETE /api/v1/members/{id}: Removes a specific member.
  • Note: A successful delete request will not return a response body. A response body is only generated if a delete is not successful.

People:

• PATCH /api/v1/people: Allows for modifying or adding multiple people records (up to 100 at a time) in the CRM. It is designed to create new records or update existing ones in a batch operation, functioning as a batch upsert endpoint.
• PUT /api/v1/people/{id}: Modifies a specific person.
  • The id parameter accepts either person.id or person.external_id.
• DELETE /api/v1/people/{id}: Removes a specific person.
  • Note: A successful delete request will not return a response body. A response body is only generated if a delete is not successful.

When creating a person, custom fields will have a key and a value that you're trying to pass in. They do not go into the additionalProp1 object.

Here's an example of how to use the patch method for the batch upsert endpoint:

curl --request PATCH \
--url https://www.autoreach.app/api/v1/people \
--header 'Authorization: Bearer TOKEN WAS HERE' \
--header 'Content-Type: application/json' \
--data '{
"people": [
{
"id": "abc123",
"email": "[e-mail]",
"first_name": "First",
"last_name": "Last",
"phone": "555-325-2017",
"previous_contact_date": "2024-01-01 20:18:57 +0000"
}
]
}'

Note: We recommend sending date values in the following date-time format: YYYY-MM-DD HH:MM:SS +TZ. For example, 2024-01-01 20:18:57 +0000.

Note: that while our API allows you to sync records from your data source into AutoReach, it does not currently support building rules or building lists/campaigns.

How to Make a Request

When making a request, remember to include your token in the header. Here's a curl example:

curl -H "Authorization: Bearer YOUR_TOKEN" https://www.autoreach.app/api/v1/campaigns

Don't forget to replace YOUR_TOKEN with your actual token.

Understanding API Responses

AutoReach API responses are delivered in JSON format. Each response includes a 'data' field that contains the requested data and a 'meta' field that contains metadata about the response.

Here's an example of a typical API response:

{
  "data": [
    {
      "id": 1,
      "name": "Campaign 1",
      "description": "This is campaign 1"
    },
    {
      "id": 2,
      "name": "Campaign 2",
      "description": "This is campaign 2"
    }
  ],
  "meta": {
    "total": 2
  }
}

In this example, the 'data' field contains an array of campaign objects, and the 'meta' field contains an object with a 'total' field indicating the total number of campaigns returned.

Dealing with Errors

If your request encounters an error, the AutoReach API will return an error object. The 'errors' field contains an array of error objects, each with a 'status', 'title', and 'detail' field.

Here's an example of an error response:

{
  "errors": [
    {
      "status": 400,
      "title": "Bad Request",
      "detail": "The request could not be understood or was missing required parameters."
    }
  ]
}

In this example, the 'errors' field contains an array with a single error object. The 'status' field indicates the HTTP status code, the 'title' field provides a brief description of the error, and the 'detail' field provides a more detailed explanation of the error.

Additional Resources

For more in-depth information, including object schemas and specific parameters for each endpoint, please refer to the comprehensive AutoReach API documentation.

If you need further help or have any queries, don't hesitate to contact our support team at [e-mail].