Common patterns

The Outreach API's flexibility helps support a wide range of possibilities and use cases. Our API works great as a light-weight CRM, as an entry-point into our platform's advanced automation capabilities, and as a tool to collect platform statistics. Continue reading for more specific use cases, and at the end of this section you'll find a reference to each resource that our API supports, including detailed information about that resource's attributes, relationships and available links.

Manage Prospects and Accounts

Prospects --- and the accounts they are associated with --- are two of the core Outreach platform resources, and working with them is easy.

Let's say you've identified a new account that you want to target. You've found a few promising leads within that account and you'd like to add them to Outreach. Because you can't write to an account's prospects relationship, you'll want to first create the account resource. Then, with each new prospect that you add you can specify this new account within the prospect's account relationship.

Note: In general, we're more likely to permit you to write to a "to-one" relationship (such as the prospect's `account`) than we are to a "to-many" (such as the account's `prospects`). This choice is made for both technical and conceptual reasons, and it's something to lookout for. Consult the API Reference for details on specific resources.

To add a new account:

Request

Copy
Copied
POST https://api.outreach.io/api/v2/accounts
Copy
Copied
{
  data: {
    type: "account",
    attributes: {
      name: "Acme",
    },
  },
}

Note: The requests in this section omit the necessary headers for brevity, namely Authorization and Content-Type; they are necessary when performing actual requests. Additionally the JSON data for the request body is simply described below the request line; actual request must include this data as the request body.

If the request was successful, the newly created account resource will be returned:

Response

Copy
Copied
{
  data: {
    type: "account",
    id: 1,
    attributes: {
      createdAt: "2017-01-01T00:00:00",
      name: "Acme",
      updatedAt: "2017-01-01T00:00:00",
      //...
    },
    relationships: {
      prospects: {
        links: {
          related: "https://api.outreach.io/api/v2/prospects?filter[account][id]=1",
        },
      },
      //...
    },
  },
}

Note that null attributes and relationships have been removed for brevity. By default resource objects include all attributes and relationships regardless of their value.

You can see from this response that Outreach has added a bit more information than you provided. First, the fields createdAt and updatedAt have been added with timestamps equal to when the request was made. Outreach maintains these timestamps internally for almost all resources; while they are visible, you cannot write to them. Second, a relationships section has been added. The account resource exposes a single relationship, prospects. Because accounts often contain many prospects, we only expose a related link and not a data list of resource identifiers. If you visit this URL you would receive an empty response, because we have not yet added any prospects to this account. Let's do that now!

To add a new prospect to an account:

Request

Copy
Copied
POST https://api.outreach.io/api/v2/prospects
Copy
Copied
{
  data: {
    type: "prospect",
    attributes: {
      emails: ["sally.smith@acme.example.com"],
      firstName: "Sally",
      title: "CEO",
    },
    relationships: {
      account: {
        data: {
          type: "account",
          id: 1,
        },
      },
    },
  },
}

Response

Copy
Copied
{
  data: {
    type: "prospect",
    id: 1,
    attributes: {
      createdAt: "2017-01-01T00:00:00",
      emails: ["sally.smith@acme.example.com"],
      firstName: "Sally",
      lastName: "Smith",
      title: "CEO",
      updatedAt: "2017-01-01T00:00:00",
      //...
    },
    relationships: {
      account: {
        data: {
          type: "account",
          id: 1,
        },
      },
      //...
    },
  },
}

To update an existing prospect:

Request

Copy
Copied
PATCH https://api.outreach.io/api/v2/prospects/1
Copy
Copied
{
  data: {
    type: "prospect",
    id: 1,
    attributes: {
      lastName: "Smith",
    },
    relationships: {
      owner: {
        data: {
          type: "user",
          id: 1,
        },
      },
    },
  },
}

Response

Copy
Copied
{
  data: {
    type: "prospect",
    id: 1,
    attributes: {
      createdAt: "2017-01-01T00:00:00",
      emails: ["sally.smith@acme.example.com"],
      firstName: "Sally",
      lastName: "Smith",
      title: "CEO",
      updatedAt: "2017-01-01T01:00:00",
      //...
    },
    relationships: {
      account: {
        data: {
          type: "account",
          id: 1,
        },
      },
      owner: {
        data: {
          type: "user",
          id: 1,
        },
      },
      //...
    },
  },
}

The request only included one changed attribute and one new relationship, but the response included all of the prospect's attributes and relationships. Remember that the Outreach API will only change the fields you provide.

For more information, see the Account and Prospect API Reference pages.

Setup and Manage Sequences

Sequences are at the heart of Outreach's system of engagement. The Outreach API provides the ability to create and manage sequences and their related rulesets and sequence steps.

To create a new sequence, provide a short name and description, and specify a sequence type of "interval" or "date":
Copy
Copied
POST https://api.outreach.io/api/v2/sequences
Copy
Copied
{
  data: {
    type: "sequence",
    attributes: {
      description: "Primary Sales Sequence",
      name: "Primary",
      sequenceType: "interval",
    },
  },
}
We picked "interval" to indicate that this sequence's steps are separated by an interval of days. Alternatively, we could have picked "date" to indicate that each step should advance at a specific date and time in the future.

Once you have the ID from the response of the create request, you can add the first sequence step. For this step we'll need to provide its step type and a time interval (in minutes), along with the sequence details:

Copy
Copied
POST https://api.outreach.io/api/v2/sequenceSteps
Copy
Copied
{
  data: {
    type: "sequenceStep",
    attributes: {
      interval: 120,
      stepType: "call",
    },
    relationships: {
      sequence: {
        data: {
          type: "sequence",
          id: 1,
        },
      },
    },
  },
}
Accepted values for the step type attribute include "auto_email", "call", "manual_email" and "task". And if this step's sequence has a sequence type set to "date", then we must instead provide a "date" attribute rather than an "interval" attribute.

You can also associate custom rulesets with sequences. First, create a new ruleset with a name and some settings:

Copy
Copied
POST https://api.outreach.io/api/v2/rulesets
Copy
Copied
{
  data: {
    type: "ruleset",
    id: 1,
    attributes: {
      autoResumeOotoProspects: true,
      name: "Custom Ruleset",
      permitDuplicateProspects: "onlyIfActive",
    },
  },
}

Then associate the ruleset with the existing sequence:

Copy
Copied
PATCH https://api.outreach.io/api/v2/sequences/1
Copy
Copied
{
  data: {
    type: "sequence",
    id: 1,
    relationships: {
      ruleset: {
        data: {
          type: "ruleset",
          id: 1,
        },
      },
    },
  },
}

For more information, see the Sequence, Ruleset and Sequence Step API Reference pages.

Save Snippets and Templates

Snippets and templates are valuable resources that save your team time and energy. Snippets provide easy access to your most commonly used HTML passages. Templates are larger resources that encapsulate a mailing's subject and body and can be associated with automated mailing sequence steps and one-off tasks. Templates can also contain a default list of recipients relevant to that topic.

To create a snippet, just provide the resource a name and the body's HTML representation:

Request

Copy
Copied
POST https://api.outreach.io/api/v2/snippets
Copy
Copied
{
  data: {
    type: "snippet",
    attributes: {
      bodyHtml: "<p>Would you please include in your response ...</p>",
      name: "Request for Information",
    },
  },
}

Response

Copy
Copied
{
  data: {
    type: "snippet",
    id: 1,
    attributes: {
      bodyHtml: "<p>Would you please include in your response ...</p>",
      name: "Request for Information",
    },
    relationships: {
      owner: {
        data: {
          type: "user",
          id: 1,
        },
      },
    },
  },
}

Templates are created in a similar fashion, but also contain relationship links to their related mailings, sequence templates and tasks. An example template may look like:

Copy
Copied
{
  data: {
    type: "template",
    id: 1,
    attributes: {
      bodyHtml: "<p>I'd like to introduce you to our new product...",
      ccRecipients: ["product@company.example.com"],
      name: "Product Announcement",
    },
    relationships: {
      mailings: {
        links: {
          related: "https://api.outreach.io/api/v2/mailings?filter[template][id]=1",
        },
      },
      owner: {
        data: {
          type: "user",
          id: 1,
        },
      },
      sequenceTemplates: {
        links: {
          related: "https://api.outreach.io/api/v2/sequenceTemplates?filter[template][id]=1",
        },
      },
      tasks: {
        links: {
          related: "https://api.outreach.io/api/v2/tasks?filter[template][id]=1",
        },
      },
    },
  },
}
Templates can be associated with mailings, sequence templates and tasks when creating or updating those resources. For example, we could associate this template with a brand new sequence template set to "auto_email" mode that will send two days after the previous step:
Copy
Copied
POST https://api.outreach.io/api/v2/sequenceSteps
Copy
Copied
{
  data: {
    type: "sequenceStep",
    attributes: {
      interval: 2880,
      stepType: "auto_email",
    },
    relationships: {
      sequence: {
        data: {
          type: "sequence",
          id: 1,
        },
      },
    },
  },
}

Assuming this returns an id of 1 for our sequenceStep

Copy
Copied
POST https://api.outreach.io/api/v2/sequenceTemplates
Copy
Copied
{
  data: {
    type: "sequenceTemplate",
    relationships: {
      sequenceStep: {
        data: {
          type: "sequenceStep",
          id: 1,
        },
      },
      template: {
        data: {
          type: "template",
          id: 1,
        },
      },
    },
  },
}

You can also create unnamed templates that will be unavailable in a list of templates in the UI or from the API index action, but can still be associated with a sequence template in order to help prevent accidental editing of a template used for sequences.

Copy
Copied
POST https://api.outreach.io/api/v2/templates
Copy
Copied
{
  data: {
    type: "template",
    attributes: {
      bodyHtml: "<h1>Greetings!</h1>",
      subject: "Hello prospect",
    },
  },
}

In order to remove the association of a sequence template to a sequence step, you must destroy the sequence template object.

For more information, see the Snippet and Template API Reference pages.

Add Prospects to Sequences

Prospects can be added and removed from sequences at any time. The Outreach API encapsulates the concept of a prospect within a sequence as a sequence state resource. To start engaging a prospect, create a sequence state resource referencing the relevant prospect, sequence and user's mailbox:

Request

Copy
Copied
POST https://api.outreach.io/api/v2/sequenceStates
Copy
Copied
{
  data: {
    type: "sequenceState",
    relationships: {
      prospect: {
        data: {
          type: "prospect",
          id: 1,
        },
      },
      sequence: {
        data: {
          type: "sequence",
          id: 1,
        },
      },
      mailbox: {
        data: {
          type: "mailbox",
          id: 1,
        },
      },
    },
  },
}

Response

Copy
Copied
{
  data: {
    type: "sequenceState",
    id: 1,
    attributes: {
      createdAt: "2017-01-01T00:00:00",
      state: "active",
      stateChangedAt: "2017-01-01T00:00:00",
      updatedAt: "2017-01-01T00:00:00",
      //...
    },
    relationships: {
      prospect: {
        data: {
          type: "prospect",
          id: 1,
        },
      },
      sequence: {
        data: {
          type: "sequence",
          id: 1,
        },
      },
      sequenceStep: {
        data: {
          type: "sequenceStep",
          id: 1,
        },
      },
      mailbox: {
        data: {
          type: "mailbox",
          id: 1,
        },
      },
    },
  },
}
Once created, the associated sequence's automation will begin. You can see that the first sequence step has already been associated with this sequence state. In addition, its state attribute has been set to "active"; additional values include "pending", "finished", "paused", "disabled", "failed", "bounced" and "opted_out". Retrieve sequence states at later times to discover changes to its state and step.

To finish a prospect in a sequence, make a request to the sequence state's finish action:

Copy
Copied
POST https://api.outreach.io/api/v2/sequenceStates/1/actions/finish
You can also pause active sequence states as well as resume those that have been paused.

For more information, see the Sequence State API Reference pages.

Schedule Mailings and Tasks

In addition to sequence-based automation, Outreach provides the ability to schedule one-off mailings and tasks.

More information coming soon.

Discover Open Tasks

Outreach can automatically assign users tasks when certain events occur to help streamline their workflow. The Outreach API can help identify new tasks and provide the opportunity to take the necessary action. To return just the tasks that a user can currently take action on, you can filter the task list by those with an "incomplete" state belonging to a given user. And to make the action step easier, you can include the task's related prospect:
Copy
Copied
GET https://api.outreach.io/api/v2/tasks?filter[state]=incomplete&filter[owner][id]=1&include=prospect
Task resources contain an action attribute that describes what type of action the user needs to take, which can be one of "action_item", "call", "email" or "in_person". Along with the task note and its related prospect, you're ready to take action!

For more information, see the Task API Reference page.

Log External Calls

Logging calls in Outreach is easy. In addition to the calling user and prospect, you'll just need to specify a call direction and outcome. The direction must be either "inbound" or "outbound" and the outcome must be either "completed" or "no_answer". You'll likely also want to provide the time when the call was answered and completed.
Copy
Copied
POST https://api.outreach.io/api/v2/calls
Copy
Copied
{
  data: {
    type: "call",
    attributes: {
      answeredAt: "2017-01-01T12:00:15",
      completedAt: "2017-01-01T12:00:00",
      direction: "outbound",
      outcome: "completed",
    },
    relationships: {
      prospect: {
        data: {
          type: "prospect",
          id: 1,
        },
      },
      user: {
        data: {
          type: "user",
          id: 1,
        },
      },
    },
  },
}

If there's an existing open call task, then you may specify that task relationship when logging the call. The created call will be associated with the task, but the task itself will not be affected.

Copy
Copied
POST https://api.outreach.io/api/v2/calls
Copy
Copied
{
  data: {
    type: "call",
    attributes: {
      direction: "outbound",
      outcome: "no_answer",
    },
    relationships: {
      prospect: {
        data: {
          type: "prospect",
          id: 1,
        },
      },
      task: {
        data: {
          type: "task",
          id: 1,
        },
      },
      user: {
        data: {
          type: "user",
          id: 1,
        },
      },
    },
  },
}

To additionally indicate that the related task has been completed, pass meta information to the task relationship itself.

Copy
Copied
POST https://api.outreach.io/api/v2/calls
Copy
Copied
{
  data: {
    type: "call",
    attributes: {
      direction: "outbound",
      note: "Meeting Booked!",
      outcome: "completed",
    },
    relationships: {
      prospect: {
        data: {
          type: "prospect",
          id: 1,
        },
      },
      task: {
        data: {
          type: "task",
          id: 1,
        },
        meta: {
          complete: true,
        },
      },
      user: {
        data: {
          type: "user",
          id: 1,
        },
      },
    },
  },
}

For more information, see the Call API Reference page, along with the related Call Disposition and Call Purpose reference pages.

Download Event Activity

Outreach logs numerous events when various activities occur throughout the platform. Collecting these events helps provide insight into a user and their organization's activity.

To download the most recent events, sort in a descending order based on the updatedAt timestamp:

Request

Copy
Copied
GET https://api.outreach.io/api/v2/events?sort=-updatedAt

Response

Copy
Copied
{
  data: [
    {
      type: "event",
      id: 1,
      attributes: {
        createdAt: "2017-01-01T00:00:00",
        name: "prospect_updated",
        updatedAt: "2017-01-01T00:00:00",
        //...
      },
    },
    //...
  ],
}

More information on event payloads and relationships coming soon.

Collect Platform Statistics

Until the Outreach API supports better analytics resources, you can still collect statistics directly from the core resources. A number of mailing-related resources provide delivery information, including mailings, prospects, sequences, sequence states, sequence steps and templates.

For example, to retrieve mailing delivery statistics for prospects, specify sparse fieldsets to get just the attributes that you are looking for:

Request

Copy
Copied
GET https://api.outreach.io/api/v2/prospects?fields[prospect]=clickCount,openCount,replyCount

Response

Copy
Copied
{
  data: [
    {
      type: "prospect",
      id: 1,
      attributes: {
        clickCount: 2,
        openCount: 9,
        replyCount: 1,
      },
    },
    //...
  ],
}

Note that these counts reference the total number of events across all of the prospect's mailings since the last touch point. These counts are not the unique number of associated mailings that have received those events.

Continue reading the API Reference for detailed descriptions of all available attributes.

Respond to Platform Events

The Outreach API normally requires your action to retrieve, create or update resources. But with Webhooks, the Outreach API will automatically notify you whenever events that you are interested in occur. You can create webhooks just like any other resource. You must provide an HTTPS URL, and you can optionally specify the resources and actions that this webhook will respond to. By default, those values will be an asterisk *, which indicates that all applicable resources and actions will be delivered. Possible values include:
ResourceActions
** created updated destroyed
account* created updated destroyed
call* created updated destroyed
mailing* created updated destroyed bounced delivered opened replied
opportunity* created updated destroyed
prospect* created updated destroyed
sequence* created updated destroyed
sequenceState* created updated destroyed advanced finished
task* created updated destroyed completed

When an active webhook sees a change to an applicable resource-action combination, the Outreach API will POST a JSON-API-styled request to the webhook's URL. Please note that create and update actions will contain only created/changed attributes, while deleted actions will contain the last known set of attributes and relationships before the resource was deleted.

For example, to create a webhook that will trigger after each "task completed" event:

Request

Copy
Copied
POST https://api.outreach.io/api/v2/webhooks
Copy
Copied
{
  data: {
    type: "webhook",
    attributes: {
      action: "completed",
      resource: "task",
      url: "https://foo.bar/webhooks",
    },
  },
}

Response

Copy
Copied
{
  data: {
    type: "webhook",
    id: 1,
    attributes: {
      action: "completed",
      active: true,
      resource: "task",
      secret: null,
      url: "https://foo.bar/webhooks",
    },
  },
}

When a task-completed event occurs, a JSON-API-styled request will be sent to the webhook's URL that includes the changed attributes and meta information about the webhook event.

Webhook Request

Copy
Copied
POST https://foo.bar/webhooks
Copy
Copied
{
  data: {
    type: "task",
    id: 1,
    attributes: {
      completed: true,
      completedAt: "2017-01-01T00:00:00",
      state: "completed",
    },
    meta: {
      deliveredAt: "2017-01-01T00:00:01",
      eventName: "task.completed",
    },
  },
}
For added protection, you can provide the webhook with a secret attribute. If that value is present, we'll include an Outreach-Webhook-Signature header that is the HMAC hexdigest of the secret and the payload body, which you can use to verify the integrity of the request.

For example, to verify the integrity of an incoming webhook in Ruby:

Copy
Copied
SECRET = "foo" # Same as is saved in the Outreach webhook

def verified?(headers, body)
  headers["Outreach-Webhook-Signature"] == signature(body)
end

def signature(body)
  OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), SECRET, body)
