NAV

Introduction

Welcome to the Boast API!

You can use the the Boast API to automate tasks and trigger your own workflows to get data in or out of Boast and integrate with other popular services.

At this time, the Boast API is only available to paid customers via one of our approved API partners such as Zapier.

Authentication (OAuth 2)

The Boast API uses the OAuth 2 protocol for authentication, specifically the Authorization Code Grant.

Creating an Application

If you're building a custom integration with Boast and need OAuth access, please contact us to request access.

Authorize

Request

GET https://app.boast.io/oauth/authorize?client_id=mBUYVNhbzejU9mi4faMzwFE27XunvbKfpf-1jLJfylc&redirect_uri=https://oauthdebugger.com/debug&scope=read write&response_type=code

Redirect

GET https://oauthdebugger.com/debug?code=axoIQaYBbm0ZEoj-sZEs-kslTxtR1hJzv4CXsEL3Z_E

GET https://app.boast.io/oauth/authorize

Query Parameters

Name
client_id
redirect_uri
scope
response_type

Access Token

Request

> POST https://app.boast.io/oauth/token
> content-type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=axoIQaYBbm0ZEoj-sZEs-kslTxtR1hJzv4CXsEL3Z_E&
client_id=mBUYVNhbzejU9mi4faMzwFE27XunvbKfpf-1jLJfylc&
client_secret=jsockwdoddKjDYUgxrPYGodyOxu3HjI5HaG0C-guDhE&
redirect_uri=https%3A%2F%2Foauthdebugger.com%2Fdebug

Response

{
  "access_token": "MNgOvnS_wcg4h-b5WxTAuof6-K4LgfW9G45543hzmaI",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "a9kSGp7uYsgNIZQAdxN_HJ8Sto_9ASh4-uawGIWZ9Z4",
  "scope": "read write",
  "created_at": 1613653883
}

POST https://app.boast.io/oauth/token

Parameters

Name
grant_type authorization_code
code Code from authorize redirect
client_id
client_secret
redirect_uri

Refresh Token

Request

> POST https://app.boast.io/oauth/token
> content-type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=a9kSGp7uYsgNIZQAdxN_HJ8Sto_9ASh4-uawGIWZ9Z4&
client_id=mBUYVNhbzejU9mi4faMzwFE27XunvbKfpf-1jLJfylc&
client_secret=jsockwdoddKjDYUgxrPYGodyOxu3HjI5HaG0C-guDhE

Response

{
  "access_token": "YO1JwYRXyOdT4cOxCn5rWLXnXNRDbcRxfXxcszUGMzE",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "8fKtyDtzyChjuNZ3hoFvSpD1wGpZpKeUkFcLe-tR6zA",
  "scope": "read write",
  "created_at": 1613654860
}

POST https://app.boast.io/oauth/token

Parameters

Name
grant_type refresh_token
refresh_token Token from last access token
client_id
client_secret

Interacting with the API

Unless otherwise noted, all API requests and responses utilize the JSON data format. Some API endpoints may support URI parameters in the query string.

Requests

Example Request Headers

Authorization: Bearer {token}
Content-Type: application/json

Example Request Body

{
  "first_name": "Michael",
  "last_name": "Bluth"
}

Unless otherwise noted, all API requests should:

Responses

Example Response Headers

Content-Type: application/json

Example Response Body (multiple objects returned)

{
  "data": [
    {
      "first_name": "Michael",
      "last_name": "Bluth"
    },
    {
      "first_name": "Lucille",
      "last_name": "Ball"
    }
  ]
}

Example Response Body (single object returned)

{
  "data": {
    "first_name": "Michael",
    "last_name": "Bluth"
  }
}

Unless otherwise noted, all API responses use the JSON format.

Data for the response is returned under a top-level data key, which is either an array[] of data objects, or a single data object.

Errors

HTTP/1.1 400 Bad Request

{
  "errors": [
    {
      "detail": "A detailed error message",
      "code": "bad_request",
      "status": 400
    }
  ]
}

Boast utilizes standard HTTP Status Codes to indicate the status of an API request.

In general, anything in the 2xx range should be considered successful, and anything in the 4xx or 5xx range should be considered an error.

