Introduction

👏 Welcome to the Gist API reference 👏

You can use the Gist API to integrate Gist into other software applications and custom workflows.

The API is designed to be a predictable and intuitive way to interact with your company’s Gist workspace.

Like Gist itself the API is under continuous development, so changes and improvements are to be expected. Be sure to keep an eye on our Changelog to receive information on new additions and changes to both Gist and the API when we release new features and changes.

For more information about Gist products, you can visit our product documentation.

If you’re looking to install Gist on your website or web application using our client-side JavaScript API, you can find the instructions here.

Authentication

Example Request

$ curl --request GET \
-s https://api.getgist.com/contacts/146179 \
-H 'Authorization:Bearer <ACCESS_TOKEN>' \
-H 'Content-Type:application/json'

Make sure to replace ACCESS_TOKEN with your API key.

Authenticate your workspace when using the API by including your secret API Key in the request. You can access your API Key in the Integration Settings on your Gist dashboard.

Note that your API Key allows you access to your private contact data in Gist and as such it should not be shared outside of your company. If a certain integration, that's not listed on our Integrations page, requests your API Key, please reach out to us, and don't share your key with anyone. Also, do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Bearer Auth.

You need to send your API Key in the Authorization header in each request. Ex: Authorization: Bearer sk_test_BQokikJOvBiI2HlWgH4olfQ2 where sk_test_BQokikJOvBiI2HlWgH4olfQ2 is the API Key. To learn more about the bearer token framework, please see the official spec here.

Working with OAuth

OAuth is a secure means of authentication that uses authorization tokens rather than an access token to connect your app to a user's workspace. Initiating OAuth access is the first step towards allowing users to install your app in their Gist workspace(s).

The OAuth flow allows you to customize the user’s experience by passing additional parameters to Gist. Some common examples are explained below, and the rest of the reference lists every possible option.

Learn more here.

Rate Limits

This API is rate limited to 100 requests for 10 seconds per workspace. Any requests beyond that are rejected with a http 429 response code. Also, note that all integrations must comply with the Gist's Terms of Use.

Errors

Gist uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a search failed, etc.), and codes in the 5xx range indicate an error with Gist’s servers.

Code	Name	Description
200	OK	Everything worked as expected.
400	Bad Request	Your request could not be processed. Often due to missing a required parameter.
400	Invalid Action	The action requested was not valid for this resource.This error is returned when you try to access an action that doesn't exist. For example, /campaigns/{id}/subscribe
400	JSON Parse Error	We encountered an unspecified JSON parsing error.This error means that your JSON was formatted incorrectly or was considered invalid or incomplete.
401	API Key Missing	Your request did not include an API key.This error suggests that your API key was missing from your request, or that something was formatted or named improperly in your header.
401	API Key Invalid	Your API key may be invalid.Check that your API key was input correctly.
403	Forbidden	You are not permitted to access this resource.
403	Workspace Disabled	This workspace has been disabled.Contact our support team if you need more help.
404	Not Found	The requested resource could not be found. This error tells you a specific resource doesn't exist. It's possible that the resource has been moved or deleted, or that there's a typo in your request.
405	Method Not Allowed	The requested method and resource are not compatible. See the Allow header for this resource's available methods.This error means that the requested resource does not support the HTTP method you used.
429	Too Many Requests	You have maxed your number of API calls for the provided time window.
500, 502, 503, 504	Server errors	An unexpected internal error has occurred at our end. Please contact Support for more information.This error lets you know our servers have experienced a problem. Although this is rare, please contact [email protected] to let us know that you've encountered this error.

API Structure

API Area	API Endpoint	Description
Contacts	`https://api.getgist.com/contacts`	Create and update Contacts. Use filters to get lists of contacts, or access their profiles individually.
Events	`https://api.getgist.com/events`	Use Events to submit User activity to Gist
Tags	`https://api.getgist.com/tags`	Organize your Contacts with tags.
Segments	`https://api.getgist.com/segments`	Fetch a list of your segments.
Forms	`https://api.getgist.com/forms`	Fetch list of forms, form submissions. Subscribe contacts to the forms.
Campaigns	`https://api.getgist.com/campaigns`	Fetch, pause or set live a campaign or list all Contacts subscribed to a campaign.
Conversations	`https://api.getgist.com/conversations`	Fetch list of conversations you have with contacts. Send messages and reply to conversations.
Teams	`https://api.getgist.com/teams`	Fetch list of teams.
Teammates	`https://api.getgist.com/teammates`	Fetch list of teammates.

Contacts

A Contact is any individual with an email address. The Contacts API allows you to create, view, delete and update your contacts. You can retrieve an individual Contact, list all Contacts, or use search filters to view subsets of your Contacts.

Details for your contact records are primarily stored in the contact properties for your contacts. In addition to several default properties, you can store any custom data that is pertinent to your contact records by creating custom properties for contacts.

Use case: Your team is using Gist and another software system for their work. They need accurate contact information in both systems, but don't want to spend time making manual updates. You can use the Contacts API to integrate the two systems and sync contact information.

Note: The Gist Contacts API treats an email address as the primary identifier for a contact and these endpoints automatically de-duplicate email addresses to keep your Gist data clean.

The contact object

The Contacts object provides details on your contacts within Gist, and will specify whether they are a user or lead through the user-type property.

Example Response

{
  "contact": {
    "type": "lead",
    "id": 146179,
    "name": "Rubamaga",
    "email": "[email protected]",
    "user_id": "22449",
    "phone": null,
    "created_at": 1506500350,
    "signed_up_at": null,
    "last_seen_at": 1506500350,
    "last_contacted_at": null,
    "updated_at": 1506501237,
    "session_count": null,
    "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=GO",
    "landing_url": null,
    "original_referrer": null,
    "last_seen_ip": "127.0.0.1",
    "last_seen_user_agent": null,
    "location_data": {
      "city_name": "Paris",
      "region_name": null,
      "country_name": "France",
      "country_code": "FR",
      "continent_code": null,
      "latitude": 48.871216,
      "longitude": 2.311713,
      "postal_code": null,
      "time_zone": null,
      "utc_offset": null
    },
    "segments": [],
    "tags": [],
    "subscription_types": [],
    "social_profiles": null,
    "custom_properties": {
      "age": 22
    },
    "unsubscribed_from_emails": false
  }
}

Contact object

Property	Type	Description
type	string	Type of the contact ('lead' or 'user')
id	string	The unique identifier for the contact generated by Gist.
name	string	The full name of the contact
email	string	The email address of the contact
user_id	string	The user id of the contact (given by you)
phone	string	The contact number of the contact
created_at	timestamp	The time the contact was added to Gist
signed_up_at	timestamp	The time the contact signed up
last_seen_at	timestamp	The time the contact was last seen
updated_at	timestamp	The time the contact was last updated
last_contacted_at	timestamp	The time the contact was last contacted
session_count	integer	The count of sessions the contact has recorded
avatar	string	The URL of contact’s avatar image
landing_url	string	The URL of the page the contact first visited on your website
original_referrer	string	The referrer URL the contact came to your website from
last_seen_ip	string	The last IP address the contact visited your website from
last_seen_user_agent	string	The last user agent the contact was seen using
location_data	json	A JSON object containing the location details of the contact
segments	string	An Array containing one or more segments the contact belongs to
tags	string	Optional. An Array containing one or more tags the contact has. E.g. ["Customer", "VIP"]
subscription_types	string	An array of subscription type contact is opted-in
social_profiles	json	A JSON object listing all the social profiles details of the contact
custom_properties	json	Optional. A JSON object containing the contact’s custom properties. E.g. { "name": "John Doe" }
unsubscribed_from_emails	boolean	If the contact has unsubscribed from emails or not

Location Data

Property	Type	Description
city_name	string	The city name
region_name	string	The region name
country_name	string	The country name
country_code	string	The ISO 3166 country code
continent_code	string	The continent code
latitude	number	The latitude
longitude	number	The longitude
postal_code	string	The postal code
time_zone	string	The ISO 8601 timezone
utc_offset	integer	The timezone offset relative to UTC

Note that location data is read-only, and cannot be updated via the API,

Property	Type	Description
name	string	The name of the social media service (e.g., facebook, twitter)
id	string	The User ID on the service
username	string	The username on the service
url	string	The URL of the contact’s profile on the service

Note that social data is read-only, and cannot be updated via the API.

Custom Properties

The custom_properties object allows you to send any information you wish about a contact with the following restrictions:

Property names must not contain Periods ('.') or Dollar ('$') characters
Property values must be JSON Strings, Numbers or Booleans - Objects and Arrays will be rejected.
Property names must be no longer than 190 characters.
String property values must be no longer than 255 characters.
You can create a maximum of 250 custom properties.
You can send dates as custom properties by sending a UNIX timestamp. If the name of your custom property ends with _at then we'll automatically treat it as a date, rather than a number.

Create or update a contact

Example Request

curl --request POST \
  --url https://api.getgist.com/contacts \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "179351",
    "user_id":100488,
    "email": "[email protected]",
    "name": "Rubamaga",
    "phone": null,
    "signed_up_at": "",
    "last_seen_ip": "",
    "last_seen_user_agent": "",
    "unsubscribed_from_emails": false,
    "custom_properties": {
           "age": 23
    },
    "tags": [
        "tagA",
        "tagB",
        "tagC"
    ]
}'

Example Response

{
    "contact": {
        "type": "user",
        "id": 179351,
        "name": "Rubamaga",
        "email": "[email protected]",
        "user_id": "100488",
        "phone": null,
        "created_at": 1502979465,
        "signed_up_at": 0,
        "last_seen_at": 1502979465,
        "last_contacted_at": null,
        "updated_at": 1540478268,
        "session_count": null,
        "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=BR",
        "landing_url": null,
        "original_referrer": null,
        "last_seen_ip": "",
        "last_seen_user_agent": "",
        "location_data": {
            "city_name": "Paris",
            "region_name": null,
            "country_name": "France",
            "country_code": "FR",
            "continent_name": null,
            "continent_code": null,
            "latitude": 48.871216,
            "longitude": 2.271031,
            "postal_code": null,
            "time_zone": null,
            "utc_offset": null
        },
        "segments": [
            {
                "id": 578,
                "name": "Test validation",
                "created_at": 1512633515,
                "updated_at": 1512633567
            }
        ],
        "tags": [
            {
                "id": 79,
                "name": "tagA"
            },
            {
                "id": 80,
                "name": "tagB"
            },
            {
                "id": 81,
                "name": "tagC"
            }
        ],
        "social_profiles": [],
        "custom_properties": {
            "form_user": null,
            "user_types": null,
            "age": 23,
            "first_name": null
        },
        "unsubscribed_from_emails": "false"
    }
}

Create a new contact in Gist with a simple HTTP POST to the Contacts API. The contact that is created will be assigned a unique ID (id) by Gist, which can be used to look it up later.

Returns 200 response on success. The response will include the details of the contact.
Returns 422 (or) 400 error when the data in the request body fails validation.

Note: The endpoint will create a new contact if it doesn't find one matching with the email and/or user_id in the request, and updates the contact if it finds a match.

Create a new contact

If only email is provided in the HTTP request, the contact will be created as a Lead.
If both user_id and email are provided, the contact will be created as a User.

Update an existing contact

Note that the following lookup order applies when updating Contacts - id then user_id then email, and results in the following logic:

if id has matched - the user_id and email will be updated if they are included in the request.
if user_id has matched - the email will be updated, the id will not be updated.
if email has matched - if no user_id is set on the matched contact, then user_id will be set to the value sent in the request, the id is not updated. Note that this will change the Contact’s type from Lead to User.
if email has matched and the matched contact has a user_id value - the user_id of the matched contact will be set to the value sent in the request, the id is not updated.

Note that email values are down-cased after they have been submitted to our API.

Property	Required	Description
email	Required on create. Required if no user_id is supplied on update.	The contact's email address.
user_id	Required on create. Required if no email is supplied on update.	A unique string identifier for the user. It is required to create Contact of type User
name	no	The full name of the contact
phone	no	The contact number of the contact
signed_up_at	no	The time the contact signed up
last_seen_ip	no	The last IP address the contact visited your website from
last_seen_user_agent	no	The last contact agent the contact was seen using
custom_properties	no	Optional. A JSON object containing the contact’s custom properties. E.g. { "name": "John Doe" }
unsubscribed_from_emails	no	If the contact has unsubscribed from emails or not
tags	no	The tags the contact is assigned.

Please note that location data and social profiles are computed by Gist and cannot be updated via the API.

New contact objects will be provided with an id field - this value cannot be changed. Social profiles, location data and avatars are processed asynchronously, and may require a subsequent call to fetch their details.

Response

A Contact object.

Create or update a batch of contacts

Example Request

curl --request POST \
  --url https://api.getgist.com/contacts/batch \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
              "contacts": [
                  {
                      "email": "[email protected]",
                      "name": "Rubamaga2",
                      "phone": null,
                      "last_seen_user_agent": "",
                      "unsubscribed_from_emails": false,
                      "custom_properties": {
                          "age": 23
                      },
                      "tags": [
                          "tagA"
                      ]
                  },
                  {
                      "id": "179351",
                      "email": "[email protected]",
                      "name": "Rubamaga",
                      "phone": null,
                      "last_seen_user_agent": "",
                      "unsubscribed_from_emails": false,
                      "custom_properties": {
                          "age": 25
                      },
                      "tags": [
                          "tagC"
                      ]
                  }
              ]
          }'