end

Responding to webhooks

It is recommended that a service behind webhook URL responds with 200 OK upon processing POSTed event.Outreach does not retry webhook deliveries upon receiving any of the Status Codes including 500 Internal Server Error and 429 Too Many Requests. Some proxies may automatically reply with 429 Too Many Requests upon exceeding certain limits or purchased capacity and those responses from webhook URLs are taken as acks. Please ensure appropriate monitoring is in place to notice such events and increase availability of webhook URL service.

Redirects are not followed either.

The timeout while waiting for response is set to 5 seconds. Please ensure that processing of posted events takes less than that or use a message bus for asynchronous processing.

Outreach retries on network related failures such as socket errors, connection resets, etc... There are 4 attempts (3 retries) made to deliver each event to a webhook URL with a second pause between them.

Invite New Users

You can invite new users to the Outreach platform and manage their identities using the Outreach API. Create new users just like any other resource:

Webhook Request

Copy
Copied
POST https://api.outreach.io/api/v2/users
Copy
Copied
{
  data: {
    type: "user",
    attributes: {
      email: "foo@bar.com",
      firstName: "Foo",
      lastName: "Bar",
    },
  },
}

Response

Copy
Copied
{
  data: {
    type: "user",
    id: 1,
    attributes: {
      email: "foo@bar.com",
      firstName: "Foo",
      lastName: "Bar",
    },
  },
}