Some API endpoints will provide additional error objects inside a top-level errors key of the JSON response.

Error Objects

Key Notes
detail Human friendly description of the error
code Internal error code, expressed as a string
status Optional HTTP status code related to the error
source Optional Object containing references to the source of the error

Pagination

Example Pagination Response

{
  "data": [
    {
      "first_name": "Michael",
      "last_name": "Bluth"
    },
    {
      "first_name": "Lucille",
      "last_name": "Ball"
    },
    {
      "first_name": "Tony",
      "last_name": "Hawk"
    }
  ],
  "meta": {
    "pagination": {
      "count": 103,
      "page": 1,
      "items": 3,
      "pages": 35
    }
  }
}

Some API endpoints may return paginated results inside a pagination object underneath a top-level meta key in the response. The current page is set with the page query parameter.

Pagination Object

Key Notes
count Total count of items
page Current page number
items Number of items per page
pages Number of total pages

Accounts

Get All Accounts

Request

GET http://api.boast.io/v1/accounts

Response

{
  "data": [
    {
      "id": "7a2f1f8c-7771-47e2-8dbd-332b301028a8",
      "name": "My Boast Account",
      "created_at": "2021-01-12T14:17:28.715Z",
      "updated_at": "2021-02-16T17:58:38.804Z"
    }
  ]
}

This endpoint retrieves all your accounts.

HTTP Request

GET http://api.boast.io/v1/accounts

Get a Specific Account

Request

GET http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8

Response

{
  "data": {
    "id": "7a2f1f8c-7771-47e2-8dbd-332b301028a8",
    "name": "My Boast Account",
    "created_at": "2021-01-12T14:17:28.715Z",
    "updated_at": "2021-02-16T17:58:38.804Z"
  }
}

This endpoint retrieves all your accounts.

HTTP Request

GET http://api.boast.io/v1/accounts/{id}

Contacts

Get All Contacts

Request

GET http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8/contacts

Response

{
  "data": [
    {
      "id": "b94f8eb4-6dea-4c25-932d-e25b5954c655",
      "first_name": "Michael",
      "last_name": "Bluth",
      "email": "michael.bluth@example.com",
      "mobile_phone": "+15555555555",
      "organization": "Bluth Company",
      "job_title": "President",
      "time_zone": "Eastern Time (US & Canada)",
      "country_code": "US",
      "location_id": "2f5c4510-65d9-4596-aca7-a4b2bd4918fd",
      "staff_id": "1ec592b5-3d92-43fe-8b3a-3e1f9075fd5e",
      "source": "response",
      "created_at": "2021-02-10T16:54:23.805Z",
      "updated_at": "2021-02-10T16:54:23.805Z",
      "links": {
        "detail": "https://demo.boast.io/contacts/b94f8eb4-6dea-4c25-932d-e25b5954c655",
        "edit": "https://demo.boast.io/contacts/b94f8eb4-6dea-4c25-932d-e25b5954c655/edit"
      }
    }
  ]
}

This endpoint retrieves all contacts for an account.

HTTP Request

GET http://api.boast.io/v1/accounts/{account_id}/contacts

Create A Contact

Request

POST http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8/contacts

{
  "email": "george.bluth@example.com",
  "mobile_phone": "+15555555555",
  "first_name": "George",
  "last_name": "Bluth",
  "organization": "Bluth Company",
  "job_title": "President",
  "time_zone": "Eastern Time (US & Canada)",
  "country_code": "US",
  "source": "api"
}

Response

{
  "data": {
    "id": "b94f8eb4-6dea-4c25-932d-e25b5954c655",
    "first_name": "George",
    "last_name": "Bluth",
    "email": "george.bluth@example.com",
    "mobile_phone": "+15555555555",
    "organization": "Bluth Company",
    "job_title": "President",
    "time_zone": "Eastern Time (US & Canada)",
    "country_code": "US",
    "location_id": null,
    "staff_id": null,
    "source": "api",
    "created_at": "2021-02-10T16:54:23.805Z",
    "updated_at": "2021-02-10T16:54:23.805Z",
    "links": {
      "detail": "https://demo.boast.io/contacts/b94f8eb4-6dea-4c25-932d-e25b5954c655",
      "edit": "https://demo.boast.io/contacts/b94f8eb4-6dea-4c25-932d-e25b5954c655/edit"
    }
  }
}