Create a batch of contacts in Gist with a HTTP POST to the Contacts API. The contacts that are created will individually be assigned a unique ID (id) by Gist, which can be used to look it up later.

Returns 200 response on success. The response will include array of details for the created contacts.
Returns 422 (or) 400 error when there is a problem with the data in the request body, including when there are no properties included in the request data.

Note:

This endpoint will create new contacts if it doesn't find one matching the email or user_id in the request, and updates the contact if it finds a match.
If any of the contact properties has invalid data, for example, text passed in place of numeric property, the entire request will fail and no contacts will be created.

Response

A paginated list of Contact objects.

Retrieve a contact

Example Request

$ curl --request GET \
--url https://api.getgist.com/contacts/146719 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'

Example Response

{
    "contact": {
        "type": "lead",
        "id": 179351,
        "name": "Rubamaga",
        "email": "[email protected]",
        "phone": null,
        "created_at": 1502979465,
        "signed_up_at": 0,
        "last_seen_at": 1502979465,
        "last_contacted_at": null,
        "updated_at": 1540478268,
        "session_count": null,
        "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=BR",
        "landing_url": null,
        "original_referrer": null,
        "last_seen_ip": "",
        "last_seen_user_agent": "",
        "location_data": {
            "city_name": "Paris",
            "region_name": null,
            "country_name": "France",
            "country_code": "FR",
            "continent_name": null,
            "continent_code": null,
            "latitude": 48.871216,
            "longitude": 2.271031,
            "postal_code": null,
            "time_zone": null,
            "utc_offset": null
        },
        "segments": [
            {
                "id": 578,
                "name": "Test validation",
                "created_at": 1512633515,
                "updated_at": 1512633567
            }
        ],
        "tags": [
            {
                "id": 79,
                "name": "Completed"
            }
        ],
        "social_profiles": [],
        "custom_properties": {
            "form_user": null,
            "user_types": null,
            "age": 23,
            "first_name": null
        },
        "unsubscribed_from_emails": "false"
    }
}

Contacts can be fetched or looked up individually via their id, email or with a user_id parameter.

The ‘contacts’ endpoint accepts two parameters:

Parameter	Required	Description
user_id	no	The user id of the contact in your database
email	no	The email address of the contact

A contact can also be fetched using a user_id or email parameter in the url:

https://api.getgist.com/contacts?user_id={user_id}

https://api.getgist.com/contacts?email={email}

The email parameter value should be url encoded when sending.

Unique URL

Each contact object has its own URL

https://api.getgist.com/contacts/{id}

Where {id} is the value of the contact's id field generated by Gist. This URL is the contact's canonical address in the API.

Response

A Contact object.

List all contacts

Example Request

$ curl --request GET \
--url https://api.getgist.com/contacts?order=desc&order_by=created_at&page=18&per_page=5 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'

Example Response

{
    "contacts": [
          {
                "type": "user",
                "id": 179351,
                "name": "Rubamaga",
                "email": "[email protected]",
                "user_id": "100488",
                "phone": null,
                "created_at": 1502979465,
                "signed_up_at": 0,
                "last_seen_at": 1502979465,
                "last_contacted_at": null,
                "updated_at": 1540478268,
                "session_count": null,
                "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=BR",
                "landing_url": null,
                "original_referrer": null,
                "last_seen_ip": "",
                "last_seen_user_agent": "",
                "location_data": {
                    "city_name": "Paris",
                    "region_name": null,
                    "country_name": "France",
                    "country_code": "FR",
                    "continent_name": null,
                    "continent_code": null,
                    "latitude": 48.8712,
                    "longitude": 2.2710,
                    "postal_code": null,
                    "time_zone": null,
                    "utc_offset": null
                },
                "segments": [
                    {
                        "id": 578,
                        "name": "Test validation",
                        "created_at": 1512633515,
                        "updated_at": 1512633567
                    }
                ],
                "tags": [
                    {
                        "id": 79,
                        "name": "Completed"
                    }
                ],
                "social_profiles": [],
                "custom_properties": {
                    "form_user": null,
                    "user_types": null,
                    "age": 23,
                    "first_name": null
                },
                "unsubscribed_from_emails": "false"
        },
        {
            "type": "lead",
            "id": 72712,
            "name": "Isaac",
            "email": "[email protected]",
            "phone": null,
            "created_at": 1497462203,
            "signed_up_at": 1497462409,
            "last_seen_at": 1510133377,
            "last_contacted_at": 1538552818,
            "updated_at": 1538552819,
            "session_count": 15,
            "avatar": "https://d2i5n66vu52qed.cloudfront.net/uploads/person_company/picture/560003/picture",
            "landing_url": "getgist.com",
            "original_referrer": "",
            "last_seen_ip": "103.237.57.123",
            "last_seen_user_agent": null,
            "location_data": {
                "city_name": "Paris",
                "region_name": null,
                "country_name": "France",
                "country_code": null,
                "continent_name": null,
                "continent_code": null,
                "latitude": 48.8967,
                "longitude": 2.2521,
                "postal_code": null,
                "time_zone": null,
                "utc_offset": null
            },
            "segments": [
                {
                    "id": 5,
                    "name": "All Users",
                    "created_at": 1493141363,
                    "updated_at": 1534413183
                }
            ],
            "tags": [
                {
                    "id": 2,
                    "name": "Potential Lead"
                }
            ],
            "social_profiles": [],
            "custom_properties": {
                "form_user": "33161518",
                "test": null,
                "age": 30,
                "first_name": null
            },
            "unsubscribed_from_emails": "false"
        },
        {
            "type": "user",
            "id": 72057,
            "name": "neyu",
            "email": "[email protected]",
            "user_id": "72057",
            "phone": null,
            "created_at": 1497348057,
            "signed_up_at": 1497348057,
            "last_seen_at": 1505199304,
            "last_contacted_at": 1538552819,
            "updated_at": 1538552820,
            "session_count": 136,
            "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=MA",
            "landing_url": "app.getgist.com/projects/rdkopx3d/events",
            "original_referrer": "",
            "last_seen_ip": "103.237.57.123",
            "last_seen_user_agent": null,
            "location_data": {
                "city_name": "Duba",
                "region_name": null,
                "country_name": "Saudi Arabia",
                "country_code": "SA",
                "continent_name": null,
                "continent_code": null,
                "latitude": 27.3657,
                "longitude": 35.7031,
                "postal_code": null,
                "time_zone": null,
                "utc_offset": null
            },
            "segments": [
                {
                    "id": 611,
                    "name": "Test filters",
                    "created_at": 1524577042,
                    "updated_at": 1538552649
                }
            ],
            "tags": [],
            "social_profiles": [],
            "custom_properties": {
                "form_user": null,
                "test": null,
                "age": 27,
                "first_name": null
            },
            "unsubscribed_from_emails": "false"
        },
        {
            "type": "lead",
            "id": 70524,
            "name": "Bringe",
            "email": "[email protected]",
            "phone": null,
            "created_at": 1497015399,
            "signed_up_at": 1497015445,
            "last_seen_at": 1510133376,
            "last_contacted_at": 1538552820,
            "updated_at": 1538552820,
            "session_count": 47,
            "avatar": "https://d2i5n66vu52qed.cloudfront.net/uploads/person_company/picture/610235/picture",
            "landing_url": "app.getgist.com/users/sign_in",
            "original_referrer": "",
            "last_seen_ip": "103.237.57.123",
            "last_seen_user_agent": null,
            "location_data": {
                "city_name": "Melbourne",
                "region_name": null,
                "country_name": "Australia",
                "country_code": "AU",
                "continent_name": null,
                "continent_code": null,
                "latitude": -37.7556,
                "longitude": 144.8277,
                "postal_code": null,
                "time_zone": null,
                "utc_offset": null
            },
            "segments": [
                {
                    "id": 578,
                    "name": "Test validation",
                    "created_at": 1512633515,
                    "updated_at": 1512633567
                }
            ],
            "tags": [],
            "social_profiles": [],
            "custom_properties": {
                "expiry_at": null,
                "key_test": null,
                "age": 31,
                "first_name": null
            },
            "unsubscribed_from_emails": "false"
        },
        {
            "type": "user",
            "id": 70502,
            "name": "Alex Aashan",
            "email": "[email protected]",
            "user_id": "70502",
            "phone": null,
            "created_at": 1497011902,
            "signed_up_at": 1497011972,
            "last_seen_at": 1510133376,
            "last_contacted_at": 1538552820,
            "updated_at": 1538552821,
            "session_count": 4,
            "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=AL",
            "landing_url": "getgist.com",
            "original_referrer": "",
            "last_seen_ip": "103.237.57.123",
            "last_seen_user_agent": null,
            "location_data": {
                "city_name": "Sydney",
                "region_name": null,
                "country_name": "Australia",
                "country_code": "AU",
                "continent_name": null,
                "continent_code": null,
                "latitude": 33.7614,
                "longitude": 150.7713,
                "postal_code": null,
                "time_zone": null,
                "utc_offset": null
            },
            "segments": [
                {
                    "id": 8,
                    "name": "Slipping Away",
                    "created_at": 1493141363,
                    "updated_at": 1539763645
                }
            ],
            "tags": [
                {
                    "id": 2,
                    "name": "Potential Lead"
                }
            ],
            "social_profiles": [],
            "custom_properties": {
                "expiry_at": null,
                "form_user": "33161518",
                "age": 29,
                "first_name": null
            },
            "unsubscribed_from_emails": "false"
        }
    ],
    "pages": {
        "prev": "https://api.getgist.com/contacts?order=desc&order_by=created_at&page=17&per_page=5",
        "next": "https://api.getgist.com/contacts?order=desc&order_by=created_at&page=19&per_page=5",
        "first": "https://api.getgist.com/contacts?order=desc&order_by=created_at&page=1&per_page=5",
        "last": "https://api.getgist.com/contacts?order=desc&order_by=created_at&page=32&per_page=5"
    }
}

You can fetch a list of contacts. The contact list is sorted by the created_at property and by default is ordered descending, most recently created first.

Request Parameters

The following optional parameters can be used to request the result page size and which page to fetch.

Parameter	Required	Description
page	no	The page of results to fetch. Defaults to first page.
per_page	no	The number of results per page. Defaults to 50, max is 60.
order	no	The sort order of the returned contacts. asc or desc. Defaults to desc.
order_by	no	Sort the list of contact by their last_seen_at, created_at, updated_at, or signed_up_at. Defaults to created_at.
created_since	no	Limit results to users that were created in that last number of days.
status	no	Filter contacts by their email subscription status: active, or unsubscribed, or bounced. Defaults to all.
form_id	no	Filter contacts who submitted a specific form. You can get the form_id from Forms API.
email_like	no	Filter contacts that contains a specific keyword in their email address.
segment_id	no	Filter contacts that match a segment. You can get the segment_id from Segments API
campaign_id	no	Filter contacts subscribed to a specific campaign. You can get the campaign id from Campaigns API.
tag_id	no	Filter contacts with a specific tag. You can get the tag id from Tags API.

The contact list contains a pages object that indicates if more contacts exist via the next key, which holds the URL that can be used to fetch the next page. If the next field is not present, that indicates there are no further contacts in the list.

Response

A paginated list of Contact objects.

Delete a contact

Example Request

$ curl --request DELETE \
--url https://api.getgist.com/contacts/265 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'

Example Response

{
    "id": "323df95",
    "object": "contact",
    "deleted": "true"
}

A contact can be deleted by sending a DELETE request to its URL using the contact's id field as part of the request.

https://api.getgist.com/contacts/{id}

Alternatively, you can delete a contact by sending a DELETE request using the email or user_id as query parameters:

https://api.getgist.com/contacts?email={email}

https://api.getgist.com/contacts?user_id={user_id}

Parameter	Required	Description
email	no	The email address of the contact
user_id	no	The user id of the contact in your database

Response

A Contact object.

Events

The event object

Example Response

{
    "event": {
        "id": 97677,
        "user_id": null,
        "email": "[email protected]",
        "name": "Clicked Signup Button",
        "properties": {
            "manual_record": true,
            "recorded_from": "backend"
        },
        "occurred_at": 1540541183
    }
}

An Event object describes the event and contains the following fields:

Parameter	Required	Description
event_name	yes	The name of the event that occurred
user_id	yes if no email	A unique identifier for the contact
email	yes if no user_id	An email address for your user.
id	yes if no email or user_id	A Gist generated identifier for the contact
occurred_at	timestamp	The time the event occurred in ISO-8601 format. Defaults to the current time
properties	json	A JSON of custom properties for the event

The event_name field is processed as follows:

Event names are case insensitive. 'Completed-Order' and 'completed-order' will be considered the same event for your workspace.
Periods (.) and dollars ($) in event names are replaced with hyphens. e.g., 'completed.order' will be stored as 'completed-order'.

To avoid confusion, we recommend sending lowercase event names that do not contain periods or dollars.

Track an event

Example Request

$ curl --request POST \
--url https://api.getgist.com/events \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
    "event_name": "Clicked Signup Button",
    "email": "[email protected]",
    "properties": {
    "manual_record": true,
    "recorded_from": "backend"
  },
  "occurred_at": null
}'

Example Response

