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 |
|---|---|---|
| Articles | https://api.getgist.com/articles |
Fetch, search, delete, create and update your articles. |
| Collections | https://api.getgist.com/collections |
Fetch, delete, create and update your collections. |
| Contacts | https://api.getgist.com/contacts |
Fetch, search, create and update your contacts. |
| Events | https://api.getgist.com/events |
View your events and track contact activity. |
| Tags | https://api.getgist.com/tags |
Fetch, create, update and delete your contact tags. Attach/detach tags to contacts. |
| Segments | https://api.getgist.com/segments |
View your workspace's 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. |
| Subscription types | https://api.getgist.com/subscription_types |
View your workspace's subscription types. Attach/detach subscription types to contacts. |
| Conversations | https://api.getgist.com/conversations |
List conversations you have with visitors and contacts. Add notes and reply to conversations. |
| Teams | https://api.getgist.com/teams |
View your workspace's teammates. |
| Teammates | https://api.getgist.com/teammates |
View your workspace's teams. |
| Token | https://api.getgist.com/token |
Fetch token information along with current workspace ID. |
Articles
An article in project documentation is a concise piece of written content that explains specific features, functionalities, or usage instructions. It serves as a reference guide for users, offering clear explanations and step-by-step instructions on how to interact with or utilize aspects of the project. Articles aim to provide users with the necessary information to understand and effectively use the project's capabilities.
The Article object
Example Response
{
"article": {
"id": 2,
"parent_id": 24,
"secondary_ids": [],
"default_locale": "en",
"statistics": {
"views": 7,
"reactions": 0,
"helpful_reactions": 0,
"unhelpful_reactions": 0
},
"translations": {
"en": {
"author": {
"id": 824,
"name": "John",
"email": "[email protected]",
"avatar": "https://gist.b-cdn.net/users_profiles/2063/medium/c9297531cffdfe2ec504d526b94d3ddc17d98fa3af541c98da649a2dfc94f0fcCMWTEy7lNfayjm_ymMFJOSI1Qdw6UsufvA.png?1680004667"
},
"title": "Getting Started with Gist: Your Day 1 Checklist",
"description": "A quick guide to help you start strong from day 1 with Gist.",
"html_text": "<p>👋 Welcome to Gist!
We understand that the first step is always the hardest, but with this guide, we hope to make the process easier for you.
Whether you are a startup or a large enterprise, we're excited to have you onboard.
This guide is based on the insights we've gathered from thousands of our successful customers, so you can be sure it's well-tested and effective.</p>",
"status": "published",
"created_at": 1193141363,
"updated_at": 1539763645,
"url": "https://help.worker.com/en/article/2-new-article"
}
}
}
}
An Article object describes the Article and contains the following fields
| Property | Type | Description |
|---|---|---|
| id | integer | The id representing the article |
| parent_id | integer | The id representing the primary_collection |
| secondary_ids | array | The array representing the ids of secondary_collection |
| default_locale | string | The default language of article |
| statistics | object | The data of the articles statistics like views_count,count of reaction , helpful and unhelpful reaction count |
| translations | object | The data of the articles in different language |
| title | string | Title of the article |
| description | string | Description of the article |
| html_text | html | Content of the article |
| status | string | Status of the article (published or draft) |
| created_at | timestamp | The time of the article was created |
| updated_at | timestamp | The time of the article was last updated |
| url | string | Url of the article |
Retrieve an Article
curl --request GET \
--url 'https://api.getgist.com/articles/2' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"article": {
"id": 2,
"parent_id": 24,
"secondary_ids": [],
"default_locale": "en",
"statistics": {
"views": 7,
"reactions": 0,
"helpful_reactions": 0,
"unhelpful_reactions": 0
},
"translations": {
"en": {
"author": {
"id": 824,
"name": "John",
"email": "[email protected]",
"avatar": "https://gist.b-cdn.net/users_profiles/2063/medium/c9297531cffdfe2ec504d526b94d3ddc17d98fa3af541c98da649a2dfc94f0fcCMWTEy7lNfayjm_ymMFJOSI1Qdw6UsufvA.png?1680004667"
},
"title": "Getting Started with Gist: Your Day 1 Checklist",
"description": "A quick guide to help you start strong from day 1 with Gist.",
"html_text": "<p>👋 Welcome to Gist!
We understand that the first step is always the hardest, but with this guide, we hope to make the process easier for you.
Whether you are a startup or a large enterprise, we're excited to have you onboard.
This guide is based on the insights we've gathered from thousands of our successful customers, so you can be sure it's well-tested and effective.</p>",
"status": "published",
"created_at": 1193141363,
"updated_at": 1539763645,
"url": "https://help.worker.com/en/article/2-new-article"
}
}
}
}
You can fetch a Article from a Workspace by sending a GET request to https://api.getgist.com/articles/{id} with id as the parameter.
An Article ID can be found by pull a list of Article using the Article API, as documented below.
Response
An Article object.
List all articles
curl --request GET \
--url https://api.getgist.com/articles \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"articles": [
{
"id": 2,
"parent_id": 24,
"secondary_ids": [],
"default_locale": "en",
"statistics": {
"views": 7,
"reactions": 0,
"helpful_reactions": 0,
"unhelpful_reactions": 0
},
"translations": {
"en": {
"author": {
"id": 824,
"name": "John",
"email": "[email protected]",
"avatar": "https://gist.b-cdn.net/users_profiles/2063/medium/c9297531cffdfe2ec504d526b94d3ddc17d98fa3af541c98da649a2dfc94f0fcCMWTEy7lNfayjm_ymMFJOSI1Qdw6UsufvA.png?1680004667"
},
"title": "Getting Started with Gist: Your Day 1 Checklist",
"description": "A quick guide to help you start strong from day 1 with Gist.",
"html_text": "<p>👋 Welcome to Gist!
We understand that the first step is always the hardest, but with this guide, we hope to make the process easier for you.
Whether you are a startup or a large enterprise, we're excited to have you onboard.
This guide is based on the insights we've gathered from thousands of our successful customers, so you can be sure it's well-tested and effective.</p>",
"status": "published",
"created_at": 1193141363,
"updated_at": 1539763645,
"url": "https://help.worker.com/en/article/2-new-article"
}
}
}
],
"page": {
"prev": "http://0.0.0.0:3013/articles?order=desc&order_by=created_at&page=1&per_page=1",
"next": "http://0.0.0.0:3013/articles?order=desc&order_by=created_at&page=3&per_page=1",
"first": "http://0.0.0.0:3013/articles?order=desc&order_by=created_at&page=1&per_page=1",
"last": "http://0.0.0.0:3013/articles?order=desc&order_by=created_at&page=78&per_page=1"
}
}
You can fetch all articles from a Workspace by sending a GET request to https://api.getgist.com/articles
The articles list is sorted by the created property and by default is ordered descending, most recently created at 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 article 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: published, or draft. Defaults to all. |
| collection_id | no | Filter by collection_id. Defaults to all. |
| author_id | no | Filter by author_id. Defaults to all. |
Returns: .
The Article list contains a pages object that indicates if more articles 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 articles in the list.
Response
A paginated list of Article object.
Create an article
Example Request
curl --request POST \
--url https://api.getgist.com/articles \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"parent_id": 2,
"secondary_ids": [1,4],
"translations": {
"en": {
"author_id": 824,
"title": "Customize the Gist Messenger to match your brand?",
"description": "Discover how to customize the launch of Gist Messenger to open chat with a simple button or link click.",
"html_text": "<p>Ever wanted to customize when and how your Gist Messenger launches? This guide will instruct you on how to make the Gist Messenger open when somebody clicks a specific button or link on your website or in your app. This functionality is great if you want to keep the chat widget hidden by default and reveal it only upon specific user interactions.</p>",
"status": "published"
},
"fr": {
"author_id": 824,
"title": "अपनी ब्रांड के साथ Gist Messenger को कस्टमाइज़ कैसे करें?",
"description": "जानें कि कैसे आप अपनी वेबसाइट या अपने ऐप में किसी विशेष बटन या लिंक क्लिक करने पर Gist Messenger को लॉन्च करने को कस्टमाइज़ कर सकते हैं।",
"html_text": "<p>क्या कभी आपने अपने Gist Messenger को कस्टमाइज़ करने की इच्छा की है? यह गाइड आपको यह बताएगा कि कैसे किसी विशेष उपयोगकर्ता प्रविष्टि पर क्लिक करने पर Gist Messenger को खोलें। यह फ़ंक्शनैलिटी बहुत उपयोगी है अगर आप चाहते हैं कि चैट विजेट डिफ़ॉल्ट रूप से छिपा रहे और उसे केवल विशेष उपयोगकर्ता प्रविष्टियों पर प्रकट करें।</p>",
"status": "published"
}
}
}'
Example Response
{
"article": {
"id": 10,
"parent_id": 24,
"secondary_ids": [1,4],
"default_locale": "fr",
"statistics": {
"views": 7,
"reactions": 0,
"helpful_reactions": 0,
"unhelpful_reactions": 0
}
"translations": {
"en": {
"author": {
"id": 824,
"name": "Saravanakumar Subramanian mallow",
"email": "[email protected]",
"avatar": "/system/users_profiles/profile_photos/000/002/063/medium/1069102.jpeg?1672898376",
},
"title": "Customize the Gist Messenger to match your brand?",
"description": "Discover how to customize the launch of Gist Messenger to open chat with a simple button or link click.",
"html_text": "<p>Ever wanted to customize when and how your Gist Messenger launches? This guide will instruct you on how to make the Gist Messenger open when somebody clicks a specific button or link on your website or in your app. This functionality is great if you want to keep the chat widget hidden by default and reveal it only upon specific user interactions.</p>",
"status": "published",
"created_at": 1193141363,
"updated_at": 1539763645,
"url": "https://help.worker.com/en/article/2-new-article"
},
"hi": {
"author": {
"id": 824,
"name": "Saravanakumar Subramanian mallow",
"email": "[email protected]",
"avatar": "/system/users_profiles/profile_photos/000/002/063/medium/1069102.jpeg?1672898376",
},
"title": "अपनी ब्रांड के साथ Gist Messenger को कस्टमाइज़ कैसे करें?",
"description": "जानें कि कैसे आप अपनी वेबसाइट या अपने ऐप में किसी विशेष बटन या लिंक क्लिक करने पर Gist Messenger को लॉन्च करने को कस्टमाइज़ कर सकते हैं।",
"html_text": "<p>क्या कभी आपने अपने Gist Messenger को कस्टमाइज़ करने की इच्छा की है? यह गाइड आपको यह बताएगा कि कैसे किसी विशेष उपयोगकर्ता प्रविष्टि पर क्लिक करने पर Gist Messenger को खोलें। यह फ़ंक्शनैलिटी बहुत उपयोगी है अगर आप चाहते हैं कि चैट विजेट डिफ़ॉल्ट रूप से छिपा रहे और उसे केवल विशेष उपयोगकर्ता प्रविष्टियों पर प्रकट करें।</p>",
"status": "published",
"created_at": 1193141363,
"updated_at": 1539763645,
"url": "https://help.worker.com/en/article/2-new-hindi"
}
}
},
"message": "Article created successfully"
}
You can create an article by submitting a POST to https://api.getgist.com/articles.
| Parameter | Required | Description |
|---|---|---|
| parent_id | no | The id of the collection |
| secondary_ids | array | The array representing the ids of secondary_collection |
| translations | yes | The object of the articles with single or multiple allowed languages |
| author_id | yes | The id of the author who create a article |
| title | yes | The title of the article |
| description | no | The description of the article |
| html_text | yes | The content of the article |
| status | yes | Status of the article (published or draft) |
Response
An Article object.
Update an article
Example Request
curl --request PATCH \
--url https://api.getgist.com/articles/10 \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"parent_id": 3,
"secondary_ids": [],
"default_locale": "en",
"translations": {
"en": {
"author_id": 824,
"title": "Customize the Gist Messenger",
"description": "Discover how to customize the launch of Gist Messenger to open chat with a simple button or link click.",
"html_text": "<p>Ever wanted to customize when and how your Gist Messenger launches? This guide will instruct you on how to make the Gist Messenger open when somebody clicks a specific button or link on your website or in your app. This functionality is great if you want to keep the chat widget hidden by default and reveal it only upon specific user interactions.</p>",
"status": "draft"
},
"fr": {
"author_id": 824,
"title": "Personnalisez le messager Gist pour correspondre à votre marque?",
"description": "Découvrez comment personnaliser le lancement du messager Gist pour ouvrir le chat avec un simple clic sur un bouton ou un lien.",
"html_text": "<p>Vous avez déjà voulu personnaliser le moment et la manière dont votre messager Gist se lance? Ce guide vous expliquera comment ouvrir le messager Gist lorsque quelqu'un clique sur un bouton ou un lien spécifique sur votre site Web ou dans votre application. Cette fonctionnalité est idéale si vous souhaitez garder le widget de chat caché par défaut et le révéler uniquement lors d'interactions utilisateur spécifiques.</p>",
"status": "published"
}
}
}'
Example Response
{
"article": {
"id": 574,
"parent_id": 24,
"secondary_ids": [],
"default_locale": "fr",
"statistics": {
"views": 7,
"reactions": 0,
"helpful_reactions": 0,
"unhelpful_reactions": 0
}
"translations": {
"hi": {
"author": {
"id": 824,
"name": "Saravanakumar Subramanian mallow",
"email": "[email protected]",
"avatar": "/system/users_profiles/profile_photos/000/002/063/medium/1069102.jpeg?1672898376",
},
"title": "अपनी ब्रांड के साथ Gist Messenger को कस्टमाइज़ कैसे करें?",
"description": "जानें कि कैसे आप अपनी वेबसाइट या अपने ऐप में किसी विशेष बटन या लिंक क्लिक करने पर Gist Messenger को लॉन्च करने को कस्टमाइज़ कर सकते हैं।",
"html_text": "<p>क्या कभी आपने अपने Gist Messenger को कस्टमाइज़ करने की इच्छा की है? यह गाइड आपको यह बताएगा कि कैसे किसी विशेष उपयोगकर्ता प्रविष्टि पर क्लिक करने पर Gist Messenger को खोलें। यह फ़ंक्शनैलिटी बहुत उपयोगी है अगर आप चाहते हैं कि चैट विजेट डिफ़ॉल्ट रूप से छिपा रहे और उसे केवल विशेष उपयोगकर्ता प्रविष्टियों पर प्रकट करें।</p>",
"status": "published",
"created_at": 1193141363,
"updated_at": 1539763645,
"url": "https://help.worker.com/en/article/2-article-hindi"
},
"en": {
"author": {
"id": 824,
"name": "Saravanakumar Subramanian mallow",
"email": "[email protected]",
"avatar": "/system/users_profiles/profile_photos/000/002/063/medium/1069102.jpeg?1672898376",
},
"title": "Customize the Gist Messenger",
"description": "Discover how to customize the launch of Gist Messenger to open chat with a simple button or link click.",
"html_text": "<p>Ever wanted to customize when and how your Gist Messenger launches? This guide will instruct you on how to make the Gist Messenger open when somebody clicks a specific button or link on your website or in your app. This functionality is great if you want to keep the chat widget hidden by default and reveal it only upon specific user interactions.</p>",
"status": "draft",
"created_at": 1193141363,
"updated_at": 1539763645,
"url": "https://help.worker.com/en/article/2-article-english"
},
"fr": {
"author": {
"id": 824,
"name": "Saravanakumar Subramanian mallow",
"email": "[email protected]",
"avatar": "/system/users_profiles/profile_photos/000/002/063/medium/1069102.jpeg?1672898376"
},
"title": "Personnalisez le messager Gist pour correspondre à votre marque?",
"description": "Découvrez comment personnaliser le lancement du messager Gist pour ouvrir le chat avec un simple clic sur un bouton ou un lien.",
"html_text": "<p>Vous avez déjà voulu personnaliser le moment et la manière dont votre messager Gist se lance? Ce guide vous expliquera comment ouvrir le messager Gist lorsque quelqu'un clique sur un bouton ou un lien spécifique sur votre site Web ou dans votre application. Cette fonctionnalité est idéale si vous souhaitez garder le widget de chat caché par défaut et le révéler uniquement lors d'interactions utilisateur spécifiques.</p>",
"status": "published",
"created_at": 1193141363,
"updated_at": 1539763645,
"url": "https://help.worker.com/en/article/2-article-french"
}
}
},
"message": "Article updated successfully"
}
You can update an article by submitting a PATCH to https://api.getgist.com/articles/{id} along with the article id.
| Parameter | Required | Description |
|---|---|---|
| parent_id | no | The id of the collection |
| translations | yes | The object of the articles with single or multiple allowed languages |
| author_id | yes | The id of the author who create a article |
| title | yes | The title of the article |
| description | no | The description of the article |
| html_text | yes | The content of the article |
| status | yes | Status of the article (published or draft) |
Response
An Article object.
Search an articles
Example Request
curl --request PATCH \
--url https://api.getgist.com/articles/search \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{"search_text": "quick guide", "locale": "en"'}'
Example Response
{
"articles": [
{
"id": 2,
"parent_id": 24,
"secondary_ids": [],
"default_locale": "en",
"statistics": {
"views": 7,
"reactions": 0,
"helpful_reactions": 0,
"unhelpful_reactions": 0
},
"translations": {
"en": {
"author": {
"id": 824,
"name": "John",
"email": "[email protected]",
"avatar": "https://gist.b-cdn.net/users_profiles/2063/medium/c9297531cffdfe2ec504d526b94d3ddc17d98fa3af541c98da649a2dfc94f0fcCMWTEy7lNfayjm_ymMFJOSI1Qdw6UsufvA.png?1680004667"
},
"title": "Getting Started with Gist: Your Day 1 Checklist",
"description": "A quick guide to help you start strong from day 1 with Gist.",
"html_text": "<p>👋 Welcome to Gist!
We understand that the first step is always the hardest, but with this guide, we hope to make the process easier for you.
Whether you are a startup or a large enterprise, we're excited to have you onboard.
This guide is based on the insights we've gathered from thousands of our successful customers, so you can be sure it's well-tested and effective.</p>",
"status": "published",
"created_at": 1193141363,
"updated_at": 1539763645,
"url": "https://help.worker.com/en/article/2-new-article"
}
}
}
],
"page": {
"prev": "http://0.0.0.0:3013/articles?order=desc&order_by=created_at&page=1&per_page=1",
"next": "http://0.0.0.0:3013/articles?order=desc&order_by=created_at&page=3&per_page=1",
"first": "http://0.0.0.0:3013/articles?order=desc&order_by=created_at&page=1&per_page=1",
"last": "http://0.0.0.0:3013/articles?order=desc&order_by=created_at&page=78&per_page=1"
}
}
You can fetch all article related to the search text form a Workspace by sending a GET request to https://api.getgist.com/articles/search_articles
| Parameter | Required | Description |
|---|---|---|
| search_text | yes | Filter the article by given string. |
| locale | no | Filter the article from given locale. Defaults to default locale. |
| 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 article 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 |
Delete an articles
Example Request
curl --request DELETE \
--url https://api.getgist.com/articles/10 \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
Example Response
{
"message": "Article deleted successfully."
}
You can delete an article form a Workspace by sending a DELETE request to https://api.getgist.com/articles/{id} along with the article id
Knowledgebase setting
Example Request
curl --request GET \
--url https://api.getgist.com/articles/settings \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
Example Response
{
"knowledgebase_setting": {
"site_visibility": true,
"sub_domain": "y4r9vuvz-domain",
"custom_domain": null,
"show_messenger": true,
"language": "en",
"seo_index": true,
"additional_languages": [
{
"code": "es",
"visibility": false
},
{
"code": "ru",
"visibility": false
}
],
"updated_at": 1139234745,
"translations": {
"en": {
"logo": "https://gist-testing.s3.amazonaws.com/knowledgebase_settings_image/logo/9eb59e846ab2ea61fffa8860c08561e92f5dc21c0b59cc3d040800b4e0a4b00aScreenshot%2B2024-02-20%2Bat%2B16.52.29.png",
"footer": [
{
"link": "www.engl",
"title": "english. dfg"
}
],
"favicon": "https://gist-testing.s3.amazonaws.com/knowledgebase_settings_image/favicon/fa3ebc563ce7479770fbdb4751bc769928a8a5110749189d8e3c073b38cde44dScreenshot%2B2024-02-20%2Bat%2B16.52.29.png",
"fb_link": "www.facebook.com/facebook link",
"bg_image": "",
"bg_value": "#83e181",
"og_title": "Open graph title",
"seo_index": true,
"text_link": "Company website CTA text",
"homepage_url": "mycompanywebsite.com",
"twitter_link": "www.twitter.com/twitter link",
"linkedin_link": "www.linkedin.com/linkedln link",
"footer_message": "Footer text",
"homepage_title": "Knowledge base title",
"og_description": "Open graph description",
"seo_description": "Meta description",
"site_description": "Welcome message in Knowledgebase",
"knowledge_base_name": "Knowledge Base title in English",
"background_color_type": "solid"
}
}
}
}
You can fetch Knowledgebase setting of your Workspace by sending a GET request to https://api.getgist.com/articles/settings
Response
A Knowledgebase setting object.
Collections
Collections are groups of related articles in project documentation. They organize information by topic, feature, or user need, making it easier for users to find relevant content quickly.
The Collection object
Example Response
{
"collection": {
"id": 13,
"parent_id": null,
"default_locale": "fr",
"created_at": 1493141363,
"updated_at": 1539763645,
"translations": {
"en": {
"name": "Getting Started",
"description": "Everything you need to know to get started with Gist",
"icon": "fal fa-laptop-code",
"url": "https://help.worker.com/en/collection/2-getting-started"
}
"hi": {
"name": "शुरुआत करना",
"description": "के साथ शुरू करने के लिए आपको सभी आवश्यक जानकारी",
"icon": "fal fa-laptop-code",
"url": "https://help.worker.com/hi/collection/2-शुरुआत-करना"
}
}
}
}
A Collection object describes the Collection and contains the following fields
| Property | Type | Description |
|---|---|---|
| id | string | The id representing the collection |
| parent_id | integer | The id representing the parent collection id |
| default_locale | string | The default language of collection |
| created_at | timestamp | The time the collection was created |
| updated_at | timestamp | The time the contact was updated |
| translations | object | The data of the collection in different language |
| name | string | Name of the collection |
| description | string | Description of the collection |
| icon | string | Icon of the collection |
Retrieve a Collection
curl --request GET \
--url 'https://api.getgist.com/collections/2' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"collection": {
"id": 13,
"parent_id": null,
"default_locale": "fr",
"created_at": 1493141363,
"updated_at": 1539763645,
"translations": {
"en": {
"name": "Getting Started",
"description": "Everything you need to know to get started with Gist",
"icon": "fal fa-laptop-code",
"url": "https://help.worker.com/en/collection/13-getting-started"
}
"hi": {
"name": "शुरुआत करना",
"description": "के साथ शुरू करने के लिए आपको सभी आवश्यक जानकारी",
"icon": "fal fa-laptop-code",
"url": "https://help.worker.com/hi/collection/13-शुरुआत-करना"
}
}
}
}
You can fetch a Collection from a Workspace by sending a GET request to https://api.getgist.com/collections/{id} along with collection id as the parameter.
A Collection id can be found by pull a list of Collection using the Collection API, as documented below.
Response
A Collection object.
List all collections
curl --request GET \
--url https://api.getgist.com/collections \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"collections": [
{
"id": 13,
"parent_id": null,
"default_locale": "fr",
"created_at": 1493141363,
"updated_at": 1539763645,
"translations": {
"en": {
"name": "Getting Started",
"description": "Everything you need to know to get started with Gist",
"icon": "fal fa-laptop-code",
"url": "https://help.worker.com/en/collection/13-getting-started"
}
"hi": {
"name": "शुरुआत करना",
"description": "के साथ शुरू करने के लिए आपको सभी आवश्यक जानकारी",
"icon": "fal fa-laptop-code",
"url": "https://help.worker.com/hi/collection/13-शुरुआत-करना"
}
}
},
{
"id": 12,
"parent_id": null,
"default_locale": "fr",
"created_at": 1293141363,
"updated_at": 13439763645,
"translations": {
"en": {
"name": "Messenger",
"description": "Setting up and customizing your Messenger to start chatting with customers.",
"icon": "fal fa-laptop-code",
"url": "https://help.worker.com/en/collection/12-messenger"
}
"hi": {
"name": "संदेशक",
"description": "अपने संदेशक को सेटअप करें और अपने ग्राहकों के साथ चैटिंग शुरू करने के लिए अनुकूलित करें।",
"icon": "fal fa-laptop-code",
"url": "https://help.worker.com/hi/collection/12-संदेशक"
}
}
}
],
"page": {
"first": "http://0.0.0.0:3013/collections?order=desc&order_by=created_at&page=1&per_page=50",
"last": "http://0.0.0.0:3013/collections?order=desc&order_by=created_at&page=1&per_page=50"
}
}
You can fetch all Collections from Workspace by sending a GET request to https://api.getgist.com/collections
The collections list is sorted by the created property and by default is ordered descending, most recently created at 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 collection 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 |
Returns: .
The Collection list contains a pages object that indicates if more collections 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 collections in the list.
Response
A paginated list of Collections object.
Create an collection
Example Request
curl --request POST \
--url https://api.getgist.com/collections \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"parent_id": 79,
"translations": {
"fr": {
"name": "Emma - Le bot AI de Gist",
"description": "Offre un support instantané et proactif à grande échelle",
"icon": "fal fa-folder"
},
"en": {
"name": "Emma - Gist AI Bot",
"description": "Offer instant and proactive support at scale",
"icon": "fal fa-folder"
}
}
}'
Example Response
{
"collection": {
"id": 81,
"parent_id": 79,
"default_locale": "fr",
"created_at": 1493141363,
"updated_at": 1539763645,
"translations": {
"fr": {
"name": "Emma - Le bot AI de Gist",
"description": "Offre un support instantané et proactif à grande échelle",
"icon": "fal fa-folder",
"url": "https://help.worker.com/fr/collection/81-emma-le-bot-ai-de-gist"
},
"en": {
"name": "Emma - Gist's AI Bot",
"description": "Offer instant and proactive support at scale",
"icon": "fal fa-folder",
"url": "https://help.worker.com/en/collection/81-emma-gist-ai-bot"
}
}
},
"message": "Collection created successfully"
}
You can create an collection by submitting a POST to https://api.getgist.com/collections.
| Parameter | Required | Description |
|---|---|---|
| parent_id | no | The id of the parent collection id |
| translations | yes | The object of the collections with single or multiple allowed languages |
| name | yes | The name of the collection |
| description | yes | The description of the collection |
| icon | yes | The icon of the collection |
Response
An Collection object.
Update an collection
Example Request
curl --request POST \
--url https://api.getgist.com/collections \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"parent_id": 85,
"translations": {
"en": {
"name": "messenger",
"description": "Offer instant and proactive support at scale",
"icon": "fal fa-folder"
},
"hi": {
"name": "मैसेंजर",
"description": "स्केल पर तुरंत और सक्रिय समर्थन प्रदान करें",
"icon": "fal fa-folder"
}
}
}'
Example Response
{
"collection": {
"id": 81,
"parent_id": 85,
"default_locale": "fr",
"created_at": 1493141363,
"updated_at": 1539763645,
"translations": {
"fr": {
"name": "Emma - Le bot AI de Gist",
"description": "Offre un support instantané et proactif à grande échelle",
"icon": "fal fa-folder",
"url": "https://help.worker.com/fr/collection/81-emma-le-bot-ai-de-gist"
},
"en": {
"name": "messenger",
"description": "Offer instant and proactive support at scale",
"icon": "fal fa-folder",
"url": "https://help.worker.com/en/collection/81-emma-gist-ai-bot"
},
"hi": {
"name": "मैसेंजर",
"description": "स्केल पर तुरंत और सक्रिय समर्थन प्रदान करें",
"icon": "fal fa-folder",
"url": "https://help.worker.com/hi/collection/81-मैसेंजर"
}
}
},
"message": "Collection updated successfully"
}
You can update a collection by submitting a POST to https://api.getgist.com/collections/{id} along with collection id.
| Parameter | Required | Description |
|---|---|---|
| parent_id | no | The id of the parent collection id |
| translations | no | The object of the collections with single or multiple allowed languages |
| name | no | The name of the collection |
| description | no | The description of the collection |
| icon | no | The icon of the collection |
Response
An Collection object.
Delete a Collection
Example Request
curl --request DELETE \
--url https://api.getgist.com/Collections/10 \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
Example Response
{
"message": "Collection deleted successfully."
}
You can delete an Collection form a Workspace by sending a DELETE request to https://api.getgist.com/collections/{id} along with the collection id
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
emailis provided in the HTTP request, the contact will be created as a Lead. - If both
user_idandemailare 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
idhas matched - theuser_idandemailwill be updated if they are included in the request. - if
user_idhas matched - theemailwill be updated, theidwill not be updated. - if
emailhas matched - if nouser_idis set on the matched contact, thenuser_idwill be set to the value sent in the request, theidis not updated. Note that this will change the Contact’s type from Lead to User. - if
emailhas matched and the matched contact has auser_idvalue - theuser_idof the matched contact will be set to the value sent in the request, theidis 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"
]
}
]
}'
Example Response
{
"status": "QUEUED",
"queued_contacts": 1000,
"batch_id": "0641fbdd-f62f-4c2c-ba02-3a83d5d11ac9",
}
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 status of the batch import, no. of contacts queued and the batch_id
- 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.
Get status of the batch import
Example Request
$ curl --request GET \
--url https://api.getgist.com/contacts/batch/<batch_id> \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"status": "COMPLETED", // can also be "IN_PROGRESS" OR "QUEUED"
"imported_contacts": 972, // will be present only when the status is "COMPLETED"
"errors": [], // will be present only when the status is "COMPLETED"
}
When you send request to create a batch of contacts via Batch API, you will get the batch_id. Now you can use that batch_id and get the status of the import
- Returns the status of the batch import, no. of contacts imported without errors and array of errors if any
- The status can be QUEUED, IN_PROGRESS or COMPLETED
Note:
- This endpoint will check the status of the queued contact.
- If any of the contact properties has invalid data, for example, text passed in place of numeric property, the other contacts will be created and the errors array will have the failed email IDs along with the reason.
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
An event is a data point that represents an interaction between a user and your product. Events can be a wide range of interactions. For example, a music service might track a new user signing up for an account or a user playing a song as an event.
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.
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
As your forms site collect data, Gist instantly stores it all in a built-in database, so you can retrieve this data anytime.
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
A drip campaign uses a series of pre-planned, automated emails to encourage customer onboarding, engagement and retention.
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/nrrjryb4/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/nrrjryb4/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/nrrjryb4/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/nrrjryb4/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/nrrjryb4/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/nrrjryb4/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/nrrjryb4/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/nrrjryb4/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.
Subscription Types
A subscription type lets customers easily opt out of non-essential communications without missing what’s important to them.
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
}
| 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.
Conversations
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 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
}
}
}
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
Teams are groups of teammates in Gist.
The team object
Example Response
{
"id": 814865,
"name": "Support Team",
"teammate_ids": [
34355
]
}
| 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
Teammates are people in your organization who have a registered Gist account and have access to your workspace.
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
}
| 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.
Workspace meta
Get the meta data of the current workspace. This can be used to get the workspace ID that the token was created for. Access tokens generated using oAuth also include the scopes and app ID that the token is associated with.
The token object
An expires_in time of 0, may indicate no expiration on the token. Any token generated through the oAuth flow in the developer platform will stay valid until app is uninstalled or deleted.
Example Response
{
"workspace_id": "nrrjryb4",
"token_type": "Bearer",
"expires_in": 0,
"app_id": 24,
"scope": "read_contact"
"created_at": 1652960176,
}
| Property | Type | Description |
|---|---|---|
| workspace_id | string | The workspace ID the token was created for |
| app_id | string | The app id associated with the token. |
| token_type | string | The type of authentication. |
| expires_in | string | The UNIX timestamp of when the token expires. |
| created_at | string | The UNIX timestamp of when the token was generated. |
| scope | string | A space-separated list of oAuth scopes on the token. |
Retrieve workspace meta
Example Request
curl --request GET \
--url https://api.getgist.com/token/info \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
You can fetch the details of a single team.
GET https://api.getgist.com/token/info
Response
A Token object.
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
This section describes the JSON format of the data sent via individual webhooks.
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",
}
}
E-Commerce
When selling online, there are many activities your customers (and potential customers) can take. Passing the details of these activities to Gist helps enable a deeper content personalization through workflow automation.
Stores
The store object
Example Response
{
"store_id": 97135842,
"name": "Voice Out",
"domain": "https://example.com",
"status": "connected",
"currency_code": "USD",
"abandon_cart_interval": 1,
"contact_tags": "ecommerce contact,first store contact"
}
A Store object describes the store. It represents a link between a Gist workspace and a store/account in an external service such as Shopify.
It contains the following fields:
| Property | Type | Required | Description |
|---|---|---|---|
| store_id | string | no | The id representing the store generated by Gist. |
| name | string | yes | The store name of the ecommerce site or domain as the store name if name not presence |
| domain | string | yes | The domain of the ecommerce site. |
| status | string | no | Active status of the store. We trigger the automations and workflows for the connected stores only. Default is disconnected |
| currency_code | string | yes | The three-letter ISO 4217 code for the currency that the store accepts. |
| abandon_cart_interval | number | yes | The time before a cart is considered abandoned. This triggers the abandon cart automations. Defaults to 1 hour. |
| contact_tags | string | no | Name of the tag that will be applied on WooCommerce contacts(s). Separate multiple tags with commas |
Create a store
Example Request
$ curl --request POST \
--url https://api.getgist.com/ecommerce/stores \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"name": "Voice Out",
"domain": "https://example.com",
"currency_code": "USD",
"status": "disconnected",
"abandon_cart_interval": 1,
"contact_tags": "ecommerce contact,first store contact"
}'
Example Response
{
"ecommerce_store": {
"store_id": 97135842,
"name": "Voice Out",
"domain": "https://example.com",
"status": "disconnected",
"currency_code": "USD",
"abandon_cart_interval": 1,
"contact_tags": "ecommerce contact,first store contact"
}
}
Add a new store to your Gist workspace.
POST https://api.getgist.com/ecommerce/stores
Response
A Store object.
Update a store
Example Request
$ curl --request PATCH \
--url https://api.getgist.com/ecommerce/stores/97135842 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"name": "Voice Out",
"domain": "https://example.com",
"currency_code": "USD",
"status": "connected",
"abandon_cart_interval": 1,
"contact_tags": "ecommerce contact,first store contact"
}'
Example Response
{
"ecommerce_store": {
"store_id": 97135842,
"name": "Voice Out",
"domain": "https://example.com",
"status": "connected",
"currency_code": "USD",
"abandon_cart_interval": 1,
"contact_tags": "ecommerce contact,first store contact"
}
}
Update a store in your Gist workspace.
PATCH https://api.getgist.com/ecommerce/stores/{store_id}
Response
A Store object.
Retrieve a store
Example Request
$ curl --request GET \
--url https://api.getgist.com/ecommerce/stores/97135842 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"ecommerce_store": {
"store_id": 97135842,
"name": "Voice Out",
"domain": "https://example.com",
"status": "disconnected",
"currency_code": "USD",
"abandon_cart_interval": 1,
"contact_tags": "ecommerce contact,first store contact"
}
}
Retrieve a store from your Gist workspace.
GET https://api.getgist.com/ecommerce/stores/{store_id}
Response
A Store object.
List all stores
Example Request
$ curl --request GET \
--url https://api.getgist.com/ecommerce/stores \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"ecommerce_stores": [
{
"store_id": 97135842,
"name": "Voice Out",
"domain": "https://example.com",
"status": "connected",
"currency_code": "USD",
"abandon_cart_interval": 1,
"contact_tags": "ecommerce contact,first store contact"
},
{
"store_id": 97135841,
"name": "Flower Day",
"domain": "https://flowerday.com",
"status": "disconnected",
"currency_code": "USD",
"abandon_cart_interval": 1,
"contact_tags": "ecommerce contact,first store contact"
}
]
}
Retrieve all stores from your Gist workspace.
GET https://api.getgist.com/ecommerce/stores
Response
A list of Store objects.
Customers
The customer object
Example Response
{
"customer_id": "1234",
"email_address": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"billing_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
},
"shipping_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
}
}
Add Customers to your Store to track their orders and to view E-Commerce data for your Gist segments and campaigns. Each Customer is connected to a Gist Contact, so adding a Customer can also add or update the attached contact.
It contains the following fields:
| Property | Type | Required | Description |
|---|---|---|---|
| customer_id | string | yes | A unique, internal id for the customer (generally the primary key generated by the ecommerce platform) |
| email_address | string | yes | The customer's email address. |
| first_name | string | no | The customer's first name. |
| last_name | string | no | The customer's last name. |
| billing_address | object | no | The customer's billing address. |
| shipping_address | object | no | The customer's shipping address. |
The billing_address and shipping_address object has the following fields:
| Property | Type | Required | Description |
|---|---|---|---|
| address1 | string | no | The mailing address of the customer. |
| address2 | string | no | An additional field for the customer's mailing address. |
| city | string | no | The city the customer is located in. |
| state | string | no | The customer's state name or normalized province. |
| postcode | string | no | The customer's postal or zip code. |
| country | string | no | The customer's country. |
| phone | string | no | The customer's phone number. |
Create a customer
Example Request
$ curl --request POST \
--url https://api.getgist.com/ecommerce/stores/12/customers \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"customer_id": "1234",
"email_address": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"billing_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
},
"shipping_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
}
}'
Example Response
{
"ecommerce_customer": {
"customer_id": "1234",
"email_address": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"billing_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
},
"shipping_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
}
}
}
Add a new customer to your ecommerce store.
POST https://api.getgist.com/ecommerce/stores/{store_id}/customers
Response
A Customer object.
Update a customer
Example Request
$ curl --request PATCH \
--url https://api.getgist.com/ecommerce/stores/12/customers/1234 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"email_address": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"billing_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
},
"shipping_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
}
}'
Example Response
{
"ecommerce_customer": {
"customer_id": "1234",
"email_address": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"billing_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
},
"shipping_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
}
}
}
Update a customer in your ecommerce store.
PATCH https://api.getgist.com/ecommerce/stores/{store_id}/customers/{customer_id}
Response
A Customer object.
Retrieve a customer
Example Request
$ curl --request GET \
--url https://api.getgist.com/ecommerce/stores/12/customers/1234 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"ecommerce_customer": {
"customer_id": "1234",
"email_address": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"billing_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
},
"shipping_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
}
}
}
Retrieve a customer from your Gist workspace.
GET https://api.getgist.com/ecommerce/stores/{store_id}/customers/{customer_id}
Response
A Customer object.
Products
The product object
Example Response
{
"product_id": "1234",
"title": " LG - Washing Machine BT12",
"description": "Fully Automatic Front Load Washing Machines have Great Wash Quality with very less running cost",
"product_url": "https://example.com/product/premium-quality-19/",
"vendor": "LG",
"image_url": "https://store.example.com/image/1234/1234",
"price": 30000,
"sku": "WAS-F12",
"inventory_quantity": 8,
"backorders": "true",
"categories": [
{ "category_id": 1, "name": "Shoes" },
{ "category_id": 2, "name": "Vitamins" }
],
"product_published_at": "2017-03-22T16:28:02"
}
E-commerce items for sale in your store need to be created as Products so you can add the items to a Cart or an Order. You can have a Product without variant which means Product doesn't require variants for main products.
It contains the following fields:
| Property | Type | Required | Description |
|---|---|---|---|
| product_id | string | yes | A unique, internal id for the product (generally the primary key generated by the ecommerce platform). |
| title | string | yes | The title of a product. |
| description | string | no | The description of a product. |
| product_url | string | no | The URL for a product. |
| vendor | string | no | The vendor for a product. |
| image_url | string | no | The image URL for a product. |
| price | string | no | The price of a product. |
| sku | string | no | The stock keeping unit (SKU) of a product. |
| inventory_quantity | integer | no | The currently available inventory of the product. |
| backorders | string | no | The backorders of a product. |
| categories | array | no | An array of categories associated with the product (e.g. shoes, vitamins, books, videos). |
| product_published_at | timestamp | no | The date and time the product was published. |
Create a product
Example Request
$ curl --request POST \
--url https://api.getgist.com/ecommerce/stores/12/products \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"product_id": "1234",
"title": " LG - Washing Machine BT12",
"description": "Fully Automatic Front Load Washing Machines have Great Wash Quality with very less running cost",
"product_url": "https://example.com/product/premium-quality-19/",
"vendor": "LG",
"image_url": "https://store.example.com/image/1234/1234",
"price": 30000,
"sku": "WAS-F12",
"inventory_quantity": 8,
"backorders": "true",
"categories": [1, 3],
"product_published_at": "2017-03-22T16:28:02"
}'
Example Response
{
"ecommerce_product": {
"product_id": "1234",
"title": " LG - Washing Machine BT12",
"description": "Fully Automatic Front Load Washing Machines have Great Wash Quality with very less running cost",
"product_url": "https://example.com/product/premium-quality-19/",
"vendor": "LG",
"image_url": "https://store.example.com/image/1234/1234",
"price": 30000,
"sku": "WAS-F12",
"inventory_quantity": 8,
"backorders": "true",
"categories": [
{ "category_id": 1, "name": "Shoes" },
{ "category_id": 2, "name": "Vitamins" }
],
"product_published_at": "2017-03-22T16:28:02"
},
}
}
Add a new product to your ecommerce store.
POST https://api.getgist.com/ecommerce/stores/{store_id}/products
Response
A Product object.
Update a product
Example Request
$ curl --request PATCH \
--url https://api.getgist.com/ecommerce/stores/12/products/1234 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"title": " LG - Washing Machine BT12",
"description": "Fully Automatic Front Load Washing Machines have Great Wash Quality with very less running cost",
"product_url": "https://example.com/product/premium-quality-19/",
"vendor": "LG",
"image_url": "https://store.example.com/image/1234/1234",
"price": 30000,
"sku": "WAS-F12",
"inventory_quantity": 8,
"backorders": "true",
"categories": [1, 3],
"product_published_at": "2017-03-22T16:28:02"
}'
Example Response
{
"ecommerce_product": {
"product_id": "1234",
"title": " LG - Washing Machine BT12",
"description": "Fully Automatic Front Load Washing Machines have Great Wash Quality with very less running cost",
"product_url": "https://example.com/product/premium-quality-19/",
"vendor": "LG",
"image_url": "https://store.example.com/image/1234/1234",
"price": 30000,
"sku": "WAS-F12",
"inventory_quantity": 8,
"backorders": "true",
"categories": [
{ "category_id": 1, "name": "Shoes" },
{ "category_id": 2, "name": "Vitamins" }
],
"product_published_at": "2017-03-22T16:28:02"
},
}
}
Update a product in your ecommerce store.
PATCH https://api.getgist.com/ecommerce/stores/{store_id}/products/{product_id}
Response
A Product object.
Retrieve a product
Example Request
$ curl --request GET \
--url https://api.getgist.com/ecommerce/stores/12/products/1234 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"ecommerce_product": {
"product_id": "1234",
"title": " LG - Washing Machine BT12",
"description": "Fully Automatic Front Load Washing Machines have Great Wash Quality with very less running cost",
"product_url": "https://example.com/product/premium-quality-19/",
"vendor": "LG",
"image_url": "https://store.example.com/image/1234/1234",
"price": 30000,
"sku": "WAS-F12",
"inventory_quantity": 8,
"backorders": "true",
"categories": [
{ "category_id": 1, "name": "Shoes" },
{ "category_id": 2, "name": "Vitamins" }
],
"product_published_at": "2017-03-22T16:28:02"
},
}
}
Retrieve a product from your Gist workspace.
GET https://api.getgist.com/ecommerce/stores/{store_id}/products/{product_id}
Response
A Product object.
Product Variants
The Product variant object
Example Response
{
"product_id": "1234",
"product_variant_id": "1234",
"title": " LG - Washing Machine BT12",
"description": "Fully Automatic Front Load Washing Machines have Great Wash Quality with very less running cost",
"product_url": "https://example.com/product/premium-quality-19/",
"vendor": "LG",
"image_url": "https://store.example.com/image/1234/1234",
"price": 30000,
"sku": "WAS-F12",
"inventory_quantity": 8,
"backorders": "true"
}
A variant can be added to a Product resource to represent one version of a product with several options.
It contains the following fields:
| Property | Type | Required | Description |
|---|---|---|---|
| product_id | string | yes | A unique, internal id for the product (generally the primary key generated by the ecommerce platform). |
| product_variant_id | string | yes | A unique identifier for the specific product variant from the provider. For example, a t-shirt may have one product_id, but several product_variant_ids for sizes and colors. If a product does not have multiple variants and you do not have a variant identifier in your system, repeat the product_id here. |
| title | string | yes | The title of a product variant. |
| description | string | no | The description of a product variant. |
| product_url | string | no | The URL for a product variant. |
| vendor | string | no | The vendor for a product. |
| image_url | string | no | The image URL for a product variant. |
| price | string | no | The price of a product variant. |
| sku | string | no | The stock keeping unit (SKU) of a product variant. |
| inventory_quantity | integer | no | The currently available inventory of the product. |
| backorders | string | no | The backorders of a product variant. |
Create a Product variant
Example Request
$ curl --request POST \
--url https://api.getgist.com/ecommerce/stores/12/products/1234/variants \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"product_variant_id": "1234",
"title": " LG - Washing Machine BT12",
"description": "Fully Automatic Front Load Washing Machines have Great Wash Quality with very less running cost",
"product_url": "https://example.com/product/premium-quality-19/",
"vendor": "LG",
"image_url": "https://store.example.com/image/1234/1234",
"price": 30000,
"sku": "WAS-F12",
"inventory_quantity": 8,
"backorders": "true"
}'
Example Response
{
"ecommerce_product_variant": {
"product_variant_id": "1234",
"title": " LG - Washing Machine BT12",
"description": "Fully Automatic Front Load Washing Machines have Great Wash Quality with very less running cost",
"product_url": "https://example.com/product/premium-quality-19/",
"vendor": "LG",
"image_url": "https://store.example.com/image/1234/1234",
"price": 30000,
"sku": "WAS-F12",
"inventory_quantity": 8,
"backorders": "true"
}
}
}
Add a new product variant in ecommerce store.
POST https://api.getgist.com/ecommerce/stores/{store_id}/products/{product_id}/variants
Response
A Product variant object.
Update a Product variant
Example Request
$ curl --request PATCH \
--url https://api.getgist.com/ecommerce/stores/12/products/1234/variants/1234 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"title": " LG - Washing Machine BT12",
"description": "Fully Automatic Front Load Washing Machines have Great Wash Quality with very less running cost",
"product_url": "https://example.com/product/premium-quality-19/",
"vendor": "LG",
"image_url": "https://store.example.com/image/1234/1234",
"price": 30000,
"sku": "WAS-F12",
"inventory_quantity": 8,
"backorders": "true"
}'
Example Response
{
"ecommerce_product_variant": {
"product_variant_id": "1234",
"title": " LG - Washing Machine BT12",
"description": "Fully Automatic Front Load Washing Machines have Great Wash Quality with very less running cost",
"product_url": "https://example.com/product/premium-quality-19/",
"vendor": "LG",
"image_url": "https://store.example.com/image/1234/1234",
"price": 30000,
"sku": "WAS-F12",
"inventory_quantity": 8,
"backorders": "true"
}
}
}
Update a product variant in your ecommerce store.
PATCH https://api.getgist.com/ecommerce/stores/{store_id}/products/{product_id}/variants/{product_variant_id}
Response
A Product variant object.
Retrieve a Product variant
Example Request
$ curl --request GET \
--url https://api.getgist.com/ecommerce/stores/12/products/1234/variants/1234 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"ecommerce_product_variant": {
"product_variant_id": "1234",
"title": " LG - Washing Machine BT12",
"description": "Fully Automatic Front Load Washing Machines have Great Wash Quality with very less running cost",
"product_url": "https://example.com/product/premium-quality-19/",
"vendor": "LG",
"image_url": "https://store.example.com/image/1234/1234",
"price": 30000,
"sku": "WAS-F12",
"inventory_quantity": 8,
"backorders": "true"
}
}
}
Retrieve a product variant from your Gist workspace.
GET https://api.getgist.com/ecommerce/stores/{store_id}/products/{product_id}/variants/{variant_id}
Response
A Product variant object.
Product Categories
The product category object
Example Response
{
"category_id": 1234,
"name": "Electronics"
}
It contains the following fields:
| Property | Type | Required | Description |
|---|---|---|---|
| category_id | string | yes | A unique, internal id for the product category (generally the primary key generated by the ecommerce platform) |
| name | string | yes | The name of a product category. |
Create a product category
Example Request
$ curl --request POST \
--url https://api.getgist.com/ecommerce/stores/12/categories \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"category_id": 12,
"name": "Electronics"
}'
Example Response
{
"ecommerce_category": {
"category_id": 1234,
"name": "Electronics"
}
}
Add a new product category to your ecommerce store.
POST https://api.getgist.com/ecommerce/stores/{store_id}/categories
Response
A Product Category object.
Update a product category
Example Request
$ curl --request PATCH \
--url https://api.getgist.com/ecommerce/stores/12/categories/1234 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"name": "Electronics"
}'
Example Response
{
"ecommerce_category": {
"category_id": 1234,
"name": "Electronics"
}
}
Update a product category in your ecommerce store.
PATCH https://api.getgist.com/ecommerce/stores/{store_id}/categories/{category_id}
Response
A Product Category object.
Retrieve a product category
Example Request
$ curl --request GET \
--url https://api.getgist.com/ecommerce/stores/12/categories/1234 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"ecommerce_category": {
"category_id": 1234,
"name": "Electronics"
}
}
Retrieve a product category from your Gist workspace.
GET https://api.getgist.com/ecommerce/stores/{store_id}/categories/{category_id}
Response
A Product Category object.
Carts
Passing in all required fields for Cart API will enable "Abandoned a cart" action in your Gist workflows. Leverage that content in our Visual Email Builder to send Cart Abandonment emails containing item details.
Note that Cart Activity will show up on a contact's activity timeline as either a "Created a cart" or "Updated a cart" event.
The cart object
Example Response
{
"ecommerce_cart": {
"customer": {
"customer_id": "1234",
"email_address": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"billing_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
},
"shipping_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
}
}
"checkout_url": "https://example.com/cart/690933842",
"currency_code": "USD",
"order_total": 234,
"discount_total": 12,
"created_at": "2017-03-22T16:28:02",
"updated_at": "2017-03-22T16:28:02",
"line_items": [
{
"product_id": "12",
"product_variant_id": "24",
"quantity": 3,
"price": 2000
},
{
"product_id": "1",
"product_variant_id": "1",
"quantity": 3,
"price": 2000
}
]
}
}
It contains the following fields:
| Property | Type | Required | Description |
|---|---|---|---|
| customer_id | string | yes | A unique, internal id for the customer (generally the primary key generated by the ecommerce platform) |
| checkout_url | string | no | The URL for the cart. This parameter is required for Abandoned Cart automations. |
| currency_code | string | yes | The three-letter ISO 4217 code for the currency that the cart uses. |
| order_total | number | yes | The order total for the cart. |
| discount_total | number | no | The discount total for the cart. |
| line_items | object[] | yes | An array of the cart's line items. |
| created_at | date | no | The date and time the cart was created in ISO 8601 format. This parameter is used for Abandoned Cart automations. |
| updated_at | date | no | The date and time the cart was last updated in ISO 8601 format. This parameter is used for Abandoned Cart automations. |
The line item object has the following fields:
| Property | Type | Required | Description |
|---|---|---|---|
| product_id | string | no | A unique identifier for the product associated with the cart line item. |
| product_variant_id | string | no | A unique identifier for the product variant associated with the cart line item. |
| quantity | number | no | The quantity of a cart line item. |
| price | number | no | The price of a cart line item. |
Create or Update a cart
Example Request
$ curl --request POST \
--url https://api.getgist.com/ecommerce/stores/12/customers/1234/cart \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"checkout_url": "https://example.com/cart/690933842",
"currency_code": "USD",
"order_total": 234,
"discount_total": 12,
"created_at": "2017-03-22T16:28:02",
"updated_at": "2017-03-22T16:28:02",
"line_items": [
{
"product_id": "12",
"product_variant_id": "24",
"quantity": 3,
"price": 2000
},
{
"product_id": "1",
"product_variant_id": "1",
"quantity": 3,
"price": 2000
}
]
}'
Example Response
{
"ecommerce_cart": {
"customer": {
"customer_id": "1234",
"email_address": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"billing_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
},
"shipping_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
}
}
"checkout_url": "https://example.com/cart/690933842",
"currency_code": "USD",
"order_total": 234,
"discount_total": 12,
"created_at": "2017-03-22T16:28:02",
"updated_at": "2017-03-22T16:28:02",
"line_items": [
{
"product_id": "12",
"product_variant_id": "24",
"quantity": 3,
"price": 2000
},
{
"product_id": "1",
"product_variant_id": "1",
"quantity": 3,
"price": 2000
}
]
}
}
Add a new cart to your ecommerce store.
POST https://api.getgist.com/ecommerce/stores/{store_id}/customers/{customer_id}/cart
Response
A Cart object.
Delete a cart
Example Request
$ curl --request DELETE \
--url https://api.getgist.com/ecommerce/stores/12/carts/12 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json'
Example Response
{
"ecommerce_cart": {
"customer": {
"customer_id": "1234",
"email_address": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"billing_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
},
"shipping_address": {
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555"
}
}
"checkout_url": "https://example.com/cart/690933842",
"currency_code": "USD",
"order_total": 234,
"discount_total": 12,
"created_at": "2017-03-22T16:28:02",
"updated_at": "2017-03-22T16:28:02",
"line_items": [
{
"product_id": "12",
"product_variant_id": "24",
"quantity": 3,
"price": 2000
},
{
"product_id": "1",
"product_variant_id": "1",
"quantity": 3,
"price": 2000
}
]
}
}
Remove a cart from your Gist workspace.
DELETE https://api.getgist.com/ecommerce/stores/{store_id}/customers/{customer_id}/cart
Response
A Cart object.
Orders
Orders will show up on a contact's activity timeline as an event. An order’s financial_status can be pending, on-hold, partially_paid, paid, partially_refunded, refunded, cancelled. Changing the status will result in tracking events for the contact.
For example, sending "pending" results in a "Placed an order" event and sending "paid" will result in an "Paid an order" event.
Gist will keep a contact's Lifetime Time Value (LTV) up-to-date with their orders. For example, if a customer places an order with an order_total of $100, their LTV will be incremented by $100. If the order is then updated, paid, or fulfilled with a order_total value of $105, the customer’s LTV will increase by $5. If the order is then canceled or refunded with a refund_amount of $105, the customer’s LTV will decrease by $105.
Whenever order resources are saved through the API, the aggregate data fields of the related contact are automatically updated.
The order object
Example Response
{
"order_id": "12",
"customer_id": "12",
"currency_code": "USD",
"order_total": 234,
"discount_total": 12,
"tax_total": 1,
"shipping_total": 1,
"financial_status": "paid",
"fulfillment_status": "fulfilled",
"order_url": "https://store.example.com/690933842/orders/b1946ac",
"tracking_number": "12345678",
"tracking_carrier": "FedEx",
"tracking_url": "https://www.aftership.com/track/12345678",
"processed_at": "2017-03-22T16:28:02",
"updated_at": "2017-03-22T16:28:02",
"cancelled_at:": "",
"billing_address": {
"name": "John Doe",
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555",
"company_name": ""
},
"shipping_address": {
"name": "John Doe",
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555",
"company_name": ""
},
"line_items": [
{
"product_id": "12",
"product_variant_id": "24",
"quantity": 3,
"price": 2000
},
{
"product_id": "1",
"product_variant_id": "1",
"quantity": 3,
"price": 2000
}
]
}
It contains the following fields:
| Property | Type | Required | Description |
|---|---|---|---|
| order_id | string | yes | A unique, internal id for the order (generally the primary key generated by the ecommerce platform) |
| customer_id | string | yes | A unique, internal id for the customer (generally the primary key generated by the ecommerce platform) |
| currency_code | string | yes | The three-letter ISO 4217 code for the currency that the order uses. |
| order_total | number | yes | The total for the order. |
| processed_at | date | yes | The date and time the order was processed in ISO 8601 format. |
| discount_total | number | no | The total amount of the discounts to be applied to the price of the order. |
| tax_total | number | no | The tax total associated with an order. |
| shipping_total | number | no | The shipping total for the order. |
| financial_status | string | no | The order status. Defaults to "pending" and can be set to: pending, on-hold, partially_paid, paid, partially_refunded, refunded, cancelled, failed. |
| fulfillment_status | string | no | The fulfillment status for the order. Defaults to null and can be set to partially_fulfilled, fulfilled. |
| order_url | string | no | The URL for the order. |
| tracking_number | string | no | The tracking number associated with the order. |
| tracking_carrier | string | no | The tracking carrier associated with the order. |
| tracking_url | string | no | The tracking URL associated with the order. |
| updated_at | date | no | The date and time the order was updated in ISO 8601 format. |
| cancelled_at | date | no | The date and time the order was cancelled in ISO 8601 format. |
| shipping_address | object | no | The shipping address for the order. |
| billing_address | object | no | The billing address for the order. |
| line_items | object[] | yes | An array of the cart's line items. |
| cart_id | string | no | A unique identifier for the cart. |
Both address objects have the following fields:
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | no | The name associated with the address. |
| address1 | string | no | The address for the order. |
| address2 | string | no | An additional field for the address. |
| city | string | no | The city in the address. |
| state | string | no | The state or normalized province in the address. |
| postal_code | string | no | The postal or zip code in the address. |
| country | string | no | The country in the address. |
| phone | string | no | The phone number for the address. |
| company_name | string | no | The company associated with the address. |
The line item object has the following fields:
| Property | Type | Required | Description |
|---|---|---|---|
| product_id | string | no | A unique identifier for the product associated with the cart line item. |
| product_variant_id | string | no | A unique identifier for the product variant associated with the cart line item. |
| quantity | number | no | The quantity of a cart line item. |
| price | number | no | The price of a cart line item. |
Create an order
Example Request
$ curl --request POST \
--url https://api.getgist.com/ecommerce/stores/12/orders \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"order_id": "12",
"customer_id": "12",
"currency_code": "USD",
"order_total": 234,
"discount_total": 12,
"tax_total": 1,
"shipping_total": 1,
"financial_status": "pending",
"fulfillment_status": "fulfilled",
"order_url": "https://store.example.com/690933842/orders/b1946ac",
"tracking_number": "12345678",
"tracking_carrier": "FedEx",
"tracking_url": "https://www.aftership.com/track/12345678",
"processed_at": "2017-03-22T16:28:02",
"updated_at": "2017-03-22T16:28:02",
"cancelled_at:": "",
"billing_address": {
"name": "John Doe",
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555",
"company_name": ""
},
"shipping_address": {
"name": "John Doe",
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555",
"company_name": ""
},
"line_items": [
{
"product_id": "12",
"product_variant_id": "24",
"quantity": 3,
"price": 2000
},
{
"product_id": "1",
"product_variant_id": "1",
"quantity": 3,
"price": 2000
}
]
}'
Example Response
{
"ecommerce_order": {
"order_id": "12",
"customer_id": "12",
"currency_code": "USD",
"order_total": 234,
"discount_total": 12,
"tax_total": 1,
"shipping_total": 1,
"financial_status": "paid",
"fulfillment_status": "fulfilled",
"order_url": "https://store.example.com/690933842/orders/b1946ac",
"tracking_number": "12345678",
"tracking_carrier": "FedEx",
"tracking_url": "https://www.aftership.com/track/12345678",
"processed_at": "2017-03-22T16:28:02",
"updated_at": "2017-03-22T16:28:02",
"cancelled_at:": "",
"billing_address": {
"name": "John Doe",
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555",
"company_name": ""
},
"shipping_address": {
"name": "John Doe",
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555",
"company_name": ""
},
"line_items": [
{
"product_id": "12",
"product_variant_id": "24",
"quantity": 3,
"price": 2000
},
{
"product_id": "1",
"product_variant_id": "1",
"quantity": 3,
"price": 2000
}
]
}
}
Add a new order to your ecommerce store.
POST https://api.getgist.com/ecommerce/stores/{store_id}/orders
Response
An Order object.
Update an order
Example Request
$ curl --request PATCH \
--url https://api.getgist.com/ecommerce/stores/12/orders/12 \
--header 'Authorization:Bearer <ACCESS_TOKEN>' \
--header 'Content-Type:application/json' \
--data '{
"currency_code": "USD",
"order_total": 234,
"discount_total": 12,
"tax_total": 1,
"shipping_total": 1,
"financial_status": "paid",
"fulfillment_status": "fulfilled",
"order_url": "https://store.example.com/690933842/orders/b1946ac",
"tracking_number": "12345678",
"tracking_carrier": "FedEx",
"tracking_url": "https://www.aftership.com/track/12345678",
"processed_at": "2017-03-22T16:28:02",
"updated_at": "2017-03-22T16:28:02",
"cancelled_at:": "",
"billing_address": {
"name": "John Doe",
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555",
"company_name": ""
},
"shipping_address": {
"name": "John Doe",
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555",
"company_name": ""
},
"line_items": [
{
"product_id": "12",
"product_variant_id": "24",
"quantity": 3,
"price": 2000
},
{
"product_id": "1",
"product_variant_id": "1",
"quantity": 3,
"price": 2000
}
]
}'
Example Response
{
"ecommerce_order": {
"order_id": "12",
"customer_id": "12",
"currency_code": "USD",
"order_total": 234,
"discount_total": 12,
"tax_total": 1,
"shipping_total": 1,
"financial_status": "paid",
"fulfillment_status": "fulfilled",
"order_url": "https://store.example.com/690933842/orders/b1946ac",
"tracking_number": "12345678",
"tracking_carrier": "FedEx",
"tracking_url": "https://www.aftership.com/track/12345678",
"processed_at": "2017-03-22T16:28:02",
"updated_at": "2017-03-22T16:28:02",
"cancelled_at:": "",
"billing_address": {
"name": "John Doe",
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555",
"company_name": ""
},
"shipping_address": {
"name": "John Doe",
"address1": "969 Market",
"address2": "",
"city": "San Francisco",
"state": "California",
"postcode": "94103",
"country": "US",
"phone": "(555) 555-5555",
"company_name": ""
},
"line_items": [
{
"product_id": "12",
"product_variant_id": "24",
"quantity": 3,
"price": 2000
},
{
"product_id": "1",
"product_variant_id": "1",
"quantity": 3,
"price": 2000
}
]
}
}
An existing order is updated in your Gist workspace.
PATCH https://api.getgist.com/ecommerce/stores/{store_id}/orders/{order_id}
Response
An Order object.