This endpoint creates a contact on an account.

HTTP Request

POST http://api.boast.io/v1/accounts/{account_id}/contacts

Parameters

Name Notes
email Requires either email or mobile_phone
mobile_phone Requires either mobile_phone or email
Must be an E.164 formatted phone number.
first_name
last_name
organization
job_title
time_zone
country_code Accepts ISO 3166-1 alpha-2 country code
source Accepts either api or integration. If no source is provided, api is used

Forms

Get All Forms

Request

GET http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8/forms

Response

{
  "data": [
    {
      "id": "8e424fa5-94fd-4353-8bec-96ed7a4bbd1a",
      "name": "NPS",
      "status": "active",
      "created_at": "2021-01-27T18:54:22.972Z",
      "updated_at": "2021-02-04T21:58:51.125Z"
    }
  ]
}

This endpoint retrieves all forms for an account.

HTTP Request

GET http://api.boast.io/v1/accounts/{account_id}/forms

Responses

Get All Responses

Request

GET http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8/responses

Response

{
  "data": [
    {
      "id": "174de834-eb54-4e33-9d87-4d104239894e",
      "status": "published",
      "thumbnail": {
        "url": "https://assets.boast.io/app/accounts/6713be5b-dc41-4af3-890a-9a67f2a4a06f/responses/c58aa5f8-3210-4a2a-b3ca-3a469bf2b424/teaser-35f98ba2c93ac7407625a23d8f954837.jpg",
        "open_graph_url": "https://assets.boast.io/app/accounts/6713be5b-dc41-4af3-890a-9a67f2a4a06f/responses/c58aa5f8-3210-4a2a-b3ca-3a469bf2b424/open_graph-b1a53d08c5c359511b7f07222e6dc960.jpg",
        "unprocessed_url": "https://assets.boast.io/app/accounts/6713be5b-dc41-4af3-890a-9a67f2a4a06f/responses/c58aa5f8-3210-4a2a-b3ca-3a469bf2b424/original-0ab2ebccb2daac4b8194ab2499c504dc.png"
      },
      "consent": "received",
      "display_weight": 1,
      "form_id": "b345d73d-197c-4990-8a0c-ee5f58287f98",
      "contact_id": "a308c983-dea1-4e73-9f4c-89db9c22cff0",
      "location_id": "3e340197-e579-40e1-8ed0-05a78aa26ece",
      "staff_id": "a17a4c54-6df6-48f1-aff3-f68a4aedcd7d",
      "accepted": "2021-02-11T17:47:52.940Z",
      "created": "2021-02-11T15:13:41.784Z",
      "updated": "2021-02-11T17:49:32.164Z",
      "fields": {
        "first_name": "Matt",
        "last_name": "Hall",
        "email": "help@boast.io",
        "feedback": "We love using Boast to collect videos from our customers, it's been an awesome tool for us!",
        "headline": "Boast is great!",
        "sentiment": "promoters",
        "rating": 5,
        "rating_type": "five_stars",
        "rating_max": 5,
        "video": {
          "url": "https://assets.boast.io/app/accounts/6713be5b-dc41-4af3-890a-9a67f2a4a06f/responses/4836ed10-7f81-4c37-9157-1979fdcc3d71/videos/95767ab2-b038-4d14-ad48-321b888474d3/video_mp4-d0199a3f7d97bd6bc007a949c8709148.mp4",
          "unprocessed_url": "https://assets.boast.io/app/accounts/6713be5b-dc41-4af3-890a-9a67f2a4a06f/responses/4836ed10-7f81-4c37-9157-1979fdcc3d71/videos/95767ab2-b038-4d14-ad48-321b888474d3/original-5968437c107cca65646ec23ea7d35741.webm"
        },
        "photo": {
          "url": "https://assets.boast.io/app/accounts/6713be5b-dc41-4af3-890a-9a67f2a4a06f/responses/b7e9178d-acf3-4d29-afe0-b53624a02392/photos/6bd306ed-ec26-49fb-9bca-bcc3f216b0fe/medium-d0199a3f7d97bd6bc007a949c8709148.jpg",
          "unprocessed_url": "https://assets.boast.io/app/accounts/6713be5b-dc41-4af3-890a-9a67f2a4a06f/responses/b7e9178d-acf3-4d29-afe0-b53624a02392/photos/6bd306ed-ec26-49fb-9bca-bcc3f216b0fe/original-184fb12980f96efb2ff88ea8b67a7a42.jpg"
        },
        "company": "Boast",
        "job_title": null,
        "mobile_phone": null
      },
      "additional_fields": {
        "my_custom_field": "Hello World!"
      },
      "tags": [
        {
          "name": "my-tag"
        }
      ],
      "links": {
        "detail": "https://demo.boast.io/responses/174de834-eb54-4e33-9d87-4d104239894e",
        "edit": "https://demo.boast.io/responses/174de834-eb54-4e33-9d87-4d104239894e/edit",
        "share": "https://demo.boast.io/r/174de834-eb54-4e33-9d87-4d104239894e"
      }
    }
  ]
}