{
    "event": {
        "id": 97677,
        "user_id": null,
        "email": "[email protected]",
        "name": "Clicked Signup Button",
        "properties": {
            "manual_record": true,
            "recorded_from": "backend"
        },
        "occurred_at": 1540541183
    }
}

You can track an event by submitting a POST to https://api.getgist.com/events along with a name of the event and a reference to the contact who performed the event.

Response

A Event object.

List all events

Example Request

$ curl --request GET \
--url https://api.getgist.com/events?event_type=all \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'

Example Response

{
    "events": [
        {
            "id": 97677,
            "name": "Clicked Signup Button"
        },
        {
            "id": 611,
            "name": "Inactive"
        },
        {
            "id": 7,
            "name": "Active"
        },
        {
            "id": 133,
            "name": "Email Subscribed"
        },
        {
            "id": 132,
            "name": "Send Notification"
        },
    ],
    "pages": {
        "first": "https://api.getgist.com/events?order=desc&order_by=created_at&page=1&per_page=50",
        "last": "https://api.getgist.com/events?order=desc&order_by=created_at&page=1&per_page=50"
    }
}

You can fetch all the events of a Workspace by sending a GET request to https://api.getgist.com/events.

Parameter	Required	Description
page	no	The page number. Defaults to 1.
per_page	no	The number of records to be returned on each page. Defaults to 50. Maximum 60.

Response

A paginated list of Event objects.

Parameter	Type	Description
id	string	The id of the tag
name	string	The name of the tag

Parameter	Required	Description
id	yes for an update	The id of the tag
name	yes	The name of the tag, which will be created if no tag was found, or the new name of the tag if this is an update request

Subscription Types

The subscription type object

{
  "id": 43,
  "name": "Announcements",
  "description": "Offers, product and feature announcements",
  "people_count": 1,
  "status": "published",
  "display_order": 1 // 2, 3, 4 depending on the position of the subscription
}

A subscription type lets customers easily opt out of non-essential communications without missing what’s important to them.

Property	Type	Description
id	integer	The id of the subscription type
name	string	The name of the subscription type
description	string	Description for the subscription type
people_count	integer	Number of contacts subscribed
status	string	Status of the subscription type
display order	integer	Display Order of the subscription type

Retrieve a subscription type

Example Request

curl --request GET \
  --url https://api.getgist.com/subscription_types/43 \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \

You can fetch the details of a single subscription type.

GET https://api.getgist.com/subscription_types/{subscription_type_id}

Response

A Subscription Type object.

List all subscription types

Example request

curl --request GET \
  --url https://api.getgist.com/subscription_types \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \

You can fetch a list of all subscription types.

GET https://api.getgist.com/subscription_types

Response

A paginated list of Subscription Type objects.

Attach a contact to subscription type

Example Request

curl --request POST \
  --url https://api.getgist.com/subscription_types/43 \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data { "email": "[email protected]",
           "subscribed_status": true }

You can add a subscription to a contact by submitting POST to https://api.getgist.com/subscription_types/{subscription_type_id}

Parameter	Required	Description
user_id	yes	User id of the contact
email	yes if no user_id	Email id of the contact
contact_id	yes if no user_id and email	Unique Id of the contact
subscribed_status	yes	Describes if contact is added or removed from subscription. 'true' to add and 'false' to remove

Response

A Contact object.

Detach a contact from subscription type

Example Request

curl --request POST \
  --url https://api.getgist.com/subscription_types/43 \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data { "email": "[email protected]",
           "subscribed_status": false }

You can remove a subscription from a contact by submitting POST to https://api.getgist.com/subscription_types/{subscription_type_id}

Parameter	Required	Description
user_id	yes	User id of the contact
email	yes if no user_id	Email id of the contact
contact_id	yes if no user_id and email	Unique Id of the contact
subscribed_status	yes	Describes if contact is added or removed from subscription. 'true' to add and 'false' to remove

Response

A Contact object.

Segments

Segments are dynamic groups of contacts defined by filters and rules that you set.

The segment object

Example Response

{
    "segment": {
        "id": 7,
        "name": "Active",
        "created_at": 1493141363,
        "updated_at": 1539756959,
        "count": 43
    }
}

A segment has a name and an id field along with created_at and updated_at timestamps. It can optionally include a count of the contacts in the segment.

Parameter	Type	Description
id	string	The id representing the segment
name	string	The name of the segment
created_at	timestamp	The time the segment was created
updated_at	timestamp	The time the segment was updated
count	integer	The number of items in the segment. It's returned when include_count=true is included in the request

Retrieve a segment

Example Request

$ curl --request GET \
--url https://api.getgist.com/segments/7?include_count=true \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'

Example Response

{
    "segment": {
        "id": 7,
        "name": "Active",
        "created_at": 1493141363,
        "updated_at": 1539756959,
        "count": 2343
    }
}

Each segment has its own URL: https://api.getgist.com/segments/{id}

Where {id} is the value of the segment's id field. A GET request to a segment's URL will return the segment object.

You can also get a count for an individual segment by adding the parameter include_count=true

Response

A Segment object.

List all segments

Example Request

$ curl --request GET \
--url https://api.getgist.com/segments?per_page=2&page=5&include_count=true \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'

Example Response

{
    "segments": [
        {
            "id": 611,
            "name": "Inactive",
            "created_at": 1524577042,
            "updated_at": 1538552649,
            "count": 153
        },
        {
            "id": 7,
            "name": "Active",
            "created_at": 1512633515,
            "updated_at": 1512633567,
            "count": 2343
        }
    ],
    "pages": {
        "next": "https://api.getgist.com/segments?order=desc&order_by=created_at&page=2&per_page=2",
        "first": "https://api.getgist.com/segments?order=desc&order_by=created_at&page=1&per_page=2",
        "last": "https://api.getgist.com/segments?order=desc&order_by=created_at&page=7&per_page=2"
    }
}

You can list the segments for your Workspace by sending a GET request to https://api.getgist.com/segments. You can also include counts in your segment object in the response if you add the parameter include_count=true in the request.

Response

A paginated list of Segment object.

Forms

The form object

Example Response

{
    "form": {
            "id": 36,
            "title": "Welcome",
            "created_at": 1531550359,
            "form_type": "lightbox",
            "status": "live",
            "fields": [
                {
                    "key": "email",
                    "label": "Email Address",
                    "is_required": "true"
                }
            ]
    }
}

A Form object describes the form and contains the following fields

Property	Type	Description
id	string	The id representing the form
title	string	Title of the form
created_at	timestamp	The time the form was created
form_type	string	Type of the form
status	string	Status of the form
fields	array	Fields of the form

Retrieve a form

Example Request


curl --request GET \
  --url 'https://api.getgist.com/forms?form_id=42161287' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type:application/json'

Example Response

{
    "form": {
        "id": 42161287,
        "title": "Testing",
        "created_at": 1519189724,
        "form_type": "lightbox",
        "status": "live",
        "fields": [
            {
                "key": "email",
                "label": "Email Address",
                "is_required": "true",
                "type": "string"
            }
        ]
    }
}

You can fetch a form from a Workspace by sending a GET request to https://api.getgist.com/forms with form_id as the parameter.

The Form ID can be found in one of two ways.

You can pull a list of Forms using the Forms API, as documented below.
You can also find the Form ID in the Gist UI: navigate to Forms from the navigation menu > click to edit a specific form > when editing a specific form, you can find the Form ID in the URL of the embedded form section. In the URL https://data.getgist.com/subscribe/2775350, the form ID is 2775350

Response

A Form object.

List all forms

Example Request

curl --request GET \
  --url https://api.getgist.com/forms \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type:application/json'

Example Response

{
    "forms": [
        {
            "id": 95775704,
            "title": "sample",
            "created_at": 1561355053,
            "form_type": "notification",
            "status": "draft",
            "fields": [
                {
                    "key": "email",
                    "label": "Email Address",
                    "is_required": "true",
                    "type": "string"
                }
            ]
        },
        {
            "id": 72280292,
            "title": "Test form",
            "created_at": 1557735548,
            "form_type": "lightbox",
            "status": "draft",
            "fields": [
                {
                    "key": "email",
                    "label": "Email Address",
                    "is_required": "true",
                    "type": "string"
                }
            ]
        },
        {
            "id": 64911038,
            "title": "Example Form",
            "created_at": 1555393267,
            "form_type": "lightbox",
            "status": "paused",
            "fields": [
                {
                    "key": "email",
                    "label": "Email Address",
                    "is_required": "true",
                    "type": "string"
                }
            ]
        },
        {
            "id": 25482088,
            "title": "Light Box23",
            "created_at": 1553694654,
            "form_type": "lightbox",
            "status": "live",
            "fields": [
                {
                    "key": "email",
                    "label": "Email Address",
                    "is_required": "true",
                    "type": "string"
                }
            ]
        },
        {
            "id": 59683938,
            "title": "Example Form 2",
            "created_at": 1544262463,
            "form_type": "lightbox",
            "status": "paused",
            "fields": [
                {
                    "key": "email",
                    "label": "Email Address",
                    "is_required": "true",
                    "type": "string"
                },
                {
                    "key": "name",
                    "label": "name",
                    "is_required": "true",
                    "type": "string"
                },
                {
                    "key": "membership",
                    "label": "m",
                    "is_required": "true",
                    "type": "string"
                }
            ]
        }
    ],
    "page": {
        "first": "https://api.getgist.com/forms?order=desc&order_by=created_at&page=1&per_page=50",
        "last": "https://api.getgist.com/forms?order=desc&order_by=created_at&page=1&per_page=50"
    }
}

You can fetch all forms for a Workspace by sending a GET request to https://api.getgist.com/forms

The form list is sorted by the created_at property and by default is ordered descending, most recently created first.

Request Parameters

The following optional parameters can be used to request the result page size and which page to fetch.

Parameter	Required	Description
page	no	The page of results to fetch. Defaults to first page
per_page	no	The number of results per page. Defaults to 50, max is 60
order	no	The sort order of the returned contact list. asc or desc. Defaults to desc
order_by	no	The property to sort the fetched results by. Defaults to created_at. Other options: last_seen_at, signed_up_at, updated_at
status	no	Filter by one of the following statuses: live, or paused, or draft. Defaults to all.

Returns: .

The form list contains a pages object that indicates if more forms exist via the next field, whose value is a URL that can be used to fetch the next page. If the next field is not present, that indicates there are no further forms in the list.

Response

A paginated list of Form object.

Example Request

curl --request POST \
  --url https://api.getgist.com/forms/42161287/subscribe \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"fields":{"name":"User", "email":"[email protected]"}, "consent_to_process":"false", "submitted_from":"https://app.getgist.com", "form_id":"42161287"}'

Example Response

{
    "acknowledge_message_header": "Thank you",
    "acknowledge_message": "<p><br></p>",
    "redirect_to_url": "https://www.example.com"
}

You can subscribe a contact to a form by submitting a POST to https://api.getgist.com/forms/{form_id}/subscribe along with the id of the form.

Parameter	Required	Description
id	yes	The id of the form
fields	yes	A list of form names and the values for those fields. Up to 1000 fields can be included.
ip_address	no	The IP address of the visitor filling out the form.
page_title	no	The title of the page the form was submitted on.
page_url	no	The URL of the page the form was submitted on.
submitted_at	no	A UNIX timestamp in milliseconds representing the time the form was submitted.
skip_validation	no	Whether or not to skip validation based on the form settings. Defaults to false.
consent_to_process	no	Whether or not the visitor checked the Consent to process checkbox.
consent_to_process_text	no	The text displayed to the visitor for the Consent to process checkbox.

Note: The name for each field must match the name of the property from the Contact Properties API. Field values should match the format used with the Contacts API.

Response

A Form object.

List all form submissions

Example Request


curl --request GET \
  --url 'https://api.getgist.com/forms/42161287/submissions' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type:application/json'

Example Response