By default all new users will receive an email invitation with instructions on how to get started. You can prevent email invitations from being sent by including an additional meta data parameter:

Request

Copy
Copied
POST https://api.outreach.io/api/v2/users
Copy
Copied
{
  data: {
    type: "user",
    attributes: {
      email: "foo@bar.com",
      firstName: "Foo",
      lastName: "Bar",
    },
    meta: {
      sendInvite: false,
    },
  },
}

Create Compliance Requests

Outreach provides a compliance request API for processing delete requests in compliance with regulations such as CCPA and GDPR. This request will be processed asynchronously, deletion may not be processed immediately.

To submit a request to permanently delete a prospect or individual in Outreach, include the following attributes to a POST request:

AttributeDescription
requester_email* Email of the Outreach user making the request
request_type* Set this value to 'Delete'
object_type* Set this value to 'Prospect'
request_object_email* Email of the Prospect to delete

Request

Copy
Copied
POST https://api.outreach.io/api/v2/complianceRequests
Copy
Copied
{
  data: {
    type: "complianceRequest",
    attributes: {
      requester_email: "admin@example.com",
      request_type: "Delete",
      object_type: "Prospect",
      request_object_email: "prospect_email@example.com",
    },
  },
}

Response

Copy
Copied
{
  data: {
    batch_compliance_request_id: "f98711fe-8a03-48b9-91d3-0f7994e999cc",
  },
}

Submitting a compliance request will trigger a batch of tasks to be processed. To view the status of the submitted request, use the batch compliance request filter on the following GET request.

Request

Copy
Copied
GET https://api.outreach.io/api/v2/complianceRequests?filter[batchComplianceRequest]=f98711fe-8a03-48b9-91d3-0f7994e999cc

A compliance request may have any of the following states to indicate its current processing status:

StateDescription
pending* The request has been received but has not started processing
running* The request is currently being processed
done* The request has successfully been processed and is complete

A compliance request consists of multiple tasks targeting different elements of the request. Each task may also have its own state, shown below:

StateDescription
pending* The task has been created but has not started processing
queued* The task has been queued for processing
running* The task is currently being processed
done* The task has successfully been processed and is complete
temporary_failure* There was an issue with the task, it is in a temporary failed state and will be retried
The only permanent state for a task or request is the done state, any failures will be retried until successful.

For more information on compliance requests, contact Outreach support at support@outreach.io.