This endpoint retrieves all responses for an account.

HTTP Request

GET http://api.boast.io/v1/accounts/{account_id}/responses

Sequences

Get All Sequences

Request

GET http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8/sequences

Response

{
  "data": [
    {
      "id": "2b83ab61-30ef-48d4-8029-e73f61717c0a",
      "collection_form_id": "a873bcdb-ae03-436a-8410-d5057b81db34",
      "enrollment_form_id": "2f2082e9-ad81-4c41-9cb9-eaa2de5790b4",
      "name": "Sudden Valley Development",
      "status": "active",
      "created_at": "2020-10-08T17:46:46.460Z",
      "updated_at": "2021-02-09T19:30:21.828Z"
    }
  ]
}

This endpoint retrieves all sequences for an account.

HTTP Request

GET http://api.boast.io/v1/accounts/{account_id}/sequences

Sequence Enrollments

Get All Sequence Enrollments

Request

GET http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8/sequence_enrollments

Response

{
  "data": [
    {
      "id": "09f1bd66-84fe-454f-ac12-4dc323f656aa",
      "contact_id": "61a06314-fa2e-4fc8-bbcf-f942075042cc",
      "sequence_id": "df51783e-c81c-460b-82dc-8c5a63b70e92",
      "response_id": "ee456cc9-91a9-48c2-8f04-4e28d92788d2",
      "status": "completed",
      "created_at": "2021-02-04T21:13:44.005Z",
      "updated_at": "2021-02-04T21:13:44.005Z"
    }
  ]
}

This endpoint retrieves all sequence enrollments for an account.

HTTP Request

GET http://api.boast.io/v1/accounts/{account_id}/sequence_enrollments

Get a Specific Sequence Enrollment

Request

GET http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8/sequence_enrollments/09f1bd66-84fe-454f-ac12-4dc323f656aa

Response

{
  "data": {
    "id": "09f1bd66-84fe-454f-ac12-4dc323f656aa",
    "contact_id": "61a06314-fa2e-4fc8-bbcf-f942075042cc",
    "sequence_id": "df51783e-c81c-460b-82dc-8c5a63b70e92",
    "response_id": "ee456cc9-91a9-48c2-8f04-4e28d92788d2",
    "status": "completed",
    "created_at": "2021-02-04T21:13:44.005Z",
    "updated_at": "2021-02-04T21:13:44.005Z"
  }
}

This endpoint retrieves a single sequence enrollment.

HTTP Request

GET http://api.boast.io/v1/accounts/{account_id}/sequence_enrollments/{enrollment_id}

Create A Sequence Enrollment

Request

POST http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8/sequence_enrollments

{
  "contact_id": "6d1c8d94-c598-461e-ad76-f4851e4af9d4",
  "sequence_id": "e16f6028-cfc1-4d9d-a087-0a8574d2f13f"
}

Response