{
    "form_subscriptions": [
        {
            "fields": {
                "name": "User 1",
                "email": "[email protected]",
                "has_consent": "false"
            },
            "ip_address": null,
            "page_url": null,
            "submitted_at": 0,
            "skip_validation": false,
            "consent_to_process": false,
            "consent_to_process_text": "I agree",
            "confirmed_at": "2019-06-26T16:06:36.345Z"
        },
        {
            "fields": {
                "name": "User 2",
                "email": "[email protected]",
                "phone": "123",
                "signup_source": "http://test.com",
                "has_consent": "true"
            },
            "ip_address": null,
            "page_url": null,
            "submitted_at": 0,
            "skip_validation": false,
            "consent_to_process": false,
            "consent_to_process_text": "I agree",
            "confirmed_at": null
        },
        {
            "fields": {
                "email": "[email protected]"
            },
            "ip_address": "0.0.0.0",
            "page_url": "http://www.example.com/",
            "submitted_at": 1559890954,
            "skip_validation": false,
            "consent_to_process": false,
            "consent_to_process_text": "status",
            "confirmed_at": "2019-06-07T07:04:16.888Z"
        },
        {
            "fields": {
                "email": "[email protected]",
            },
            "ip_address": "0.0.0.0",
            "page_url": "http://www.example.com/",
            "submitted_at": 1559890718,
            "skip_validation": false,
            "consent_to_process": false,
            "consent_to_process_text": "status",
            "confirmed_at": "2019-06-07T06:58:59.350Z"
        },
        {
            "fields": {
                "email": "[email protected]",
            },
            "ip_address": "0.0.0.0",
            "page_url": "http://www.example.com/",
            "submitted_at": 1559818627,
            "skip_validation": false,
            "consent_to_process": false,
            "consent_to_process_text": "status",
            "confirmed_at": "2019-06-06T10:57:08.296Z"
        },
        {
            "fields": {
                "email": "[email protected]",
                "test_event": "Test event",
                "age": "123"
            },
            "ip_address": "0.0.0.0",
            "page_url": "http://www.example.com/",
            "submitted_at": 1559302007,
            "skip_validation": false,
            "consent_to_process": false,
            "consent_to_process_text": "status",
            "confirmed_at": "2019-05-31T11:26:48.137Z"
        },
        {
            "fields": {
                "email": "[email protected]",
                "test_event": "Test event",
                "age": "24"
            },
            "ip_address": "0.0.0.0",
            "page_url": "http://www.example.com/",
            "submitted_at": 1559300801,
            "skip_validation": false,
            "consent_to_process": false,
            "consent_to_process_text": "status",
            "confirmed_at": "2019-05-31T11:06:41.355Z"
        },
        {
            "fields": {
                "email": "[email protected]",
                "test_event": "Test event 2"
            },
            "ip_address": "0.0.0.0",
            "page_url": "http://www.example.com/",
            "submitted_at": 1559282368,
            "skip_validation": false,
            "consent_to_process": false,
            "consent_to_process_text": "status",
            "confirmed_at": "2019-05-31T05:59:28.650Z"
        }
    ],
    "page": {
        "first": "https://api.getgist.com/forms/42161287/subscriptions?order=desc&order_by=created_at&page=1&per_page=50",
        "last": "https://api.getgist.com/forms/42161287/subscriptions?order=desc&order_by=created_at&page=1&per_page=50"
    }
}

You can fetch a list of submissions for a form from a Workspace by sending a GET request to https://api.getgist.com/forms/{form_id}/submissions.

Get the submissions for the specified form. This will include the fields in the submissions, the time of the form submission, and the page URL that the form was submitted on. Submissions will be returned in reverse-chronological order.

Request Parameters

The following optional parameters can be used to request the result page size and which page to fetch.

Parameter	Required	Description
page	no	The page of results to fetch. Defaults to first page
per_page	no	The number of results per page. Defaults to 50, max is 60
order	no	The sort order of the returned contact list. asc or desc. Defaults to desc
order_by	no	The property to sort the fetched results by. Defaults to created_at. Other options: last_seen_at, signed_up_at, updated_at
limit	no	The number of results to include in the response. Defaults to 50, supports a maximum of 60.

The form subscriptions list contains a pages object that indicates if more forms exist via the next field, whose value is a URL that can be used to fetch the next page. If the next field is not present, that indicates there are no further form subscriptions in the list.

Response

A paginated list of Form Subscriptions objects.

Campaigns

The campaign object

Example Response

{
    "campaign": {
        "id": 39,
        "status": "live",
        "name": "New Campaign",
        "created_at": 1522334060,
        "updated_at": 1522334060,
        "email_count": 0,
        "active_subscriber_count": 0,
        "unsubscribed_subscriber_count": 0,
        "email_open_rate": 0,
        "email_click_rate": 0,
        "href": "https://app.getgist.com/projects/4rtjrhbh/campaigns/39"
    }
}

A Campaign object describes the campaign and contains the following fields

Property	Type	Description
id	string	The id of the campaign
status	string	The status of the campaign. It can be either draft, paused or live
name	string	The name of the campaign
created_at	timestamp	The time the campaign was created
updated_at	timestamp	The time the campaign was last updated
email_count	integer	The count of emails sent by the campaign
active_subscriber_count	integer	The count of subscribers currently receiving the campaign
unsubscribed_subscriber_count	integer	The count of contacts who unsubscribed from the campaign
email_open_rate	integer	The average open rate of the campaign
email_click_rate	integer	The average click through rate of the campaign
href	string	The unique URL of the campaign
links	object	A link object containing all the links in the campaign

Retrieve a campaign

Example Request

$ curl --request GET \
--url https://api.getgist.com/campaigns/39 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'

Example Response

{
    "campaign": {
        "id": 39,
        "status": "live",
        "name": "New Campaign",
        "created_at": 1522334060,
        "updated_at": 1522334060,
        "email_count": 0,
        "active_subscriber_count": 0,
        "unsubscribed_subscriber_count": 0,
        "email_open_rate": 0,
        "email_click_rate": 0,
        "href": "https://app.getgist.com/projects/4rtjrhbh/campaigns/39"
    }
}

You can fetch a campaign from a Workspace by sending a GET request to https://api.getgist.com/campaigns with campaign_id as the parameter.

Response

A Campaign object.

List all campaigns

Example Request

$ curl --request GET \
--url https://api.getgist.com/campaigns \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'

Example Response

{
    "campaigns": [
        {
            "id": 42,
            "status": "live",
            "name": "New users",
            "created_at": 1538548118,
            "updated_at": 1538548118,
            "email_count": 222,
            "active_subscriber_count": 123,
            "unsubscribed_subscriber_count": 0,
            "email_open_rate": 88.29,
            "email_click_rate": 0.51,
            "href": "https://app.getgist.com/projects/4rtjrhbh/campaigns/42"
        },
        {
            "id": 41,
            "status": "draft",
            "name": "Without Branding",
            "created_at": 1527587937,
            "updated_at": 1527587940,
            "email_count": 0,
            "active_subscriber_count": 17,
            "unsubscribed_subscriber_count": 0,
            "email_open_rate": 0,
            "email_click_rate": 0,
            "href": "https://app.getgist.com/projects/4rtjrhbh/campaigns/41"
        },
        {
            "id": 40,
            "status": "live",
            "name": "Leads",
            "created_at": 1526544400,
            "updated_at": 1526544654,
            "email_count": 7,
            "active_subscriber_count": 1,
            "unsubscribed_subscriber_count": 0,
            "email_open_rate": 100,
            "email_click_rate": 14.29,
            "href": "https://app.getgist.com/projects/4rtjrhbh/campaigns/40"
        },
        {
            "id": 39,
            "status": "live",
            "name": "New Campaign",
            "created_at": 1522334060,
            "updated_at": 1522334060,
            "email_count": 0,
            "active_subscriber_count": 0,
            "unsubscribed_subscriber_count": 0,
            "email_open_rate": 0,
            "email_click_rate": 0,
            "href": "https://app.getgist.com/projects/4rtjrhbh/campaigns/39"
        }
    ],
    "pages": {
        "first": "https://api.getgist.com/campaigns?order=desc&order_by=created_at&page=1&per_page=50",
        "last": "https://api.getgist.com/campaigns?order=desc&order_by=created_at&page=1&per_page=50"
    }
}

You can fetch all campaigns for a Workspace by sending a GET request to https://api.getgist.com/campaigns

Parameter	Required	Description
status	no	Filter by one of the following statuses: draft, active, or paused. Defaults to all.

Response

A paginated list of Campaign objects.

Example Request

{
  "id": 39,
  "user_id": 303,
  "unsubscribed": false,
  "reactivate_if_removed": true,
  "starting_email_index": 1
}

Example Response

{
    "campaign": {
        "id": 39,
        "status": "draft",
        "name": "New Campaign",
        "created_at": 1522334060,
        "updated_at": 1522334060,
        "email_count": 0,
        "active_subscriber_count": 0,
        "unsubscribed_subscriber_count": 0,
        "email_open_rate": 0,
        "email_click_rate": 0,
        "href": "https://app.getgist.com/projects/4rtjrhbh/campaigns/39"
    }
}

You can subscribe a contact to a campaign by submitting a POST to https://api.getgist.com/campaigns along with the id of the campaign.

Parameter	Required	Description
id	yes	The id of the campaign
email	yes	The email address of the subscriber
user_id	yes if no email	Your identifier for the contact
starting_email_index	yes if no user_id	The index of the email to send first. Defaults to 0.
reactivate_if_removed	no	Sending true will force subscribe the contact even if they unsubscribed from the campaign earlier.

Response

A Campaign object.

Unsubscribe a contact from campaign

Example Request

{
  "id": 39,
  "user_id": 303,
  "unsubscribed": true,
}

Example Response

{
    "campaign": {
        "id": 39,
        "status": "draft",
        "name": "New Campaign",
        "created_at": 1522334060,
        "updated_at": 1522334060,
        "email_count": 0,
        "active_subscriber_count": 0,
        "unsubscribed_subscriber_count": 0,
        "email_open_rate": 0,
        "email_click_rate": 0,
        "href": "https://app.getgist.com/projects/4rtjrhbh/campaigns/39"
    }
}

You can unsubscribe a contact from a campaign by submitting a POST to https://api.getgist.com/campaigns along with the id of the campaign.

Parameter	Required	Description
id	yes	The id of the campaign
email	yes	The email address of the subscriber
user_id	yes if no email	Your identifier for the contact

Response

A Campaign object.

Conversations

The conversation object

Example Response

{
  "conversation": {
      "id": 1911149811, // The id representing the conversation
      "created_at": 1539897198, // The time the conversation was created
      "updated_at": 1540393270, // The last time the conversation was updated
      "channel": "chat", // channel the conversation was initiated on.
      "title": "Conversation title", // title of the conversation that is created
      "conversation_identifier": "nmjkgjw6-322acdac-6b3d-17d8-c08e-dd1b6f82cfc3", // conversation url key
      // The contact who is involved in the conversation.
      "contacts": [
          {
           "type": "user",
           "id": 165796,
           "user_id": "1",
           "email": "[email protected]"
      }
      ],
      // List of all teammates that participated (left a response) in the conversation
      "teammates": [
          {
              "id": 814860,
              "name": "Mark Strong",
              "email": "[email protected]"
          }
      ],
      // The teammate the conversation is currently assigned to. Note 'unassigned' indicates the conversation is currently unassigned.
      "assignee": {
          "id": 814860,
          "type": "teammate", // can be team or teammate
                "name": "Mark Strong",
                "email": "[email protected]"
      },
      "open": true, // Indicates whether a conversation is open (true) or closed (false)
      "state": "open", // Can be set to "open", "closed" or "snoozed"
      "read": true, // Indicates whether the last message in conversation has been read by the contact.
      "waiting_since": 64654125776, // The last time a contact responded to a teammate. In other words, the time a contact started waiting for a response. Set to null if last reply is from a teammate.
      "snoozed_until": null, // If set this is the time in the future when this conversation will be marked as open. i.e. it will be in a snoozed state until this time.
      // A list of tags associated with the conversation.
      "tags": {
          "tags": [
             {
                "id": 5,
                "name": "test 3"
             }
          ],
      },
      // List of all available conversation properties in the conversation
      "custom_properties": {
        "user_id": 145,
        "city": "London",
        "last_seen": 1502979465,
        "active": true,
        "fruits": ["Apple", "Orange", "Peach"] // List property
      }
      "priority": "not_priority", // The priority of the conversation. Can be set to "priority" or "not_priority"
      "conversation_rating": {
          "created_at": 1539897198, // indicates the time the rating was first left
          // the contact that gave the rating
          "contact": {
              "id": 1,
              "type": "lead"
          },
          "rating": 5, // The rating, between 1 and 5, for the conversation
          "remark": null, // An optional field to add a remark to correspond to the number rating
          // An object containing the ID and type of the teammate associated with the conversation when it was rated
          "teammate": {
              "id": 814860,
              "name": "Mark Strong",
              "email": "[email protected]"
          }
      },
      "statistics": {
        "first_contact_reply_at": 1539897200,
        "first_assignment_at": 1539897200,
        "first_teammate_reply_at": 1539897200,
        "first_close_at": 1539897200,
        "last_assignment_at": 1539897200,
        "last_assignment_teammate_reply_at": 1539897200,
        "last_contact_reply_at": 1539897200,
        "last_teammate_reply_at": 1539897200,
        "last_close_at": 1539897200,
        "last_closed_by": {
          "id": 325432652,
          "name": "Tom Smith",
          "email": "[email protected]"
        },
        "count_messages": 67
      }
    }
}

Conversations are how you can communicate with your contacts in Gist. A single conversation is a unique thread of messages exchanged between a single Contact and a group of Teammates or a Bot. Each Conversation has a time-ordered set of Messages representing chat messages, internal notes, and metadata events within that conversation.

A new Conversation is created when a contact replies to an outbound message, or when one of your teammates directly sends a message to a single contact.

The message object

Example Response


{
  "message": {
  "message_type": "reply", // whether it is a reply or a note
  "is_inbound": false, // whether the message was received (true) or sent (false)
  "id": 2202737122,
  "conversation_id": 99999999,
  "created_at": 1539897200,
  "updated_at": 1539897200,
  "channel": "Chat", // can also be Email/Facebook/Twitter/API
  "author": {
    "type": "teammmate" // can be bot, contact or teammate
    "id": 815309,
    "email": "[email protected]",
    "first_name": "Leela",
    "last_name": "Turanga",
  },
  "body": "Test_App typically replies in a few hours."
}

A message is a resource which can be either received or sent via an inbox. Messages are grouped by conversations.

A message can be either inbound (received) or outbound (sent). You can know if a message has been received or sent thanks to the boolean is_inbound.

Create a conversation

Example Request

curl --request POST \
  --url https://api.getgist.com/conversations \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "from": {
        "id": "1234"
      },
      "body": "Hello there!",
      "title": "Conversation title",
      "custom_properties": {
        "user_id": 145,
        "city": "London",
        "last_seen": 1502979465,
        "active": true,
        "fruits": ["Apple", "Orange", "Peach"]
      }
}'

