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,

Social Profile Data

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:

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.

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

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:

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.

Note:

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:

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.

Tags

Tags allow you to mark or label your contacts and list them using that tag. You can then use group contacts by tags and create highly targeted contact segments for your campaigns.

This section is about creating, updating, and deleting tags using the API. You can also use this to tag or untag contacts in bulk.

The tag object

Example Response

{
    "id": 386,
    "name": "trial"
}

A tag has a name and an id field. Once created the id field cannot be changed, but the name field can be used to rename the tag in the future.

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

Create or update a tag

Example Request

$ curl --request POST \
--url https://api.getgist.com/tags \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
          "name": "Free Trail"
        }'

Example Response

{
    "tag": {
        "id": 727,
        "name": "Free Trail"
    }
}

You can create a new tag by submitting a POST to https://api.getgist.com/tags along with a name for the tag. The tag name may contain whitespace and punctuations.

If the same tag name is sent multiple times, only one tag will be created for that name - this lets you avoid checking if a tag exists first.

Tag names are case insensitive - 'ExampleTag' and 'exampletag' will result in a single tag being created.

A tag's name can also be updated by posting a tag to https://api.getgist.com/tags.

The submitted tag object will contain the id of the tag to update and a new name for the tag. A successful request will update the name value for that tag and return the updated tag in the response.

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

Response

A Tag object.

Delete a tag

Example Request

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

Example Response

{
    "tag": {
        "id": 727,
        "name": "Free Trail"
    }
}

A tag can be deleted by sending a DELETE request to its URL. A tag's URL is defined using the tag's id to create a URL of the form, https://api.getgist.com/tags/{id}.

Response

A Tag object.

List all tags

Example Request

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

Example Response

{
    "tags": [
        {
            "id": 437,
            "name": "Unsubscribed"
        },
        {
            "id": 436,
            "name": "Completed"
        },
        {
            "id": 435,
            "name": "Subscribed"
        },
        {
             "id": 732,
             "name": "Active"
        },
        {
             "id": 727,
             "name": "Free Trial"
        }
    ],
    "pages": {
        "next": "https://api.getgist.com/tags?order=desc&order_by=created_at&page=2&per_page=5",
        "first": "https://api.getgist.com/tags?order=desc&order_by=created_at&page=1&per_page=5",
        "last": "https://api.getgist.com/tags?order=desc&order_by=created_at&page=3&per_page=5"
    }
}

You can fetch the tags for a workspace by sending a GET request to https://api.getgist.com/tags.

Response

A paginated list of Tag objects.

Add a tag to contacts

Example Request

$ curl --request POST \
--url https://api.getgist.com/tags \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
          "id": 727,
          "name": "Free Trial",
          "contacts": [
              {
                "id" : "69768"
              },
              {
                "email":"[email protected]"
              }
            ]
        }'

Example Response

{
    "tag": {
        "id": 727,
        "name": "Free Trail"
    }
}

You can tag contacts using a POST to https://api.getgist.com/tags.

This lets you assign a tag to multiple contacts at once. If the tag does not already exist it will be created for you.

Contacts can be tagged by supplying a contacts array. The array contains objects identifying contacts by their id, email or user_id fields.

We recommend tagging no more than 50 contacts at a time as larger requests could result in a timeout.

Response

A Tag object.

Remove a tag from contacts

Example Request

$ curl --request POST \
--url https://api.getgist.com/tags \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
          "id": 727,
          "name": "Free Trial",
          "contacts": [
              {
                "id" : "69768",
                "untag": true
              },
              {
                "email":"[email protected]",
                 "untag": true
              }
            ]
        }'

Example Response

{
    "tag": {
        "id": 727,
        "name": "Free Trail"
    }
}

You can remove a tag from a contact by adding "untag": true to each of the contact objects. Passing the untag value to false is the same as requesting the contacts be tagged.

Response

A Tag object.

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.

  1. You can pull a list of Forms using the Forms API, as documented below.

  2. 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.

Subscribe contact to a form

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.

Subscribe a contact to campaign

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

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

Added API's for retriving Team and Teammate

December 26, 2019

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

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