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 |
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:
- Property names must not contain Periods ('.') or Dollar ('$') characters
- Property values must be JSON Strings, Numbers or Booleans - Objects and Arrays will be rejected.
- Property names must be no longer than 190 characters.
- String property values must be no longer than 255 characters.
- You can create a maximum of 250 custom properties.
- You can send dates as custom properties by sending a UNIX timestamp. If the name of your custom property ends with _at then we'll automatically treat it as a date, rather than a number.
Create or update a contact
Example Request
curl --request POST \
--url https://api.getgist.com/contacts \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"id": "179351",
"user_id":100488,
"email": "[email protected]",
"name": "Rubamaga",
"phone": null,
"signed_up_at": "",
"last_seen_ip": "",
"last_seen_user_agent": "",
"unsubscribed_from_emails": false,
"custom_properties": {
"age": 23
},
"tags": [
"tagA",
"tagB",
"tagC"
]
}'
Example Response
{
"contact": {
"type": "user",
"id": 179351,
"name": "Rubamaga",
"email": "[email protected]",
"user_id": "100488",
"phone": null,
"created_at": 1502979465,
"signed_up_at": 0,
"last_seen_at": 1502979465,
"last_contacted_at": null,
"updated_at": 1540478268,
"session_count": null,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=BR",
"landing_url": null,
"original_referrer": null,
"last_seen_ip": "",
"last_seen_user_agent": "",
"location_data": {
"city_name": "Paris",
"region_name": null,
"country_name": "France",
"country_code": "FR",
"continent_name": null,
"continent_code": null,
"latitude": 48.871216,
"longitude": 2.271031,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [
{
"id": 578,
"name": "Test validation",
"created_at": 1512633515,
"updated_at": 1512633567
}
],
"tags": [
{
"id": 79,
"name": "tagA"
},
{
"id": 80,
"name": "tagB"
},
{
"id": 81,
"name": "tagC"
}
],
"social_profiles": [],
"custom_properties": {
"form_user": null,
"user_types": null,
"age": 23,
"first_name": null
},
"unsubscribed_from_emails": "false"
}
}
Create a new contact in Gist with a simple HTTP POST to the Contacts API. The contact that is created will be assigned a unique ID (id
) by Gist, which can be used to look it up later.
- Returns 200 response on success. The response will include the details of the contact.
- Returns 422 (or) 400 error when the data in the request body fails validation.
Note: The endpoint will create a new contact if it doesn't find one matching with the email
and/or user_id
in the request, and updates the contact if it finds a match.
Create a new contact
- If only
email
is provided in the HTTP request, the contact will be created as a Lead. - If both
user_id
andemail
are provided, the contact will be created as a User.
Update an existing contact
Note that the following lookup order applies when updating Contacts - id
then user_id
then email
, and results in the following logic:
- if
id
has matched - theuser_id
andemail
will be updated if they are included in the request. - if
user_id
has matched - theemail
will be updated, theid
will not be updated. - if
email
has matched - if nouser_id
is set on the matched contact, thenuser_id
will be set to the value sent in the request, theid
is not updated. Note that this will change the Contact’s type from Lead to User. - if
email
has matched and the matched contact has auser_id
value - theuser_id
of the matched contact will be set to the value sent in the request, theid
is not updated.
Note that email values are down-cased after they have been submitted to our API.
Property | Required | Description |
---|---|---|
Required on create. Required if no user_id is supplied on update. | The contact's email address. | |
user_id | Required on create. Required if no email is supplied on update. | A unique string identifier for the user. It is required to create Contact of type User |
name | no | The full name of the contact |
phone | no | The contact number of the contact |
signed_up_at | no | The time the contact signed up |
last_seen_ip | no | The last IP address the contact visited your website from |
last_seen_user_agent | no | The last contact agent the contact was seen using |
custom_properties | no | Optional. A JSON object containing the contact’s custom properties. E.g. { "name": "John Doe" } |
unsubscribed_from_emails | no | If the contact has unsubscribed from emails or not |
tags | no | The tags the contact is assigned. |
Please note that location data and social profiles are computed by Gist and cannot be updated via the API.
New contact objects will be provided with an id field - this value cannot be changed. Social profiles, location data and avatars are processed asynchronously, and may require a subsequent call to fetch their details.
Response
A Contact object.
Create or update a batch of contacts
Example Request
curl --request POST \
--url https://api.getgist.com/contacts/batch \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"contacts": [
{
"email": "[email protected]",
"name": "Rubamaga2",
"phone": null,
"last_seen_user_agent": "",
"unsubscribed_from_emails": false,
"custom_properties": {
"age": 23
},
"tags": [
"tagA"
]
},
{
"id": "179351",
"email": "[email protected]",
"name": "Rubamaga",
"phone": null,
"last_seen_user_agent": "",
"unsubscribed_from_emails": false,
"custom_properties": {
"age": 25
},
"tags": [
"tagC"
]
}
]
}'
Create a batch of contacts in Gist with a HTTP POST to the Contacts API. The contacts that are created will individually be assigned a unique ID (id
) by Gist, which can be used to look it up later.
- Returns 200 response on success. The response will include array of details for the created contacts.
- Returns 422 (or) 400 error when there is a problem with the data in the request body, including when there are no properties included in the request data.
Note:
- This endpoint will create new contacts if it doesn't find one matching the email or user_id in the request, and updates the contact if it finds a match.
- If any of the contact properties has invalid data, for example, text passed in place of numeric property, the entire request will fail and no contacts will be created.
Response
A paginated list of Contact objects.
Retrieve a contact
Example Request
$ curl --request GET \
--url https://api.getgist.com/contacts/146719 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"contact": {
"type": "lead",
"id": 179351,
"name": "Rubamaga",
"email": "[email protected]",
"phone": null,
"created_at": 1502979465,
"signed_up_at": 0,
"last_seen_at": 1502979465,
"last_contacted_at": null,
"updated_at": 1540478268,
"session_count": null,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=BR",
"landing_url": null,
"original_referrer": null,
"last_seen_ip": "",
"last_seen_user_agent": "",
"location_data": {
"city_name": "Paris",
"region_name": null,
"country_name": "France",
"country_code": "FR",
"continent_name": null,
"continent_code": null,
"latitude": 48.871216,
"longitude": 2.271031,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [
{
"id": 578,
"name": "Test validation",
"created_at": 1512633515,
"updated_at": 1512633567
}
],
"tags": [
{
"id": 79,
"name": "Completed"
}
],
"social_profiles": [],
"custom_properties": {
"form_user": null,
"user_types": null,
"age": 23,
"first_name": null
},
"unsubscribed_from_emails": "false"
}
}
Contacts can be fetched or looked up individually via their id
, email
or with a user_id
parameter.
The ‘contacts’ endpoint accepts two parameters:
Parameter | Required | Description |
---|---|---|
user_id | no | The user id of the contact in your database |
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 |
---|---|---|
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 |
yes if no user_id | An email address for your user. | |
id | yes if no email or user_id | A Gist generated identifier for the contact |
occurred_at | timestamp | The time the event occurred in ISO-8601 format. Defaults to the current time |
properties | json | A JSON of custom properties for the event |
The event_name field is processed as follows:
- Event names are case insensitive. 'Completed-Order' and 'completed-order' will be considered the same event for your workspace.
- Periods (.) and dollars ($) in event names are replaced with hyphens. e.g., 'completed.order' will be stored as 'completed-order'.
To avoid confusion, we recommend sending lowercase event names that do not contain periods or dollars.
Track an event
Example Request
$ curl --request POST \
--url https://api.getgist.com/events \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"event_name": "Clicked Signup Button",
"email": "[email protected]",
"properties": {
"manual_record": true,
"recorded_from": "backend"
},
"occurred_at": null
}'
Example Response
{
"event": {
"id": 97677,
"user_id": null,
"email": "[email protected]",
"name": "Clicked Signup Button",
"properties": {
"manual_record": true,
"recorded_from": "backend"
},
"occurred_at": 1540541183
}
}
You can track an event by submitting a POST to https://api.getgist.com/events
along with a name of the event and a reference to the contact who performed the event.
Response
A Event object.
List all events
Example Request
$ curl --request GET \
--url https://api.getgist.com/events?event_type=all \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"events": [
{
"id": 97677,
"name": "Clicked Signup Button"
},
{
"id": 611,
"name": "Inactive"
},
{
"id": 7,
"name": "Active"
},
{
"id": 133,
"name": "Email Subscribed"
},
{
"id": 132,
"name": "Send Notification"
},
],
"pages": {
"first": "https://api.getgist.com/events?order=desc&order_by=created_at&page=1&per_page=50",
"last": "https://api.getgist.com/events?order=desc&order_by=created_at&page=1&per_page=50"
}
}
You can fetch all the events of a Workspace by sending a GET request to https://api.getgist.com/events
.
Parameter | Required | Description |
---|---|---|
page | no | The page number. Defaults to 1. |
per_page | no | The number of records to be returned on each page. Defaults to 50. Maximum 60. |
Response
A paginated list of Event objects.
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 |
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 |
yes if no user_id | Email id of the contact | |
contact_id | yes if no user_id and email | Unique Id of the contact |
subscribed_status | yes | Describes if contact is added or removed from subscription. 'true' to add and 'false' to remove |
Response
A Contact object.
Segments
Segments are dynamic groups of contacts defined by filters and rules that you set.
The segment object
Example Response
{
"segment": {
"id": 7,
"name": "Active",
"created_at": 1493141363,
"updated_at": 1539756959,
"count": 43
}
}
A segment has a name and an id
field along with created_at
and updated_at
timestamps. It can optionally include a count
of the contacts in the segment.
Parameter | Type | Description |
---|---|---|
id | string | The id representing the segment |
name | string | The name of the segment |
created_at | timestamp | The time the segment was created |
updated_at | timestamp | The time the segment was updated |
count | integer | The number of items in the segment. It's returned when include_count=true is included in the request |
Retrieve a segment
Example Request
$ curl --request GET \
--url https://api.getgist.com/segments/7?include_count=true \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"segment": {
"id": 7,
"name": "Active",
"created_at": 1493141363,
"updated_at": 1539756959,
"count": 2343
}
}
Each segment has its own URL: https://api.getgist.com/segments/{id}
Where {id} is the value of the segment's id field. A GET request to a segment's URL will return the segment object.
You can also get a count for an individual segment by adding the parameter include_count=true
Response
A Segment object.
List all segments
Example Request
$ curl --request GET \
--url https://api.getgist.com/segments?per_page=2&page=5&include_count=true \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"segments": [
{
"id": 611,
"name": "Inactive",
"created_at": 1524577042,
"updated_at": 1538552649,
"count": 153
},
{
"id": 7,
"name": "Active",
"created_at": 1512633515,
"updated_at": 1512633567,
"count": 2343
}
],
"pages": {
"next": "https://api.getgist.com/segments?order=desc&order_by=created_at&page=2&per_page=2",
"first": "https://api.getgist.com/segments?order=desc&order_by=created_at&page=1&per_page=2",
"last": "https://api.getgist.com/segments?order=desc&order_by=created_at&page=7&per_page=2"
}
}
You can list the segments for your Workspace by sending a GET request to https://api.getgist.com/segments
. You can also include counts in your segment object in the response if you add the parameter include_count=true
in the request.
Response
A paginated list of Segment object.
Forms
The form object
Example Response
{
"form": {
"id": 36,
"title": "Welcome",
"created_at": 1531550359,
"form_type": "lightbox",
"status": "live",
"fields": [
{
"key": "email",
"label": "Email Address",
"is_required": "true"
}
]
}
}
A Form object describes the form and contains the following fields
Property | Type | Description |
---|---|---|
id | string | The id representing the form |
title | string | Title of the form |
created_at | timestamp | The time the form was created |
form_type | string | Type of the form |
status | string | Status of the form |
fields | array | Fields of the form |
Retrieve a form
Example Request
curl --request GET \
--url 'https://api.getgist.com/forms?form_id=42161287' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"form": {
"id": 42161287,
"title": "Testing",
"created_at": 1519189724,
"form_type": "lightbox",
"status": "live",
"fields": [
{
"key": "email",
"label": "Email Address",
"is_required": "true",
"type": "string"
}
]
}
}
You can fetch a form from a Workspace by sending a GET request to https://api.getgist.com/forms
with form_id as the parameter.
The Form ID can be found in one of two ways.
You can pull a list of Forms using the Forms API, as documented below.
You can also find the Form ID in the Gist UI: navigate to Forms from the navigation menu > click to edit a specific form > when editing a specific form, you can find the Form ID in the URL of the embedded form section. In the URL https://data.getgist.com/subscribe/2775350, the form ID is 2775350
Response
A Form object.
List all forms
Example Request
curl --request GET \
--url https://api.getgist.com/forms \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"forms": [
{
"id": 95775704,
"title": "sample",
"created_at": 1561355053,
"form_type": "notification",
"status": "draft",
"fields": [
{
"key": "email",
"label": "Email Address",
"is_required": "true",
"type": "string"
}
]
},
{
"id": 72280292,
"title": "Test form",
"created_at": 1557735548,
"form_type": "lightbox",
"status": "draft",
"fields": [
{
"key": "email",
"label": "Email Address",
"is_required": "true",
"type": "string"
}
]
},
{
"id": 64911038,
"title": "Example Form",
"created_at": 1555393267,
"form_type": "lightbox",
"status": "paused",
"fields": [
{
"key": "email",
"label": "Email Address",
"is_required": "true",
"type": "string"
}
]
},
{
"id": 25482088,
"title": "Light Box23",
"created_at": 1553694654,
"form_type": "lightbox",
"status": "live",
"fields": [
{
"key": "email",
"label": "Email Address",
"is_required": "true",
"type": "string"
}
]
},
{
"id": 59683938,
"title": "Example Form 2",
"created_at": 1544262463,
"form_type": "lightbox",
"status": "paused",
"fields": [
{
"key": "email",
"label": "Email Address",
"is_required": "true",
"type": "string"
},
{
"key": "name",
"label": "name",
"is_required": "true",
"type": "string"
},
{
"key": "membership",
"label": "m",
"is_required": "true",
"type": "string"
}
]
}
],
"page": {
"first": "https://api.getgist.com/forms?order=desc&order_by=created_at&page=1&per_page=50",
"last": "https://api.getgist.com/forms?order=desc&order_by=created_at&page=1&per_page=50"
}
}
You can fetch all forms for a Workspace by sending a GET request to https://api.getgist.com/forms
The form list is sorted by the created_at property and by default is ordered descending, most recently created first.
Request Parameters
The following optional parameters can be used to request the result page size and which page to fetch.
Parameter | Required | Description |
---|---|---|
page | no | The page of results to fetch. Defaults to first page |
per_page | no | The number of results per page. Defaults to 50, max is 60 |
order | no | The sort order of the returned contact list. asc or desc. Defaults to desc |
order_by | no | The property to sort the fetched results by. Defaults to created_at. Other options: last_seen_at, signed_up_at, updated_at |
status | no | Filter by one of the following statuses: live, or paused, or draft. Defaults to all. |
Returns: .
The form list contains a pages object that indicates if more forms exist via the next field, whose value is a URL that can be used to fetch the next page. If the next field is not present, that indicates there are no further forms in the list.
Response
A paginated list of Form object.
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 |
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 |
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 |
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 |
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 |
string | The email of the teammate | |
avatar | string | URL where the user's profile image is saved |
agent_status | string | status of the user. whether online, away or offline based on their last seen |
last_active_on | DateTime | The time with which the user has made last web activity irrespective of the away mode. |
away_mode_enabled | boolean | Whether the teammate is currently set in away more or not. |
has_inbox_seat | boolean | Whether the teammate has a paid inbox seat or not |
team_ids | object | A list of team ids the teammate is a part of |
Retrieve a teammate
Example Request
curl --request GET \
--url https://api.getgist.com/teammates/ \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"teammate_id": "493881", // one of these
"email": "[email protected]", // one of these
}'
You can fetch the details of a single teammate.
GET https://api.getgist.com/teammates/{teammate_id}
You can send either the teammate_id
or the email
of the teammate to fetch their details.
Response
A Teammate object.
Retrieve a list of Teammates
Example Request
curl --request GET \
--url https://api.getgist.com/teammates \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
You can fetch the details of all teammates within your Gist workspace.
GET https://api.getgist.com/teammates/
Response
A paginated list of Teammates objects.
Webhooks
In Gist with the help of webhooks, we will provide you with real-time information immediately. If any changes happen in the website like a user filled a form or had a conversation with an agent, each and every information will be delivered to you as it happens. This makes the process more efficient, unlike other APIs where you need to call for data very frequently in order to get it real-time.
Webhooks are available on our Premium plans.
Setup webhooks
- Navigate to Settings > API > Webhooks page.
- Click “New Webhook” button
- Enter a name, endpoint URL
- Choose the topic and request headers and body
- Set it live
Supported topics
You can retrieve the data in JSON format. Webhooks are available for the following topics
Topic | Description |
---|---|
User Created | When a new user gets created |
Lead Created | When a new lead gets created |
User Deleted | When a existing user is deleted |
Lead Deleted | When a existing lead is deleted |
Contact Tagged | When a contact gets tagged |
Contact Untagged | When a contact gets untagged |
Custom Attribute Updated | When a custom attribute is updated |
Contact Email Updated | When the contact email is updated |
Contact Unsubscribed Emails | When a contact unsubscribed emails |
Contact Initiated Conversation | When we receive a new message from a contact |
Conversation Assigned | When a conversation gets assigned to a teammate |
Conversation Opened | When a conversation is opened |
Conversation Closed | When a conversation is closed |
Conversation Rating | When a conversation is rated by a contact |
Message From Contact | When a contact send a message in chat |
Teammate Replied | When a teammate replied in chat |
Note Added | When a teammate add a note to the conversation |
Contact Subscribed Campaign | When the contact subscribed for a campaign |
Contact Unsubscribed Campaign | When the contact unsubscribed for a campaign |
New Page Visit | When there is a new page visit |
Contact Performed Event | When a contact performed an event |
Lead Submitted Email | When a lead submits an Email |
Event Created | When a event is created |
Contact Submitted Form | When a contact submits a form |
Meeting Scheduled | When a meeting is scheduled |
Meeting Cancelled | When a meeting is cancelled |
Meeting Rescheduled | When a meeting is rescheduled |
Handling Notification
When you setup a subscription you will receive notifications on your chosen topics. How you handle those notifications, i.e. the HTTP status code returned, will determine the subsequent state of that subscription. Please see below for a list of how a subscription will respond to these status codes
Response Code | Description | Action |
---|---|---|
2XX | Success | Timeout in 10 seconds |
410 | Gone- Resource no longer available | The webhook will be disabled |
4XX*, 5XX | Client or service error | 1st retry in 1 Hour. 2nd retry in 3 Hours. 3rd retry in 6 Hours. 4th retry in 24 Hours |
Note: Retry interval is relative to original attempt.
*Excluding 410
Webhook data
User Created
User created webhook will trigger when an user is created with Gist. We can be identified the user created webhook
by "event_type":"user_created"
and the created user as "user"
with "type":"user"
in request parameter of webhook post request to endpoint URL.
User Created
{
"event_type": "user_created",
"contact" {
"type": "user",
"id": 297267,
"name": Example,
"email": "[email protected]",
"user_id": 1234,
"phone": 9999999999,
"created_at": 1542699961,
"signed_up_at": 1542700022,
"last_seen_at": 1542700022,
"last_contacted_at": null,
"updated_at": 1542700022,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
"landing_url": "getgist.com",
"original_referrer": "",
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": "false"
}
}
Lead Created
Lead created webhook will trigger when a lead is created with Gist. We can be identified the lead created webhook
by "event_type":"lead_created"
and the created user as "user"
with "type":"lead"
in request parameter of webhook post request to endpoint URL.
Lead Created
{
"event_type": "lead_created",
"contact" {
"type": "lead",
"id": 297267,
"name": null,
"email": "[email protected]",
"user_id": null,
"phone": null,
"created_at": 1542699961,
"signed_up_at": 1542700022,
"last_seen_at": 1542700022,
"last_contacted_at": null,
"updated_at": 1542700022,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
"landing_url": "getgist.com",
"original_referrer": "",
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": "false"
}
}
User Deleted
User deleted webhook will trigger when an user is deleted in Gist. We can be identified the user deleted webhook
by "event_type":"user_deleted"
and the deleted user as "user"
with "type":"user"
in request parameter of webhook post request to endpoint URL.
User Deleted
{
"event_type": "delete_lead",
"contact" {
"type": "lead",
"id": 297265,
"name": Example,
"email": [email protected],
"user_id": 1234,
"phone": 9999999999,
"created_at": 1542698541,
"signed_up_at": null,
"last_seen_at": 1542698541,
"last_contacted_at": null,
"updated_at": 1542698578,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/unknown?size=120u0026type=svgu0026text=SI",
"landing_url": "getgist.com",
"original_referrer": "",
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": null
}
}
Lead Deleted
Lead deleted webhook will trigger when a lead is deleted in Gist. We can be identified the lead deleted webhook
by "event_type":"lead_deleted"
and the deleted lead as "user"
with "type":"lead"
in request parameter of webhook post request to endpoint URL.
Lead Deleted
{
"event_type": "delete_lead",
"contact" {
"type": "lead",
"id": 297265,
"name": null,
"email": [email protected],
"user_id": null,
"phone": null,
"created_at": 1542698541,
"signed_up_at": null,
"last_seen_at": 1542698541,
"last_contacted_at": null,
"updated_at": 1542698578,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/unknown?size=120u0026type=svgu0026text=SI",
"landing_url": "getgist.com",
"original_referrer": "",
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": null
}
}
Contact Tagged
Contact tagged webhook will trigger when a contact(lead/user) is tagged in Gist. We can be identified the contact tagged webhook
by "event_type":"contact_tagged"
and the added tag as "added_tag"
in request parameter of webhook post request to endpoint URL.
Contact Tagged
{
"event_type": "contact_tagged",
"contact" {
"type": "lead",
"id": 297266,
"name": null,
"email": "[email protected]",
"user_id": null,
"phone": null,
"created_at": 1542699599,
"signed_up_at": 1542699634,
"last_seen_at": 1542699634,
"last_contacted_at": null,
"updated_at": 1542699634,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=EX",
"landing_url": "lvh.me",
"original_referrer": "",
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [],
"tags": [
{
"id": 320,
"name": "webhook"
}
],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": "false",
"added_tag": {
"id": 320,
"name": "webhook"
}
}
}
Contact Untagged
Contact untagged webhook will trigger when a contact(lead/user) is untagged in Gist. We can be identified the contact untagged webhook
by "event_type":"contact_untagged"
and the removed tag as "removed_tag"
in request parameter of webhook post request to endpoint URL.
Contact Untagged
{
"event_type": "contact_untagged",
"contact" {
"type": "lead",
"id": 297266,
"name": null,
"email": "[email protected]",
"user_id": null,
"phone": null,
"created_at": 1542699599,
"signed_up_at": 1542699634,
"last_seen_at": 1542699634,
"last_contacted_at": null,
"updated_at": 1542699634,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=EX",
"landing_url": "lvh.me",
"original_referrer": "",
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [],
"tags": [
{
"id": 330,
"name": "eduction"
}
],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": "false",
"removed_tag": {
"id": 320,
"name": "webhook"
}
}
}
Custom Attribute Updated
Custom Attribute Updated webhook will trigger when the custom attribute of a contact(lead/user) is updated in Gist.
We can be identified the custom attribute updated webhook by "event_type":"custom_attribute_updated"
and
the updated custom attributes in "custom_properties"
in request parameter of webhook post request to endpoint URL.
Custom Attribute Updated
{
"event_type": "user_created",
"contact" {
"type": "user",
"id": 297267,
"name": Example,
"email": "[email protected]",
"user_id": 1234,
"phone": 9999999999,
"created_at": 1542699961,
"signed_up_at": 1542700022,
"last_seen_at": 1542700022,
"last_contacted_at": null,
"updated_at": 1542700022,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
"landing_url": "facebook.com",
"original_referrer": "",
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": true,
"twitter": false
},
"unsubscribed_from_emails": "false"
}
}
Contact Email Updated
Contact email updated webhook will trigger when the email of a contact(lead/user) is updated in Gist.
We can be identified the Contact email updated webhook by "event_type":"contact_email_updated"
and the updated email
in "email"
of "user"
in request parameter of webhook post request to endpoint URL.
Contact Email Updated
{
"event_type": "contact_email_updated",
"contact" {
"type": "user",
"id": 297267,
"name": Example,
"email": "[email protected]",
"user_id": 1234,
"phone": 9999999999,
"created_at": 1542699961,
"signed_up_at": 1542700022,
"last_seen_at": 1542700022,
"last_contacted_at": null,
"updated_at": 1542700022,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
"landing_url": "getgist.com",
"original_referrer": "",
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": "false"
}
}
Contact Unsubscribed Emails
Contact unsubscribed emails webhook will trigger when the contact(lead/user) is unsubscribed from emails in Gist.
We can be identified the Contact unsubscribed emails webhook by "event_type":"contact_unsubscribed_email"
and
the contact unsubscribed emails in "unsubscribed_from_emails"
of "user"
in request parameter of webhook post request to endpoint URL.
Contact Unsubscribed Emails
{
"event_type": "contact_unsubscribed_emails",
"contact" {
"type": "user",
"id": 297267,
"name": Example,
"email": "[email protected]",
"user_id": 1234,
"phone": 9999999999,
"created_at": 1542699961,
"signed_up_at": 1542700022,
"last_seen_at": 1542700022,
"last_contacted_at": null,
"updated_at": 1542700022,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
"landing_url": "getgist.com",
"original_referrer": "",
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": "true"
}
}
Contact Initiated Conversation
Contact initiated conversation webhook will trigger when the contact(lead/user) started a new chat in Gist.
We can be identified the Contact initiated conversation webhook by "event_type":"contact_initiated_conversation"
and
the contact initiated conversation as "conversation"
in request parameter of webhook post request to endpoint URL.
Contact Initiated Conversation
{
"event_type": "contact_initiated_conversation",
"conversation": {
"id": 13859,
"channel": "Chat",
"state": "open",
"title": "Conversation title",
"contact": {
"type": "user",
"id": 13450,
"user_id": "13450",
"email": "[email protected]"
},
"assignee": {
"type": "teammate",
"id": 158,
"name": "Example",
"email": "[email protected]",
}
}
}
Conversation Assigned
Conversation assigned webhook will trigger when the conversation is assigned to some agent/team in Gist.
We can be identified the conversation assigned webhook by "event_type":"conversation_assigned"
and the agent/team to whom
the conversation assigned in "assignee"
of "conversation"
in request parameter of webhook post request to endpoint URL.
Conversation Assigned
{
"event_type": "conversation_assigned",
"conversation": {
"id": 13859,
"channel": "Chat",
"state": "open",
"title": "Conversation title",
"contact": {
"type": "user",
"id": 13450,
"user_id": "13450",
"email": "[email protected]"
},
"assignee": {
"type": "teammate",
"id": 158,
"name": "Example",
"email": "[email protected]",
}
}
}
Conversation Opened
Conversation opened webhook will trigger when the conversation is opened in Gist.
We can be identified the conversation opened webhook by "event_type":"conversation_opened"
and
the conversation opened with "state"
of "conversation"
in request parameter of webhook post request to endpoint URL.
Conversation Opened
{
"event_type": "conversation_opened",
"conversation": {
"id": 13859,
"channel": "Chat",
"state": "open",
"title": "Conversation title",
"contact": {
"type": "user",
"id": 13450,
"user_id": "13450",
"email": "[email protected]"
},
"assignee": {
"type": "teammate",
"id": 158,
"name": "Example",
"email": "[email protected]",
}
}
}
Conversation Closed
Conversation closed webhook will trigger when the conversation is closed in Gist.
We can be identified the conversation closed webhook by "event_type":"conversation_closed"
and
the conversation closed with "state"
of "conversation"
in request parameter of webhook post request to endpoint URL.
Conversation Closed
{
"event_type": "conversation_closed",
"conversation": {
"id": 13859,
"channel": "Chat",
"state": "open",
"title": "Conversation title",
"contact": {
"type": "user",
"id": 13450,
"user_id": "13450",
"email": "[email protected]"
},
"assignee": {
"type": "teammate",
"id": 158,
"name": "Example",
"email": "[email protected]",
}
}
}
Conversation Rating
A conversation rating contains information related to a customer's satisfaction with their interaction with your team. For more info on conversation ratings please see here
Conversation rating
{
"event_type": "conversation_rating",
"conversation": {
"id": 13859,
"channel": "Chat",
"state": "open",
"title": "Conversation title",
"contact": {
"type": "lead",
"id": 129243610,
"user_id": "nil",
"email": "[email protected]"
},
"assignee": {
"type": "teammate",
"id": 138,
"name": "John",
"email"=>"[email protected]"
},
"conversation_rating": {
"rating": 5,
"remark": "Good",
"created_at": 1590542572,
"contact": {
"id": 129243610
},
"teammate": {
"id": 138,
"name": "John",
"email": "[email protected]"
}
}
}
}
The conversation rating object
Property | Type | Description |
---|---|---|
rating | integer | The rating is between 1 and 5 for the conversation |
remark | string | An optional field to add a remark to correspond to the number rating |
created_at | timestamp | The time the conversation that is being rated was created |
contact | Contact object | An object containing the ID and type of the customer (e.g. it could be a user or lead) |
agent | User object | An object containing the ID the teammate finally replied to the conversation |
Message From Contact
Message from contact webhook will trigger when the contact(lead/user) send a message to a conversation in Gist.
We can be identified the message from contact webhook by "event_type":"message_from_contact"
, the message from
contact as "message"
and the contact "author"
object with type 'contact'
in request parameter of webhook post request to endpoint URL.
Contact Replied
{
"event_type": "message_from_contact",
"message": {
"message_type": "reply",
"is_inbound": true,
"id": 25137,
"conversation_id": 13832,
"body": "Hi there",
"channel": "Chat", // can also be Email/Facebook/Twitter/API
"created_at": 1585112120,
"updated_at": 1585112120,
"author": {
"type": "contact",
"id": 324124,
"email": "[email protected]",
"first_name": "Smith",
"last_name": "Jardon"
}
}
}
Teammate Replied
Teammate replied webhook will trigger when the teammate replied for a conversation in Gist.
We can be identified the teammate replied webhook by "event_type":"teammate_replied"
, the teammate replied message
as "message"
and the teammate as "author"
object with type 'teammate'
in request parameter of webhook post request to endpoint URL.
Teammate Replied
{
"event_type": "teammate_replied",
"message": {
"message_type": "reply",
"is_inbound": true,
"id": 25137,
"conversation_id": 13832,
"created_at": 1585112120,
"updated_at": 1585112120,
"channel": "Chat", // can also be Email/Facebook/Twitter/API
"author": {
"type": "teammate",
"id": 324124,
"email": "[email protected]",
"first_name": "Christopher",
"last_name": "Syre"
}
}
}
Note Added
Note added webhook will trigger when the teammate added a note in a conversation in Gist.
We can be identified the note added webhook by "event_type":"note_added"
, the note message
as "message"
and the teammate as "agent"
in request parameter of webhook post request to endpoint URL.
Note Added
{
"event_type": "note_added",
"message": {
"message_type": "note",
"is_inbound": false,
"id": 25137,
"conversation_id": 13832,
"body": "@Smith - Can you please check this?&nbsp;",
"channel": "Chat", // can also be Email/Facebook/Twitter/API
"created_at": 1585112120,
"updated_at": 1585112120,
"author": {
"type": "teammate",
"id": 324124,
"email": "[email protected]",
"first_name": "Christopher",
"last_name": "Syre"
}
}
}
}
Contact Subscribed Campaign
Contact subscribed campaign webhook will trigger when the contact(lead/user) subscribed to a campaign in Gist.
We can be identified the contact subscribed campaign webhook by "event_type":"contact_subscribed_campaign"
and
the subscribed campaign in "campaign"
of "user"
in request parameter of webhook post request to endpoint URL.
Contact Subscribed Campaign
{
"event_type": "contact_subscribed_campaign",
"contact" {
"type": "lead",
"id": 297268,
"name": "Test",
"email": "[email protected]",
"user_id": null,
"phone": null,
"created_at": 1542700926,
"signed_up_at": 1542700956,
"last_seen_at": 1542700956,
"last_contacted_at": null,
"updated_at": 1542700956,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
"landing_url": null,
"original_referrer": null,
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [
{
"id": 599,
"name": "All Users",
"created_at": 1524656926,
"updated_at": 1542700957
}
],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": "false",
"campaign": {
"id": 32,
"status": "live",
"name": "Test campaign",
"created_at": 1528963438,
"updated_at": 1542701276,
"email_count": 1,
"active_subscriber_count": 4,
"unsubscribed_subscriber_count": 0,
"email_open_rate": 0,
"email_click_rate": 0,
"href": "https://app.getgist.com/projects/gg94simq/campaigns/32"
}
}
}
Contact Unsubscribed Campaign
Contact unsubscribed campaign webhook will trigger when the contact(lead/user) unsubscribed to a campaign in Gist.
We can be identified the contact unsubscribed campaign webhook by "event_type":"contact_unsubscribed_campaign"
and
the unsubscribed campaign in "campaign"
of "user"
in request parameter of webhook post request to endpoint URL.
Contact Unsubscribed Campaign
{
"event_type": "contact_unsubscribed_campaign",
"contact" {
"type": "lead",
"id": 297268,
"name": "Test",
"email": "[email protected]",
"user_id": null,
"phone": null,
"created_at": 1542700926,
"signed_up_at": 1542700956,
"last_seen_at": 1542700956,
"last_contacted_at": null,
"updated_at": 1542700956,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
"landing_url": null,
"original_referrer": null,
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [
{
"id": 599,
"name": "All Users",
"created_at": 1524656926,
"updated_at": 1542700957
}
],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": "false",
"campaign": {
"id": 32,
"status": "live",
"name": "Test campaign",
"created_at": 1528963438,
"updated_at": 1542701276,
"email_count": 1,
"active_subscriber_count": 4,
"unsubscribed_subscriber_count": 0,
"email_open_rate": 0,
"email_click_rate": 0,
"href": "https://app.getgist.com/projects/gg94simq/campaigns/32"
}
}
}
Contact Performed Event
Contact performed event webhook will trigger when the contact(lead/user) performed a defined event in Gist.
We can be identified the contact performed event webhook by "event_type":"contact_performed_event"
and
the performed event as "event"
of "user"
in request parameter of webhook post request to endpoint URL.
Contact Performed Event
{
"event_type": "contact_performed_event",
"contact" {
"type": "lead",
"id": 297276,
"name": null,
"email": "[email protected]",
"user_id": null,
"phone": null,
"created_at": 1544075170,
"signed_up_at": 1544075441,
"last_seen_at": 1544079362,
"last_contacted_at": null,
"updated_at": 1544079362,
"session_count": 2,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
"landing_url": "localhost",
"original_referrer": "",
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [
{
"id": 599,
"name": "All Users",
"created_at": 1524656926,
"updated_at": 1544075441
}
],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": "false",
"event": {
"id": 297276,
"user_id": null,
"email": "[email protected]",
"name": "Event Name",
"properties": {
"tag": "",
"type": "",
"id": "",
"class": "",
"href": "",
"linkText": "",
"action": "",
"title": "Helloworld",
"method": ""
},
"occurred_at": 1544079788
}
}
}
Lead Submitted Email
Lead submitted email webhook will trigger when the lead submitted email in Gist. We can be identified
the lead submitted email webhook by "event_type":"lead_submitted_email"
and
the submitted email in "email"
of "user"
in request parameter of webhook post request to endpoint URL.
Lead Submitted Email
{
"event_type": "lead_submitted_email",
"contact" {
"type": "lead",
"id": 297267,
"name": null,
"email": "[email protected]",
"user_id": null,
"phone": null,
"created_at": 1542699961,
"signed_up_at": 1542700022,
"last_seen_at": 1542700022,
"last_contacted_at": null,
"updated_at": 1542700022,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
"landing_url": "getgist.com",
"original_referrer": "",
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [
{
"id": 599,
"name": "All Users",
"created_at": 1524656926,
"updated_at": 1542700023
}
],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": "false"
}
}
Contact Submitted Form
Contact submitted form webhook will trigger when the contact submitted a form in Gist, based on optin method of submitted form.
We can be identified the contact submitted form webhook by "event_type":"contact_submitted_form"
and
the submitted form in "submitted_form"
of "user"
in request parameter of webhook post request to endpoint URL.
Contact Submitted Form
{
"event_type": “contact_submitted_form”,
"contact" {
"type": "lead",
"id": 297268,
"name": "Test",
"email": "[email protected]",
"user_id": null,
"phone": null,
"created_at": 1542700926,
"signed_up_at": 1542700956,
"last_seen_at": 1542700956,
"last_contacted_at": null,
"updated_at": 1542700956,
"session_count": 1,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=TE",
"landing_url": null,
"original_referrer": null,
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [
{
"id": 599,
"name": "All Users",
"created_at": 1524656926,
"updated_at": 1542700957
}
],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": null
},
"unsubscribed_from_emails": "false",
"submitted_form": {
"id": 36,
"title": "Welcome",
"created_at": 1531550359,
"form_type": "lightbox",
"status": "live"
}
}
}
Meeting Scheduled
Meeting scheduled webhook will trigger when a meeting is scheduled with agent in Gist. We can be identified the meeting scheduled
webhook by "event_type":"meeting_scheduled"
and the scheduled meeting as "meeting"
in request parameter of webhook post request to endpoint URL.
Meeting Scheduled
{
"event_type": "meeting_scheduled",
"meeting": {
"id": 4,
"contact": {
"type": "lead",
"id": 297229,
"name": "Example",
"email": "[email protected]",
"user_id": null,
"phone": null,
"created_at": 1541155954,
"signed_up_at": 1541155953,
"last_seen_at": 1541155953,
"last_contacted_at": null,
"updated_at": 1541155954,
"session_count": null,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=GO",
"landing_url": "10.0.1.116/example1gg",
"original_referrer": null,
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [
{
"id": 615,
"name": "test rule",
"created_at": 1528984324,
"updated_at": 1542803636
}
],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": ""
},
"unsubscribed_from_emails": "false"
},
"scheduled_date_time": 1541138400,
"invitee_name": "Example",
"invitee_email": "[email protected]",
"invitee_other_details": {
"phone_number":"9999999999",
"skype_id":"example.example"
},
"created_at": 1541156335,
"updated_at": 1541156885,
"duration": 45,
"user_time_zone": "Asia/Calcutta",
"agent_time_zone": "Etc/GMT+12",
}
}
Meeting Cancelled
Meeting cancelled webhook will trigger when a meeting is cancelled with agent in Gist. We can be identified the meeting cancelled
webhook by "event_type":"meeting_cancelled"
and the cancelled meeting as "meeting"
in request parameter of webhook post request to endpoint URL.
Meeting Cancelled
{
"event_type": "meeting_cancelled",
"meeting": {
"id": 4,
"contact": {
"type": "lead",
"id": 297229,
"name": "Example",
"email": "[email protected]",
"user_id": null,
"phone": null,
"created_at": 1541155954,
"signed_up_at": 1541155953,
"last_seen_at": 1541155953,
"last_contacted_at": null,
"updated_at": 1541155954,
"session_count": null,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=GO",
"landing_url": "10.0.1.116/example1gg",
"original_referrer": null,
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [
{
"id": 615,
"name": "test rule",
"created_at": 1528984324,
"updated_at": 1542803636
}
],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": ""
},
"unsubscribed_from_emails": "false"
},
"scheduled_date_time": 1541138400,
"invitee_name": "Example",
"invitee_email": "[email protected]",
"invitee_other_details": {
"phone_number":"9999999999",
"skype_id":"example.example"
},
"created_at": 1541156335,
"updated_at": 1541156885,
"duration": 45,
"user_time_zone": "Asia/Calcutta",
"agent_time_zone": "Etc/GMT+12",
"cancellation_reason": "Testing"
}
}
Meeting Rescheduled
Meeting rescheduled webhook will trigger when a meeting is rescheduled with agent in Gist. We can be identified the meeting rescheduled
webhook by "event_type":"meeting_rescheduled"
and the rescheduled meeting as "meeting"
in request parameter of webhook post request to endpoint URL.
Meeting Rescheduled
{
"event_type": "meeting_rescheduled",
"meeting": {
"id": 4,
"contact": {
"type": "lead",
"id": 297229,
"name": "Example",
"email": "[email protected]",
"user_id": null,
"phone": null,
"created_at": 1541155954,
"signed_up_at": 1541155953,
"last_seen_at": 1541155953,
"last_contacted_at": null,
"updated_at": 1541155954,
"session_count": null,
"avatar": "https://avatar.tobi.sh/[email protected]?size=120u0026type=svgu0026text=GO",
"landing_url": "10.0.1.116/example1gg",
"original_referrer": null,
"last_seen_ip": null,
"last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36",
"location_data": {
"city_name": null,
"region_name": null,
"country_name": null,
"country_code": null,
"continent_name": null,
"continent_code": null,
"latitude": null,
"longitude": null,
"postal_code": null,
"time_zone": null,
"utc_offset": null
},
"segments": [
{
"id": 615,
"name": "test rule",
"created_at": 1528984324,
"updated_at": 1542803636
}
],
"tags": [],
"social_profiles": [],
"custom_properties": {
"facebook": ""
},
"unsubscribed_from_emails": "false"
},
"scheduled_date_time": 1541138400,
"invitee_name": "Example",
"invitee_email": "[email protected]",
"invitee_other_details": {
"phone_number":"9999999999",
"skype_id":"example.example"
},
"created_at": 1541156335,
"updated_at": 1541156885,
"duration": 45,
"user_time_zone": "Asia/Calcutta",
"agent_time_zone": "Etc/GMT+12",
}
}
Changelog
Any new additions and changes to Gist’s API will be updated here. Be sure to check once in a while to stay informed.
We make sure all the changes we do are mostly backward compatible i.e. old API endpoints and API format will still continue to work without any issues. But, we recommend to update your logics with new changes to make sure you get all updates in future.
If there are any breaking changes in any release, we will be listing those below for easy reference.
May 29, 2020
Added Conversations API's
- You can do several actions on conversations. Refer the docs for further details
Added API's for retriving Team and Teammate
December 26, 2019
Leads & Users APIs has been replaced with the Contacts API.
- You can now use Contacts API for both leads and users instead of using two separate APIs.
Tag or Untag Users or Leads API has been replaced with Tag or Untag Contacts API.
- You can send both leads and users in the same key
contacts
instead of using separate key forusers
andleads
.