You can create a conversation that has been initiated by a contact (ie. user or lead).

POST https://api.getgist.com/conversations

A common use case is creating conversations in Gist that represent activity from other data sources. Enabling Gist to be your one stop shop for contact activity.

Request Parameters

Parameters	Required	Description
from	yes	See From object below for more.
body	yes	The content of the message. HTML is not supported.
title	no	Preferred title for the conversation
custom_properties	no	Preferred conversation properties. Property is created if it's not present already

From object

Parameters	Required	Description
id	one of	The identifier for the contact which is given by Gist.
user_id	one of	The user id you have defined for the contact
email	one of	The email you have defined for the contact

Response

A Conversation object.

Retrieve a conversation

Example Request

curl --request POST \
  --url https://api.getgist.com/conversations/1911149811 \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \

A single conversation can be fetched or looked up individually via their id parameter.

GET https://api.getgist.com/conversations/{conversation_id}

Specify the id of the conversation you wish to retrieve, where {id} is the id field of the conversation.

This will include the time when the conversation was created, the status, the page URL that the conversation was initiated on etc.

Response

A Conversation object.

Update a conversation

Example Request

curl --request PATCH \
  --url https://api.getgist.com/conversations/1911149811 \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "title": "Conversation title",
      "custom_properties": {
        "user_id": 145,
        "city": "London",
        "last_seen": 1502979465,
        "active": true,
        "fruits": ["Apple", "Orange", "Peach"]
      }
    }'

You can assign/update the title of the conversation.

PATCH https://api.getgist.com/conversations/{conversation_id}

Parameter	Required	Description
title	no	Preferred title for the conversation
custom_properties	no	Preferred conversation properties. Property is created if it's not present already

Response

A Conversation object.

Retrieve all messages within a conversation

curl --request GET \
  --url https://api.getgist.com/conversations/1911149811/messages \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \

You can retrieve the messages within a conversation

GET https://api.getgist.com/conversations/{conversation_id}/messages

Messages in the Messages object are ordered by with the most recently created messages appearing at the end of the list.

Parameter	Required	Description
page	no	The page of results to fetch. Defaults to first page
per_page	no	The number of results per page. Defaults to 50, max is 60
with_notes	no	Optional field where the with_notes can either be true or false or absent

Response

A paginated list of Message objects.

Reply to a conversation

Example Request (Reply by Contact)

curl --request POST \
  --url https://api.getgist.com/conversations/1911149811/messages \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "message_type": "reply",
      "from": {
        "type": "contact",
        "user_id": "32193"
      },
      "body": "Hello there!"
}'

Example Request (Reply by Teammate)

curl --request POST \
  --url https://api.getgist.com/conversations/1911149811/messages \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "message_type": "reply",
      "from": {
        "type": "teammate", // "bot" to post a reply or note as a bot
        "teammate_id": "4543534", // not required if "bot"
      },
      "body": "Hello there!"
}'

You can reply to an existing conversation by sending the body of the message as a parameter.

POST https://api.getgist.com/conversations/{conversation_id}/messages

Request Parameters

For a Contact Reply:

Parameter	Required	Description
message_type	yes	Must be ‘reply’
id	one of	The Gist defined id representing the contact
user_id	one of	The user id you have defined for the contact
email	one of	The email you have defined for the contact
body	yes	The text body of the comment.

or for a Teammate Reply:

Parameter	Required	Description
message_type	yes	Must be reply or note
teammate_id	yes	The id of the Teammate who is authoring the comment
body	yes	The text body of the comment. Must be set for reply and note.

Notes are not visible to the end user.

Response

A Message object.

Delete a conversation

A single conversation can be deleted individually by sending the id parameter.

DELETE https://api.getgist.com/conversations/{conversation_id}

Specify the id of the conversation you wish to delete, where {id} is the id field of the conversation.

Response

200 OK

Unassign a conversation

Example Request

curl --request PATCH \
  --url https://api.getgist.com/conversations/1911149811/assign \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "teammate_id": "4543534", // who is assigning
      "assignee_id": null // who it is being assigned to
}'

You can unassign a conversation using this endpoint. You should do this if you do not want the conversation to remain in your own inbox. This will allow other teammates to pick up the conversation when the contact replies to it

PATCH https://api.getgist.com/conversations/{conversation_id}/assign

Just set the assignee_id to ‘null’ when sending the request to un-assign a conversation.

Assign a conversation

Example Request

curl --request PATCH \
  --url https://api.getgist.com/conversations/1911149811/assign \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "teammate_id": "4543534", // who is assigning
      "assignee_id": "3245356" // who it is being assigned to
      "assignee_type": "teammate", // This can either be sent or ignored for assigning to teammate
}'

curl --request PATCH \
  --url https://api.getgist.com/conversations/1911149811/assign \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "teammate_id": "4543534", // who is assigning
      "assignee_id": "1601", // ID of team to who it is being assigned to
      "assignee_type": "team", // For assigning this to team, this params is essential
}'

You can assign a conversation to another teammate.

PATCH https://api.getgist.com/conversations/{conversation_id}/assign

Just use the teammate ID of the teammate you want to assign the conversation to instead of 'null'.

Parameter	Required	Description
teammate_id	yes	Only teammates can assign a conversation so you need to provide the teammate_id
assignee_id	yes	To assign a conversation to team/teammate, this ID is essential. If left blank it will unassign the conversation
assignee_type	no	Value can either be team/teammate. You can ignore this params if you are assigning the conversation to teammate. For teammmate this params is optional. For assigning to the team this is required.

Snooze a conversation

Example Request

curl --request PATCH \
  --url https://api.getgist.com/conversations/1911149811 \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "state": "snoozed",
      // "type": "bot",
      "teammate_id": "4357446", // ID of the teammate who snooozed the conversation
      "snoozed_until":"1543654545"
}'

You can snooze a conversation.

PATCH https://api.getgist.com/conversations/{conversation_id}

Which accepts a JSON object identifying the time you want the conversation snoozed until.

Parameter	Required	Description
type	one of	Mention as "bot" to perform snooze conversation as a bot
teammate_id	one of	The id of the teammate who is performing the snooze action
state	yes	Must be snoozed
snooze_until	yes	The time in Unix time (i.e. seconds) you want the conversation to reopen

Unsnooze a conversation

Example Request

curl --request PATCH \
  --url https://api.getgist.com/conversations/1911149811 \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "state": "open",
      // "type": "bot",
      "teammate_id": "4357446",  // ID of the teammate who opened the conversation
}'

You can unsnooze a conversation.

PATCH https://api.getgist.com/conversations/{conversation_id}

With the state set to ‘open’

Parameter	Required	Description
type	one of	Mention as "bot" to perform unsnooze conversation as a bot
teammate_id	one of	The id of the teammate who is performing the unsnooze action
state	yes	Must be ‘open’ to re-open or unsnooze the conversation

Close a conversation

Example Request

curl --request PATCH \
  --url https://api.getgist.com/conversations/1911149811 \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "state": "closed",
      // "type": "bot",
      "teammate_id": "4357446", // ID of the teammate who closed the conversation
}'

You can close a conversation with or without a reply once you set the message to close: "state":"closed".

PATCH https://api.getgist.com/conversations/{conversation_id}

Prioritize a conversation

Example Request

curl --request PATCH \
  --url https://api.getgist.com/conversations/1911149811/priority \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "teammate_id": "4357446", // ID of the teammate who set the priority
      // "type": "bot",
      "priority": "priority", // The priority of the conversation. Can be set to "priority" or "not_priority"
}'

You can mark a conversation as priority by sending “priority”: “priority” as the body.

PATCH https://api.getgist.com/conversations/{conversation_id}/priority

Retrieve global conversation counts

Example Request

curl --request GET \
  --url https://api.getgist.com/conversations/count \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \

Example Response

{
    "conversation_count": {
        "open": 30,
        "closed": 170,
        "snoozed": 5,
        "unassigned": 5,
        "assigned": 30
    }
}

Attribute	Type	Description
conversation	object	Contains counts related to conversations
conversation.open	number	Contains the number of open conversations
conversation.closed	number	Contains the number of closed conversations
conversation.snoozed	number	Contains the number of snoozed conversations
conversation.unassigned	number	Contains the number of unassigned conversations
conversation.assigned	number	Contains the number of assigned conversations

You may want to occasionally query the total state of conversations in your workspace without having to scroll through the conversation API.

The following endpoint will return a count of conversations by status in the workspace.

GET https://api.getgist.com/conversations/count

Note that each property will be absent if the count is 0. i.e. a response with "conversationCount" : {} indicates no conversations.

Retrieve team conversations counts

Example Request

curl --request GET \
  --url https://api.getgist.com/conversations/count/teams \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \

Example Response

{
    "conversation_count": {
        "teams": [
            {
                "id": 1601,
                "name": "Support team",
                "open": 1,
                "snoozed": 0,
                "closed": 0
            },
            {
                "id": 1,
                "name": "Marketing team",
                "open": 0,
                "snoozed": 1,
                "closed": 1
            }
        ]
    }
}

You can fetch the team ID and name along with the count of the number of conversations assigned to them within your Gist workspace.

GET https://api.getgist.com/conversations/count/teams

Retrieve teammate conversations counts

Example Request

curl --request GET \
  --url https://api.getgist.com/conversations/count/teammates \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \

Example Response

{
    "conversation_count": {
        "teammates": [
            {
                "id": 603,
                "name": "Jitta",
                "open": 4,
                "snoozed": 0,
                "closed": 1
            },
            {
                "id": 297,
                "name": "Indrani",
                "open": 4,
                "snoozed": 0,
                "closed": 1
            },
            {
                "id": 654,
                "name": "Ruchi",
                "open": 4,
                "snoozed": 0,
                "closed": 1
            }
        ]
    }
}

You can fetch the teammate ID and name along with the count of the number of conversations assigned to them within your Gist workspace.

GET https://api.getgist.com/conversations/count/teammates

Tag a conversation

Example request

curl --request POST \
  --url https://api.getgist.com/conversations/1911149811/tags \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "message_id": 4352, // optional. Tag will be applied to last message of conversation if id not provided
  "tags": "bug, sales" // comma separated values
  }'

You can apply a tag to the conversation

POST https://api.getgist.com/conversations/{conversation_id}/tags

Property	Type	Description
message_id	integer	The id of the message to which tag is to be applied
tags	string	Comma separated values of tags to be applied

Untag a conversation

Example request

curl --request DELETE \
  --url https://api.getgist.com/conversations/1911149811/tags \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "message_id": 4352, // optional. Tag will be removed from all messages of conversation if id not provided
  "tag_id": 1224
  }'

You can remove the tag from a conversation

DELETE https://api.getgist.com/conversations/{conversation_id}/tags

Property	Type	Description
message_id	integer	The id of the message from which tag is to be removed
tag_id	integer	The id of the tag to be removed

List all conversations

Example Request

curl --request GET \
  --url https://api.getgist.com/conversations?order=desc&order_by=updated_at \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \

You can fetch a list of all conversations.

GET https://api.getgist.com/conversations?order=desc&order_by=updated_at

order can be asc or desc

status can be all, open, closed, snoozed

order_by can be created_at, updated_at or waiting_longest

page value can be 1,2,3.. ete depending on the page number required

Default values:

order = desc

status = all

order_by = updated_at

page = 1

Each conversation has a type depending on the channel it has been sent with:

Type	Description
`chat`	Chat message
`email`	Email message
`tweet_dm`	Direct Message from Twitter
`facebook`	Message from Facebook

Response

A paginated list of Conversation objects.

Search conversations

Example Request

curl --request POST \
  --url https://api.getgist.com/conversations/search?order=desc&order_by=updated_at \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter_query": [
    {
      "criteria": [
        {
          "key": "contact.id",
          "operator": "=",
          "value": 165796
        },
        {
          "key": "teammate_assigned_id",
          "operator": "IN",
          "value": [7652, 9098]
        }
      ]
    },
    {
      "criteria": [
        {
          "key": "channel",
          "operator": "NIN",
          "value": ["email", "facebook"]
        }
      ]
    }
]}'

You can search conversations by passing a search query to conversation search endpoint.

POST https://api.getgist.com/conversations/search?order=desc&order_by=updated_at

order can be asc or desc

status can be all, open, closed, snoozed

order_by can be created_at, updated_at or waiting_longest

page value can be 1,2,3.. ete depending on the page number required

Default values:

order = desc

status = all

order_by = updated_at

page = 1

Query Basics

To search for conversations, you specify the search query in the body of the request named filter_query. To understand how the search query is built, you will need to learn about conditions and criteria.

Condition

It is the smallest unit of the query that is made up of key, operator and value.

Parameter	Description
key	A property associated with the conversation that you can search for. See below for the supported keys.
operator	Indicates the type of operation that needs to be performed. See below for supported operators
value	Indicates the text or id or an array you want to search by.

Example

{ "key": "teammate_assigned_id", "operator": "IN", "value": [7652, 9098] }

Criteria

It is a collection of multiple conditions combined with an OR logic.

Filter Query

It is a collection of multiple criteria combined with AND logic.