{
  "data": {
    "id": "09f1bd66-84fe-454f-ac12-4dc323f656aa",
    "contact_id": "6d1c8d94-c598-461e-ad76-f4851e4af9d4",
    "sequence_id": "e16f6028-cfc1-4d9d-a087-0a8574d2f13f",
    "response_id": null,
    "status": "active",
    "created_at": "2021-02-04T21:13:44.005Z",
    "updated_at": "2021-02-04T21:13:44.005Z"
  }
}

This endpoint enrolls an existing contact in a sequence.

HTTP Request

POST http://api.boast.io/v1/accounts/{account_id}/sequence_enrollments

Parameters

Name Notes
contact_id Required
sequence_id Required

Remove a Sequence Enrollment

Request

DELETE http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8/sequence_enrollments/09f1bd66-84fe-454f-ac12-4dc323f656aa

Response

{
  "data": {
    "id": "09f1bd66-84fe-454f-ac12-4dc323f656aa",
    "contact_id": "61a06314-fa2e-4fc8-bbcf-f942075042cc",
    "sequence_id": "df51783e-c81c-460b-82dc-8c5a63b70e92",
    "response_id": "ee456cc9-91a9-48c2-8f04-4e28d92788d2",
    "status": "removed",
    "created_at": "2021-02-04T21:13:44.005Z",
    "updated_at": "2021-02-04T21:13:44.005Z"
  }
}

This endpoint unenrolls a contact with an active enrollment from a sequence.

HTTP Request

DELETE http://api.boast.io/v1/accounts/{account_id}/sequence_enrollments/{enrollment_id}

Webhook Subscriptions

Get All Webhook Subscriptions

Request

GET http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8/webhook_subscriptions

Response

{
  "data": [
    {
      "id": "cb836066-c343-4b0a-8516-dbd802567b92",
      "event_name": "response.status.changed",
      "filters": {
        "form_id": "d15cd168-4001-4f7e-8e59-d66eb9524a37",
        "to_status": "published"
      },
      "target_url": "https://your-site.example.com/hooks/4f29c329-8f19-419c-ad0a-519232d73ee8",
      "user_id": "1c2e2e9b-529a-4870-8781-311e83ab95a1",
      "created_at": "2021-01-28T13:16:39.917Z"
    }
  ]
}

This endpoint retrieves all webhook subscriptions for an account.

HTTP Request

GET http://api.boast.io/v1/accounts/{account_id}/webhook_subscriptions

Create A Webhook Subscriptions

Request

POST http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8/webhook_subscriptions

{
  "event_name": "response.status.changed",
  "target_url": "https://your-site.example.com/hooks/4f29c329-8f19-419c-ad0a-519232d73ee8",
  "filters": {
    "form_id": "d15cd168-4001-4f7e-8e59-d66eb9524a37",
    "to_status": "published"
  }
}

Response

{
  "data": {
    "id": "cb836066-c343-4b0a-8516-dbd802567b92",
    "event_name": "response.status.changed",
    "filters": {
      "form_id": "d15cd168-4001-4f7e-8e59-d66eb9524a37",
      "status": "published"
    },
    "target_url": "https://your-site.example.com/hooks/4f29c329-8f19-419c-ad0a-519232d73ee8",
    "user_id": "1c2e2e9b-529a-4870-8781-311e83ab95a1",
    "created_at": "2021-01-28T13:16:39.917Z"
  }
}

This endpoint creates a webhook subscription for a specific event. Additional filters can be provided.

HTTP Request

POST http://api.boast.io/v1/accounts/{account_id}/webhook_subscriptions

Parameters

Name Notes
event_name Required
See table of possible events below.
target_url Required
filters Optional object of filters checked when sending webhook requests. See table of supported filters by event below.

Webhook Events

Name Supported Filters
response.available form_id
response.status.changed form_id, status
response.published form_id
response.destroyed form_id
contact.created
contact.updated
contact.destroyed

Destroy a Webhook Subscription

Request

DELETE http://api.boast.io/v1/accounts/7a2f1f8c-7771-47e2-8dbd-332b301028a8/webhook_subscriptions/cb836066-c343-4b0a-8516-dbd802567b92

Response

204 No Content

This endpoint destroys a webhook subscription.

HTTP Request

DELETE http://api.boast.io/v1/accounts/{account_id}/webhook_subscriptions/{webhook_subscription_id}