Supported keys

Key	Type	Description
teammate_assigned_id	Integer	The id of the teammate assigned to the conversations.
team_assigned_id	Integer	The id of the team assigned to the conversations.
is_assigned	Boolean	Indicates whether the conversations are assigned (true) or unassigned (false).
channel	String	The channel the conversations were initiated on. Accepted values are `Email`, `Chat`, `Facebook`, `Twitter` & `API`.
conversation_tags	Integer	The id of the tag associated with the conversations.
contact.id	Integer	The id of the contact involved in the conversations.

Operators

Operator	Valid Types	Description
=	All	Equals
IN	All	IN Values must be an array
NIN	All	NOT IN Values must be an array

Response

A paginated list of Conversation objects.

Teams

The team object

Example Response

{
    "id": 814865,
    "name": "Support Team",
    "teammate_ids": [
        34355
    ]
}

Teams are groups of teammates in Gist.

Property	Type	Description
id	string	The id of the team
name	string	The name of the team
teammate_ids	object	A list of teammate ids that are part of the team

Retrieve a team

Example Request

curl --request GET \
  --url https://api.getgist.com/teams/4356 \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \

You can fetch the details of a single team.

GET https://api.getgist.com/teams/{team_id}

Response

A Team object.

List all teams

Example Request

curl --request GET \
  --url https://api.getgist.com/teams \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \

You can fetch the details of all teams within your Gist workspace.

GET https://api.getgist.com/teams

*Returns: *

Response

A paginated list of Teams objects.

Teammates

The teammate object

Example Response

{
    "id": 7652,
    "name": "John Doe",
    "email": "[email protected]",
    "avatar": "https://d258lu9myqkejp.cloudfront.net/users_profiles/3/medium/jittarao.jpg?1588261838",
    "agent_status": "online",
    "last_active_on": "2020-10-08T13:05:38.022Z",
    "away_mode_enabled": false,
    "team_ids": [
        1
     ],
    "has_inbox_seat": true
}

Teammates are people in your organization who have a registered Gist account and have access to your workspace.

Property	Type	Description
id	string	The id of the teammate
name	string	The name of the teammate
email	string	The email of the teammate
avatar	string	URL where the user's profile image is saved
agent_status	string	status of the user. whether online, away or offline based on their last seen
last_active_on	DateTime	The time with which the user has made last web activity irrespective of the away mode.
away_mode_enabled	boolean	Whether the teammate is currently set in away more or not.
has_inbox_seat	boolean	Whether the teammate has a paid inbox seat or not
team_ids	object	A list of team ids the teammate is a part of

Retrieve a teammate

Example Request

curl --request GET \
  --url https://api.getgist.com/teammates/ \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "teammate_id": "493881", // one of these
    "email": "[email protected]", // one of these
}'

You can fetch the details of a single teammate.

GET https://api.getgist.com/teammates/{teammate_id}

You can send either the teammate_id or the email of the teammate to fetch their details.

Response

A Teammate object.

Retrieve a list of Teammates

Example Request

curl --request GET \
  --url https://api.getgist.com/teammates \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \

You can fetch the details of all teammates within your Gist workspace.

GET https://api.getgist.com/teammates/

Response

A paginated list of Teammates objects.

Webhooks

In Gist with the help of webhooks, we will provide you with real-time information immediately. If any changes happen in the website like a user filled a form or had a conversation with an agent, each and every information will be delivered to you as it happens. This makes the process more efficient, unlike other APIs where you need to call for data very frequently in order to get it real-time.

Webhooks are available on our Premium plans.

Setup webhooks

Navigate to Settings > API > Webhooks page.
Click “New Webhook” button
Enter a name, endpoint URL
Choose the topic and request headers and body
Set it live

Supported topics

You can retrieve the data in JSON format. Webhooks are available for the following topics

Topic	Description
User Created	When a new user gets created
Lead Created	When a new lead gets created
User Deleted	When a existing user is deleted
Lead Deleted	When a existing lead is deleted
Contact Tagged	When a contact gets tagged
Contact Untagged	When a contact gets untagged
Custom Attribute Updated	When a custom attribute is updated
Contact Email Updated	When the contact email is updated
Contact Unsubscribed Emails	When a contact unsubscribed emails
Contact Initiated Conversation	When we receive a new message from a contact
Conversation Assigned	When a conversation gets assigned to a teammate
Conversation Opened	When a conversation is opened
Conversation Closed	When a conversation is closed
Conversation Rating	When a conversation is rated by a contact
Message From Contact	When a contact send a message in chat
Teammate Replied	When a teammate replied in chat
Note Added	When a teammate add a note to the conversation
Contact Subscribed Campaign	When the contact subscribed for a campaign
Contact Unsubscribed Campaign	When the contact unsubscribed for a campaign
New Page Visit	When there is a new page visit
Contact Performed Event	When a contact performed an event
Lead Submitted Email	When a lead submits an Email
Event Created	When a event is created
Contact Submitted Form	When a contact submits a form
Meeting Scheduled	When a meeting is scheduled
Meeting Cancelled	When a meeting is cancelled
Meeting Rescheduled	When a meeting is rescheduled

Handling Notification

When you setup a subscription you will receive notifications on your chosen topics. How you handle those notifications, i.e. the HTTP status code returned, will determine the subsequent state of that subscription. Please see below for a list of how a subscription will respond to these status codes

Response Code	Description	Action
2XX	Success	Timeout in 10 seconds
410	Gone- Resource no longer available	The webhook will be disabled
4XX*, 5XX	Client or service error	1st retry in 1 Hour. 2nd retry in 3 Hours. 3rd retry in 6 Hours. 4th retry in 24 Hours

Note: Retry interval is relative to original attempt.

*Excluding 410

Webhook data

User Created

User created webhook will trigger when an user is created with Gist. We can be identified the user created webhook by "event_type":"user_created" and the created user as "user" with "type":"user" in request parameter of webhook post request to endpoint URL.

User Created

{
   "event_type": "user_created",
   "contact" {
     "type": "user",
     "id": 297267,
     "name": Example,
     "email": "[email protected]",
     "user_id": 1234,
     "phone": 9999999999,
     "created_at": 1542699961,
     "signed_up_at": 1542700022,
     "last_seen_at": 1542700022,
     "last_contacted_at": null,
     "updated_at": 1542700022,
     "session_count": 1,
     "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
     "landing_url": "getgist.com",
     "original_referrer": "",
     "last_seen_ip": null,
     "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
     "location_data": {
       "city_name": null,
       "region_name": null,
       "country_name": null,
       "country_code": null,
       "continent_name": null,
       "continent_code": null,
       "latitude": null,
       "longitude": null,
       "postal_code": null,
       "time_zone": null,
       "utc_offset": null
     },
     "segments": [],
     "tags": [],
     "social_profiles": [],
     "custom_properties": {
       "facebook": null
     },
     "unsubscribed_from_emails": "false"
   }
 }

Lead Created

Lead created webhook will trigger when a lead is created with Gist. We can be identified the lead created webhook by "event_type":"lead_created" and the created user as "user" with "type":"lead" in request parameter of webhook post request to endpoint URL.

Lead Created

{
   "event_type": "lead_created",
   "contact" {
     "type": "lead",
     "id": 297267,
     "name": null,
     "email": "[email protected]",
     "user_id": null,
     "phone": null,
     "created_at": 1542699961,
     "signed_up_at": 1542700022,
     "last_seen_at": 1542700022,
     "last_contacted_at": null,
     "updated_at": 1542700022,
     "session_count": 1,
     "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
     "landing_url": "getgist.com",
     "original_referrer": "",
     "last_seen_ip": null,
     "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
     "location_data": {
       "city_name": null,
       "region_name": null,
       "country_name": null,
       "country_code": null,
       "continent_name": null,
       "continent_code": null,
       "latitude": null,
       "longitude": null,
       "postal_code": null,
       "time_zone": null,
       "utc_offset": null
     },
     "segments": [],
     "tags": [],
     "social_profiles": [],
     "custom_properties": {
       "facebook": null
     },
     "unsubscribed_from_emails": "false"
   }
 }

User Deleted

User deleted webhook will trigger when an user is deleted in Gist. We can be identified the user deleted webhook by "event_type":"user_deleted" and the deleted user as "user" with "type":"user" in request parameter of webhook post request to endpoint URL.

User Deleted

{
  "event_type": "delete_lead",
  "contact" {
    "type": "lead",
    "id": 297265,
    "name": Example,
    "email": [email protected],
    "user_id": 1234,
    "phone": 9999999999,
    "created_at": 1542698541,
    "signed_up_at": null,
    "last_seen_at": 1542698541,
    "last_contacted_at": null,
    "updated_at": 1542698578,
    "session_count": 1,
    "avatar": "https://avatar.tobi.sh/unknown?size=120u0026type=svgu0026text=SI",
    "landing_url": "getgist.com",
    "original_referrer": "",
    "last_seen_ip": null,
    "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
    "location_data": {
      "city_name": null,
      "region_name": null,
      "country_name": null,
      "country_code": null,
      "continent_name": null,
      "continent_code": null,
      "latitude": null,
      "longitude": null,
      "postal_code": null,
      "time_zone": null,
      "utc_offset": null
    },
    "segments": [],
    "tags": [],
    "social_profiles": [],
    "custom_properties": {
      "facebook": null
    },
    "unsubscribed_from_emails": null
  }
}

Lead Deleted

Lead deleted webhook will trigger when a lead is deleted in Gist. We can be identified the lead deleted webhook by "event_type":"lead_deleted" and the deleted lead as "user" with "type":"lead" in request parameter of webhook post request to endpoint URL.

Lead Deleted

{
  "event_type": "delete_lead",
  "contact" {
    "type": "lead",
    "id": 297265,
    "name": null,
    "email": [email protected],
    "user_id": null,
    "phone": null,
    "created_at": 1542698541,
    "signed_up_at": null,
    "last_seen_at": 1542698541,
    "last_contacted_at": null,
    "updated_at": 1542698578,
    "session_count": 1,
    "avatar": "https://avatar.tobi.sh/unknown?size=120u0026type=svgu0026text=SI",
    "landing_url": "getgist.com",
    "original_referrer": "",
    "last_seen_ip": null,
    "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
    "location_data": {
      "city_name": null,
      "region_name": null,
      "country_name": null,
      "country_code": null,
      "continent_name": null,
      "continent_code": null,
      "latitude": null,
      "longitude": null,
      "postal_code": null,
      "time_zone": null,
      "utc_offset": null
    },
    "segments": [],
    "tags": [],
    "social_profiles": [],
    "custom_properties": {
      "facebook": null
    },
    "unsubscribed_from_emails": null
  }
}

Contact Tagged

Contact tagged webhook will trigger when a contact(lead/user) is tagged in Gist. We can be identified the contact tagged webhook by "event_type":"contact_tagged" and the added tag as "added_tag" in request parameter of webhook post request to endpoint URL.

Contact Tagged

{
  "event_type": "contact_tagged",
  "contact" {
    "type": "lead",
    "id": 297266,
    "name": null,
    "email": "[email protected]",
    "user_id": null,
    "phone": null,
    "created_at": 1542699599,
    "signed_up_at": 1542699634,
    "last_seen_at": 1542699634,
    "last_contacted_at": null,
    "updated_at": 1542699634,
    "session_count": 1,
    "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=EX",
    "landing_url": "lvh.me",
    "original_referrer": "",
    "last_seen_ip": null,
    "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
    "location_data": {
      "city_name": null,
      "region_name": null,
      "country_name": null,
      "country_code": null,
      "continent_name": null,
      "continent_code": null,
      "latitude": null,
      "longitude": null,
      "postal_code": null,
      "time_zone": null,
      "utc_offset": null
    },
    "segments": [],
    "tags": [
      {
        "id": 320,
        "name": "webhook"
      }
    ],
    "social_profiles": [],
    "custom_properties": {
      "facebook": null
    },
    "unsubscribed_from_emails": "false",
    "added_tag": {
      "id": 320,
      "name": "webhook"
    }
  }
}

Contact Untagged

Contact untagged webhook will trigger when a contact(lead/user) is untagged in Gist. We can be identified the contact untagged webhook by "event_type":"contact_untagged" and the removed tag as "removed_tag" in request parameter of webhook post request to endpoint URL.

Contact Untagged

{
  "event_type": "contact_untagged",
  "contact" {
    "type": "lead",
    "id": 297266,
    "name": null,
    "email": "[email protected]",
    "user_id": null,
    "phone": null,
    "created_at": 1542699599,
    "signed_up_at": 1542699634,
    "last_seen_at": 1542699634,
    "last_contacted_at": null,
    "updated_at": 1542699634,
    "session_count": 1,
    "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=EX",
    "landing_url": "lvh.me",
    "original_referrer": "",
    "last_seen_ip": null,
    "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
    "location_data": {
      "city_name": null,
      "region_name": null,
      "country_name": null,
      "country_code": null,
      "continent_name": null,
      "continent_code": null,
      "latitude": null,
      "longitude": null,
      "postal_code": null,
      "time_zone": null,
      "utc_offset": null
    },
    "segments": [],
    "tags": [
      {
        "id": 330,
        "name": "eduction"
      }
    ],
    "social_profiles": [],
    "custom_properties": {
      "facebook": null
    },
    "unsubscribed_from_emails": "false",
    "removed_tag": {
      "id": 320,
      "name": "webhook"
    }
  }
}

Custom Attribute Updated

Custom Attribute Updated webhook will trigger when the custom attribute of a contact(lead/user) is updated in Gist. We can be identified the custom attribute updated webhook by "event_type":"custom_attribute_updated" and the updated custom attributes in "custom_properties" in request parameter of webhook post request to endpoint URL.

Custom Attribute Updated

{
   "event_type": "user_created",
   "contact" {
     "type": "user",
     "id": 297267,
     "name": Example,
     "email": "[email protected]",
     "user_id": 1234,
     "phone": 9999999999,
     "created_at": 1542699961,
     "signed_up_at": 1542700022,
     "last_seen_at": 1542700022,
     "last_contacted_at": null,
     "updated_at": 1542700022,
     "session_count": 1,
     "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
     "landing_url": "facebook.com",
     "original_referrer": "",
     "last_seen_ip": null,
     "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
     "location_data": {
       "city_name": null,
       "region_name": null,
       "country_name": null,
       "country_code": null,
       "continent_name": null,
       "continent_code": null,
       "latitude": null,
       "longitude": null,
       "postal_code": null,
       "time_zone": null,
       "utc_offset": null
     },
     "segments": [],
     "tags": [],
     "social_profiles": [],
     "custom_properties": {
       "facebook": true,
       "twitter": false
     },
     "unsubscribed_from_emails": "false"
   }
 }

Contact Email Updated

Contact email updated webhook will trigger when the email of a contact(lead/user) is updated in Gist. We can be identified the Contact email updated webhook by "event_type":"contact_email_updated" and the updated email in "email" of "user" in request parameter of webhook post request to endpoint URL.

Contact Email Updated

{
   "event_type": "contact_email_updated",
   "contact" {
     "type": "user",
     "id": 297267,
     "name": Example,
     "email": "[email protected]",
     "user_id": 1234,
     "phone": 9999999999,
     "created_at": 1542699961,
     "signed_up_at": 1542700022,
     "last_seen_at": 1542700022,
     "last_contacted_at": null,
     "updated_at": 1542700022,
     "session_count": 1,
     "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
     "landing_url": "getgist.com",
     "original_referrer": "",
     "last_seen_ip": null,
     "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
     "location_data": {
       "city_name": null,
       "region_name": null,
       "country_name": null,
       "country_code": null,
       "continent_name": null,
       "continent_code": null,
       "latitude": null,
       "longitude": null,
       "postal_code": null,
       "time_zone": null,
       "utc_offset": null
     },
     "segments": [],
     "tags": [],
     "social_profiles": [],
     "custom_properties": {
       "facebook": null
     },
     "unsubscribed_from_emails": "false"
   }
 }

Contact Unsubscribed Emails

Contact unsubscribed emails webhook will trigger when the contact(lead/user) is unsubscribed from emails in Gist. We can be identified the Contact unsubscribed emails webhook by "event_type":"contact_unsubscribed_email" and the contact unsubscribed emails in "unsubscribed_from_emails" of "user" in request parameter of webhook post request to endpoint URL.

Contact Unsubscribed Emails

{
   "event_type": "contact_unsubscribed_emails",
   "contact" {
     "type": "user",
     "id": 297267,
     "name": Example,
     "email": "[email protected]",
     "user_id": 1234,
     "phone": 9999999999,
     "created_at": 1542699961,
     "signed_up_at": 1542700022,
     "last_seen_at": 1542700022,
     "last_contacted_at": null,
     "updated_at": 1542700022,
     "session_count": 1,
     "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
     "landing_url": "getgist.com",
     "original_referrer": "",
     "last_seen_ip": null,
     "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
     "location_data": {
       "city_name": null,
       "region_name": null,
       "country_name": null,
       "country_code": null,
       "continent_name": null,
       "continent_code": null,
       "latitude": null,
       "longitude": null,
       "postal_code": null,
       "time_zone": null,
       "utc_offset": null
     },
     "segments": [],
     "tags": [],
     "social_profiles": [],
     "custom_properties": {
       "facebook": null
     },
     "unsubscribed_from_emails": "true"
   }
 }

Contact Initiated Conversation

Contact initiated conversation webhook will trigger when the contact(lead/user) started a new chat in Gist. We can be identified the Contact initiated conversation webhook by "event_type":"contact_initiated_conversation" and the contact initiated conversation as "conversation" in request parameter of webhook post request to endpoint URL.

Contact Initiated Conversation

{
  "event_type": "contact_initiated_conversation",
  "conversation": {
    "id": 13859,
    "channel": "Chat",
    "state": "open",
    "title": "Conversation title",
    "contact": {
      "type": "user",
      "id": 13450,
      "user_id": "13450",
      "email": "[email protected]"
    },
    "assignee": {
      "type": "teammate",
      "id": 158,
      "name": "Example",
      "email": "[email protected]",
     }
  }
}

Conversation Assigned

Conversation assigned webhook will trigger when the conversation is assigned to some agent/team in Gist. We can be identified the conversation assigned webhook by "event_type":"conversation_assigned" and the agent/team to whom the conversation assigned in "assignee" of "conversation" in request parameter of webhook post request to endpoint URL.

Conversation Assigned

{
  "event_type": "conversation_assigned",
   "conversation": {
      "id": 13859,
      "channel": "Chat",
      "state": "open",
      "title": "Conversation title",
      "contact": {
        "type": "user",
        "id": 13450,
        "user_id": "13450",
        "email": "[email protected]"
      },
      "assignee": {
        "type": "teammate",
        "id": 158,
        "name": "Example",
        "email": "[email protected]",
       }
    }
}

Conversation Opened

Conversation opened webhook will trigger when the conversation is opened in Gist. We can be identified the conversation opened webhook by "event_type":"conversation_opened" and the conversation opened with "state" of "conversation" in request parameter of webhook post request to endpoint URL.

Conversation Opened

{
  "event_type": "conversation_opened",
   "conversation": {
      "id": 13859,
      "channel": "Chat",
      "state": "open",
      "title": "Conversation title",
      "contact": {
        "type": "user",
        "id": 13450,
        "user_id": "13450",
        "email": "[email protected]"
      },
      "assignee": {
        "type": "teammate",
        "id": 158,
        "name": "Example",
        "email": "[email protected]",
       }
    }
}

Conversation Closed

Conversation closed webhook will trigger when the conversation is closed in Gist. We can be identified the conversation closed webhook by "event_type":"conversation_closed" and the conversation closed with "state" of "conversation" in request parameter of webhook post request to endpoint URL.

Conversation Closed

{
  "event_type": "conversation_closed",
   "conversation": {
      "id": 13859,
      "channel": "Chat",
      "state": "open",
      "title": "Conversation title",
      "contact": {
        "type": "user",
        "id": 13450,
        "user_id": "13450",
        "email": "[email protected]"
      },
      "assignee": {
        "type": "teammate",
        "id": 158,
        "name": "Example",
        "email": "[email protected]",
       }
    }
}

Conversation Rating

A conversation rating contains information related to a customer's satisfaction with their interaction with your team. For more info on conversation ratings please see here

Conversation rating

{
  "event_type": "conversation_rating",
   "conversation": {
      "id": 13859,
      "channel": "Chat",
      "state": "open",
      "title": "Conversation title",
      "contact": {
        "type": "lead",
        "id": 129243610,
        "user_id": "nil",
        "email": "[email protected]"
      },
      "assignee": {
        "type": "teammate",
        "id": 138,
        "name": "John",
        "email"=>"[email protected]"
       },
      "conversation_rating": {
         "rating": 5,
         "remark": "Good",
         "created_at": 1590542572,
         "contact": {
            "id": 129243610
         },
         "teammate": {
         "id": 138,
         "name": "John",
         "email": "[email protected]"
         }
      }
    }
}

The conversation rating object

Property	Type	Description
rating	integer	The rating is between 1 and 5 for the conversation
remark	string	An optional field to add a remark to correspond to the number rating
created_at	timestamp	The time the conversation that is being rated was created
contact	Contact object	An object containing the ID and type of the customer (e.g. it could be a user or lead)
agent	User object	An object containing the ID the teammate finally replied to the conversation

Message From Contact

Message from contact webhook will trigger when the contact(lead/user) send a message to a conversation in Gist. We can be identified the message from contact webhook by "event_type":"message_from_contact", the message from contact as "message" and the contact "author" object with type 'contact' in request parameter of webhook post request to endpoint URL.

Contact Replied

{
  "event_type": "message_from_contact",
  "message": {
     "message_type": "reply",
     "is_inbound": true,
     "id": 25137,
     "conversation_id": 13832,
     "body": "Hi there",
     "channel": "Chat", // can also be Email/Facebook/Twitter/API
     "created_at": 1585112120,
     "updated_at": 1585112120,
     "author": {
        "type": "contact",
        "id": 324124,
        "email": "[email protected]",
        "first_name": "Smith",
        "last_name": "Jardon"
     }
  }
}

Teammate Replied

Teammate replied webhook will trigger when the teammate replied for a conversation in Gist. We can be identified the teammate replied webhook by "event_type":"teammate_replied", the teammate replied message as "message" and the teammate as "author" object with type 'teammate' in request parameter of webhook post request to endpoint URL.

Teammate Replied

{
  "event_type": "teammate_replied",
     "message": {
        "message_type": "reply",
        "is_inbound": true,
        "id": 25137,
        "conversation_id": 13832,
        "created_at": 1585112120,
        "updated_at": 1585112120,
        "channel": "Chat", // can also be Email/Facebook/Twitter/API
        "author": {
           "type": "teammate",
            "id": 324124,
           "email": "[email protected]",
           "first_name": "Christopher",
           "last_name": "Syre"
       }
    }
  }

Note Added

Note added webhook will trigger when the teammate added a note in a conversation in Gist. We can be identified the note added webhook by "event_type":"note_added", the note message as "message" and the teammate as "agent" in request parameter of webhook post request to endpoint URL.

Note Added

{
  "event_type": "note_added",
  "message": {
     "message_type": "note",
     "is_inbound": false,
     "id": 25137,
     "conversation_id": 13832,
     "body": "@Smith - Can you please check this?&amp;nbsp;",
     "channel": "Chat", // can also be Email/Facebook/Twitter/API
     "created_at": 1585112120,
     "updated_at": 1585112120,
     "author": {
        "type": "teammate",
        "id": 324124,
        "email": "[email protected]",
        "first_name": "Christopher",
        "last_name": "Syre"
        }
     }
  }
}

Contact Subscribed Campaign

Contact subscribed campaign webhook will trigger when the contact(lead/user) subscribed to a campaign in Gist. We can be identified the contact subscribed campaign webhook by "event_type":"contact_subscribed_campaign" and the subscribed campaign in "campaign" of "user" in request parameter of webhook post request to endpoint URL.

Contact Subscribed Campaign

{
  "event_type": "contact_subscribed_campaign",
  "contact" {
    "type": "lead",
    "id": 297268,
    "name": "Test",
    "email": "[email protected]",
    "user_id": null,
    "phone": null,
    "created_at": 1542700926,
    "signed_up_at": 1542700956,
    "last_seen_at": 1542700956,
    "last_contacted_at": null,
    "updated_at": 1542700956,
    "session_count": 1,
    "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
    "landing_url": null,
    "original_referrer": null,
    "last_seen_ip": null,
    "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
    "location_data": {
      "city_name": null,
      "region_name": null,
      "country_name": null,
      "country_code": null,
      "continent_name": null,
      "continent_code": null,
      "latitude": null,
      "longitude": null,
      "postal_code": null,
      "time_zone": null,
      "utc_offset": null
    },
    "segments": [
      {
        "id": 599,
        "name": "All Users",
        "created_at": 1524656926,
        "updated_at": 1542700957
      }
    ],
    "tags": [],
    "social_profiles": [],
    "custom_properties": {
      "facebook": null
    },
    "unsubscribed_from_emails": "false",
    "campaign": {
      "id": 32,
      "status": "live",
      "name": "Test campaign",
      "created_at": 1528963438,
      "updated_at": 1542701276,
      "email_count": 1,
      "active_subscriber_count": 4,
      "unsubscribed_subscriber_count": 0,
      "email_open_rate": 0,
      "email_click_rate": 0,
      "href": "https://app.getgist.com/projects/gg94simq/campaigns/32"
    }
  }
}

Contact Unsubscribed Campaign

Contact unsubscribed campaign webhook will trigger when the contact(lead/user) unsubscribed to a campaign in Gist. We can be identified the contact unsubscribed campaign webhook by "event_type":"contact_unsubscribed_campaign" and the unsubscribed campaign in "campaign" of "user" in request parameter of webhook post request to endpoint URL.

Contact Unsubscribed Campaign

{
  "event_type": "contact_unsubscribed_campaign",
  "contact" {
    "type": "lead",
    "id": 297268,
    "name": "Test",
    "email": "[email protected]",
    "user_id": null,
    "phone": null,
    "created_at": 1542700926,
    "signed_up_at": 1542700956,
    "last_seen_at": 1542700956,
    "last_contacted_at": null,
    "updated_at": 1542700956,
    "session_count": 1,
    "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
    "landing_url": null,
    "original_referrer": null,
    "last_seen_ip": null,
    "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
    "location_data": {
      "city_name": null,
      "region_name": null,
      "country_name": null,
      "country_code": null,
      "continent_name": null,
      "continent_code": null,
      "latitude": null,
      "longitude": null,
      "postal_code": null,
      "time_zone": null,
      "utc_offset": null
    },
    "segments": [
      {
        "id": 599,
        "name": "All Users",
        "created_at": 1524656926,
        "updated_at": 1542700957
      }
    ],
    "tags": [],
    "social_profiles": [],
    "custom_properties": {
      "facebook": null
    },
    "unsubscribed_from_emails": "false",
    "campaign": {
      "id": 32,
      "status": "live",
      "name": "Test campaign",
      "created_at": 1528963438,
      "updated_at": 1542701276,
      "email_count": 1,
      "active_subscriber_count": 4,
      "unsubscribed_subscriber_count": 0,
      "email_open_rate": 0,
      "email_click_rate": 0,
      "href": "https://app.getgist.com/projects/gg94simq/campaigns/32"
    }
  }
}

Contact Performed Event

Contact performed event webhook will trigger when the contact(lead/user) performed a defined event in Gist. We can be identified the contact performed event webhook by "event_type":"contact_performed_event" and the performed event as "event" of "user" in request parameter of webhook post request to endpoint URL.

Contact Performed Event

{
  "event_type": "contact_performed_event",
  "contact" {
    "type": "lead",
    "id": 297276,
    "name": null,
    "email": "[email protected]",
    "user_id": null,
    "phone": null,
    "created_at": 1544075170,
    "signed_up_at": 1544075441,
    "last_seen_at": 1544079362,
    "last_contacted_at": null,
    "updated_at": 1544079362,
    "session_count": 2,
    "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
    "landing_url": "localhost",
    "original_referrer": "",
    "last_seen_ip": null,
    "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36",
    "location_data": {
      "city_name": null,
      "region_name": null,
      "country_name": null,
      "country_code": null,
      "continent_name": null,
      "continent_code": null,
      "latitude": null,
      "longitude": null,
      "postal_code": null,
      "time_zone": null,
      "utc_offset": null
    },
    "segments": [
      {
        "id": 599,
        "name": "All Users",
        "created_at": 1524656926,
        "updated_at": 1544075441
      }
    ],
    "tags": [],
    "social_profiles": [],
    "custom_properties": {
      "facebook": null
    },
    "unsubscribed_from_emails": "false",
    "event": {
        "id": 297276,
        "user_id": null,
        "email": "[email protected]",
        "name": "Event Name",
        "properties": {
          "tag": "",
          "type": "",
          "id": "",
          "class": "",
          "href": "",
          "linkText": "",
          "action": "",
          "title": "Helloworld",
          "method": ""
        },
        "occurred_at": 1544079788
      }
  }
}

Lead Submitted Email

Lead submitted email webhook will trigger when the lead submitted email in Gist. We can be identified the lead submitted email webhook by "event_type":"lead_submitted_email" and the submitted email in "email" of "user" in request parameter of webhook post request to endpoint URL.

Lead Submitted Email

{
  "event_type": "lead_submitted_email",
  "contact" {
    "type": "lead",
    "id": 297267,
    "name": null,
    "email": "[email protected]",
    "user_id": null,
    "phone": null,
    "created_at": 1542699961,
    "signed_up_at": 1542700022,
    "last_seen_at": 1542700022,
    "last_contacted_at": null,
    "updated_at": 1542700022,
    "session_count": 1,
    "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
    "landing_url": "getgist.com",
    "original_referrer": "",
    "last_seen_ip": null,
    "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
    "location_data": {
      "city_name": null,
      "region_name": null,
      "country_name": null,
      "country_code": null,
      "continent_name": null,
      "continent_code": null,
      "latitude": null,
      "longitude": null,
      "postal_code": null,
      "time_zone": null,
      "utc_offset": null
    },
    "segments": [
      {
        "id": 599,
        "name": "All Users",
        "created_at": 1524656926,
        "updated_at": 1542700023
      }
    ],
    "tags": [],
    "social_profiles": [],
    "custom_properties": {
      "facebook": null
    },
    "unsubscribed_from_emails": "false"
  }
}

Contact Submitted Form

Contact submitted form webhook will trigger when the contact submitted a form in Gist, based on optin method of submitted form. We can be identified the contact submitted form webhook by "event_type":"contact_submitted_form" and the submitted form in "submitted_form" of "user" in request parameter of webhook post request to endpoint URL.

Contact Submitted Form

{
  "event_type": “contact_submitted_form”,
  "contact" {
    "type": "lead",
    "id": 297268,
    "name": "Test",
    "email": "[email protected]",
    "user_id": null,
    "phone": null,
    "created_at": 1542700926,
    "signed_up_at": 1542700956,
    "last_seen_at": 1542700956,
    "last_contacted_at": null,
    "updated_at": 1542700956,
    "session_count": 1,
    "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
    "landing_url": null,
    "original_referrer": null,
    "last_seen_ip": null,
    "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
    "location_data": {
      "city_name": null,
      "region_name": null,
      "country_name": null,
      "country_code": null,
      "continent_name": null,
      "continent_code": null,
      "latitude": null,
      "longitude": null,
      "postal_code": null,
      "time_zone": null,
      "utc_offset": null
    },
    "segments": [
      {
        "id": 599,
        "name": "All Users",
        "created_at": 1524656926,
        "updated_at": 1542700957
      }
    ],
    "tags": [],
    "social_profiles": [],
    "custom_properties": {
      "facebook": null
    },
    "unsubscribed_from_emails": "false",
    "submitted_form": {
      "id": 36,
      "title": "Welcome",
      "created_at": 1531550359,
      "form_type": "lightbox",
      "status": "live"
    }
  }
}

Meeting Scheduled

Meeting scheduled webhook will trigger when a meeting is scheduled with agent in Gist. We can be identified the meeting scheduled webhook by "event_type":"meeting_scheduled" and the scheduled meeting as "meeting" in request parameter of webhook post request to endpoint URL.

Meeting Scheduled

{
  "event_type": "meeting_scheduled",
  "meeting": {
    "id": 4,
    "contact": {
      "type": "lead",
      "id": 297229,
      "name": "Example",
      "email": "[email protected]",
      "user_id": null,
      "phone": null,
      "created_at": 1541155954,
      "signed_up_at": 1541155953,
      "last_seen_at": 1541155953,
      "last_contacted_at": null,
      "updated_at": 1541155954,
      "session_count": null,
      "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=GO",
      "landing_url": "10.0.1.116/example1gg",
      "original_referrer": null,
      "last_seen_ip": null,
      "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36",
      "location_data": {
        "city_name": null,
        "region_name": null,
        "country_name": null,
        "country_code": null,
        "continent_name": null,
        "continent_code": null,
        "latitude": null,
        "longitude": null,
        "postal_code": null,
        "time_zone": null,
        "utc_offset": null
      },
      "segments": [
        {
          "id": 615,
          "name": "test rule",
          "created_at": 1528984324,
          "updated_at": 1542803636
        }
      ],
      "tags": [],
      "social_profiles": [],
      "custom_properties": {
        "facebook": ""
      },
      "unsubscribed_from_emails": "false"
    },
    "scheduled_date_time": 1541138400,
    "invitee_name": "Example",
    "invitee_email": "[email protected]",
    "invitee_other_details": {
                            "phone_number":"9999999999",
                            "skype_id":"example.example"
        },
    "created_at": 1541156335,
    "updated_at": 1541156885,
    "duration": 45,
    "user_time_zone": "Asia/Calcutta",
    "agent_time_zone": "Etc/GMT+12",
  }
}

Meeting Cancelled

Meeting cancelled webhook will trigger when a meeting is cancelled with agent in Gist. We can be identified the meeting cancelled webhook by "event_type":"meeting_cancelled" and the cancelled meeting as "meeting" in request parameter of webhook post request to endpoint URL.

Meeting Cancelled

{
  "event_type": "meeting_cancelled",
  "meeting": {
    "id": 4,
    "contact": {
      "type": "lead",
      "id": 297229,
      "name": "Example",
      "email": "[email protected]",
      "user_id": null,
      "phone": null,
      "created_at": 1541155954,
      "signed_up_at": 1541155953,
      "last_seen_at": 1541155953,
      "last_contacted_at": null,
      "updated_at": 1541155954,
      "session_count": null,
      "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=GO",
      "landing_url": "10.0.1.116/example1gg",
      "original_referrer": null,
      "last_seen_ip": null,
      "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36",
      "location_data": {
        "city_name": null,
        "region_name": null,
        "country_name": null,
        "country_code": null,
        "continent_name": null,
        "continent_code": null,
        "latitude": null,
        "longitude": null,
        "postal_code": null,
        "time_zone": null,
        "utc_offset": null
      },
      "segments": [
        {
          "id": 615,
          "name": "test rule",
          "created_at": 1528984324,
          "updated_at": 1542803636
        }
      ],
      "tags": [],
      "social_profiles": [],
      "custom_properties": {
        "facebook": ""
      },
      "unsubscribed_from_emails": "false"
    },
    "scheduled_date_time": 1541138400,
    "invitee_name": "Example",
    "invitee_email": "[email protected]",
    "invitee_other_details": {
                            "phone_number":"9999999999",
                            "skype_id":"example.example"
        },
    "created_at": 1541156335,
    "updated_at": 1541156885,
    "duration": 45,
    "user_time_zone": "Asia/Calcutta",
    "agent_time_zone": "Etc/GMT+12",
    "cancellation_reason": "Testing"
  }
}

Meeting Rescheduled

Meeting rescheduled webhook will trigger when a meeting is rescheduled with agent in Gist. We can be identified the meeting rescheduled webhook by "event_type":"meeting_rescheduled" and the rescheduled meeting as "meeting" in request parameter of webhook post request to endpoint URL.

Meeting Rescheduled

{
  "event_type": "meeting_rescheduled",
  "meeting": {
    "id": 4,
    "contact": {
      "type": "lead",
      "id": 297229,
      "name": "Example",
      "email": "[email protected]",
      "user_id": null,
      "phone": null,
      "created_at": 1541155954,
      "signed_up_at": 1541155953,
      "last_seen_at": 1541155953,
      "last_contacted_at": null,
      "updated_at": 1541155954,
      "session_count": null,
      "avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=GO",
      "landing_url": "10.0.1.116/example1gg",
      "original_referrer": null,
      "last_seen_ip": null,
      "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36",
      "location_data": {
        "city_name": null,
        "region_name": null,
        "country_name": null,
        "country_code": null,
        "continent_name": null,
        "continent_code": null,
        "latitude": null,
        "longitude": null,
        "postal_code": null,
        "time_zone": null,
        "utc_offset": null
      },
      "segments": [
        {
          "id": 615,
          "name": "test rule",
          "created_at": 1528984324,
          "updated_at": 1542803636
        }
      ],
      "tags": [],
      "social_profiles": [],
      "custom_properties": {
        "facebook": ""
      },
      "unsubscribed_from_emails": "false"
    },
    "scheduled_date_time": 1541138400,
    "invitee_name": "Example",
    "invitee_email": "[email protected]",
    "invitee_other_details": {
                        "phone_number":"9999999999",
                        "skype_id":"example.example"
    },
    "created_at": 1541156335,
    "updated_at": 1541156885,
    "duration": 45,
    "user_time_zone": "Asia/Calcutta",
    "agent_time_zone": "Etc/GMT+12",
  }
}

Changelog

Any new additions and changes to Gist’s API will be updated here. Be sure to check once in a while to stay informed.

We make sure all the changes we do are mostly backward compatible i.e. old API endpoints and API format will still continue to work without any issues. But, we recommend to update your logics with new changes to make sure you get all updates in future.

If there are any breaking changes in any release, we will be listing those below for easy reference.

May 29, 2020

Added Conversations API's

You can do several actions on conversations. Refer the docs for further details

Added API's for retriving Team and Teammate

You can retrieve a single or list of Team or Teammate. Refer the docs for Team and Teammate

December 26, 2019

Leads & Users APIs has been replaced with the Contacts API.

You can now use Contacts API for both leads and users instead of using two separate APIs.

Tag or Untag Users or Leads API has been replaced with Tag or Untag Contacts API.

You can send both leads and users in the same key contacts instead of using separate key for users and leads.

Introduction

Authentication

Working with OAuth

Rate Limits

Errors

API Structure

Contacts

The contact object

Contact object

Location Data

Social Profile Data

Custom Properties

Create or update a contact

Create a new contact

Update an existing contact

Response

Create or update a batch of contacts

Note:

Response

Retrieve a contact

Response

List all contacts

Response

Delete a contact

Response

Events

The event object

Track an event

Response

List all events

Response

Tags

The tag object

Create or update a tag

Response

Delete a tag

Response

List all tags

Response

Add a tag to contacts

Response

Remove a tag from contacts

Response

Subscription Types

The subscription type object

Retrieve a subscription type

Response

List all subscription types

Response

Attach a contact to subscription type

Response

Detach a contact from subscription type

Response

Segments

The segment object

Retrieve a segment

Response

List all segments

Response

Forms

The form object

Retrieve a form

Response

List all forms

Response

Subscribe contact to a form

Response

List all form submissions

Response

Campaigns

The campaign object

Retrieve a campaign

Response

List all campaigns

Response

Subscribe a contact to campaign

Response

Unsubscribe a contact from campaign

Response

Conversations