NAV Navbar
shell
  • API Reference
  • Authentication
  • API Structure
  • Users
  • Leads
  • Tags
  • Segments
  • Events
  • Campaign
  • API Reference

    Welcome to the Gist API.

    The Gist API is organized around REST. It consists of predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, such as HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

    We support CORS (cross-origin resource sharing), helping you interact securely with our API from a client-side web application. For safety purposes, we recommend you to not expose your secret API key in any public website's client-side code under any circumstances. JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

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

    You can view code examples for popular programming languages, to the right of this page. We provide API code examples for Ruby, PHP, Java, and for our events, we use JavaScript.

    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/users/146179 \
    -H 'Authorization:Bearer <access_token>' \
    -H 'Accept:application/json'
    

    Authenticate your account when using the API by including your secret Access Token in the request. You can manage your Access Token in the Integration Settings in your Gist dashboard.

    Note that your Access Token allows you access to your private user data in Gist and as such it should not be shared outside of your company. If a certain integration requests your access token, please reach out to us, and don't share your token 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 Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

    If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer sk_test_BQokikJOvBiI2HlWgH4olfQ2" instead of -u sk_test_BQokikJOvBiI2HlWgH4olfQ2. To learn more about the bearer token framework, please see the official spec here.

    API Structure

    API Area API Resource Description
    Users https://api.getgist.com/users Create and update Users. Use filters to get lists of Users, or access their profiles individually.
    Leads https://api.getgist.com/leads Create and update Leads. Get lists of Leads, or access their profiles individually.
    Tags https://api.getgist.com/tags Organize your Project Users and Leads with tags.
    Segments https://api.getgist.com/segments View your Project's Segments.
    Events https://api.getgist.com/events Use Events to submit User activity to Gist
    Campaigns https://api.getgist.com/campaigns Fetch, pause or set live a campaign or list all Users and Leads subscribed to a campaign.

    Users

    This resource is the principal method of interacting with Gist. Using the users endpoint, you can fetch, create, update or delete your users or add custom properties describing them.

    User Model

    Example Response

    {
      "user": {
        "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": [],
        "social_profiles": null,
        "custom_properties": {
          "age": 22
        },
        "unsubscribed_from_emails": false
      }
    }
    
    Property Type Description
    type string Default is ‘user’
    id string Internal Gist UUID representing the user
    name string The full name of the user
    email string The email address of the user
    user_id string The user id of the user
    phone string The contact number of the user
    created_at timestamp The time the user was added to Gist
    signed_up_at timestamp The time the user signed up
    last_seen_at timestamp The time the user was last seen
    updated_at timestamp The time the user was last updated
    last_contacted_at timestamp The time the user was last contacted
    session_count integer The count of sessions the user has recorded
    avatar string The URL of user’s avatar image
    landing_url string The URL of the page the user first visited on your website
    original_referrer string The referrer URL the user came to your website from
    last_seen_ip string The last IP address the user visited your website from
    last_seen_user_agent string The last user agent the user was seen using
    location_data json A JSON object containing the location details of the user
    segments string An Array containing one or more segments the user belongs to
    tags string Optional. An Array containing one or more tags the user has. E.g. ["Customer", "VIP"]
    social_profiles json A JSON object listing all the social profiles details of the user
    custom_properties json Optional. A JSON object containing the user’s custom properties. E.g. { "name": "John Doe" }
    unsubscribed_from_emails boolean If the user 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 user’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 user with the following restrictions

    Create or Update a User

    Example Request

    curl --request POST \
      --url https://api.getgist.com/users \
      --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
        }
    }'
    

    Example Response

    {
        "user": {
            "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": "Completed"
                }
            ],
            "social_profiles": [],
            "custom_properties": {
                "form_user": null,
                "user_types": null,
                "age": 23,
                "first_name": null
            },
            "unsubscribed_from_emails": "false"
        }
    }
    

    Users can be created or updated via a POST method to https://api.getgist.com/users, which accepts a JSON object describing the user.

    Users not found via email or user_id will be created, and those that are found will be updated.

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

    id is matched - the user_id and email will be updated if they are sent.

    user_id match - the email will be updated, the id is not updated.

    email match where no user_id set on the matching user - the user_id will be set to the value sent in the request, the id is not updated.

    email match where there is a user_id set on the matching user - a new unique record with new id will be created if a new value for user_id is sent in the request.

    Note that email values are downcased after they have been submitted to our API.

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

    Returns: A created or updated user object.

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

    Fetch a User

    Example Request

    $ curl --request GET \
    --url https://api.getgist.com/users/146719 \
    --header 'Authorization:Bearer <access_token>' \
    --header 'Accept:application/json'
    

    Example Response

    {
        "user": {
            "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": "Completed"
                }
            ],
            "social_profiles": [],
            "custom_properties": {
                "form_user": null,
                "user_types": null,
                "age": 23,
                "first_name": null
            },
            "unsubscribed_from_emails": "false"
        }
    }
    

    Each user object has its own URL - https://api.getgist.com/users/{id}

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

    The ‘users’ endpoint accepts two parameters:

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

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

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

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

    The email parameter value should be url encoded when sending.

    Returns: A user object.

    Fetch a list of Users

    Example Request

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

    Example Response

    {
        "users": [
              {
                    "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": "user",
                "id": 72712,
                "name": "Isaac",
                "email": "[email protected]",
                "user_id": "72712",
                "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": "user",
                "id": 70524,
                "name": "Bringe",
                "email": "[email protected]",
                "user_id": "70524",
                "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/users?order=desc&order_by=created_at&page=17&per_page=5",
            "next": "https://api.getgist.com/users?order=desc&order_by=created_at&page=19&per_page=5",
            "first": "https://api.getgist.com/users?order=desc&order_by=created_at&page=1&per_page=5",
            "last": "https://api.getgist.com/users?order=desc&order_by=created_at&page=32&per_page=5"
        }
    }
    

    You can fetch a list of users. The user 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 user list. asc or desc. Defaults to desc
    sort no The property to sort the fetched results by. Defaults to created_at. Other options: last_seen_at, signed_up_at, updated_at
    created_since no Limit results to users that were created in that last number of days.
    status no Filter by one of the following statuses: active, or unsubscribed, or bounced. Defaults to all.
    tags no A comma separated list of tags. When included, returns only subscribers who have at least one of the listed tags.

    Returns: A pageable list of users.

    The user list contains a pages object that indicates if more users 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 users in the list.

    Fetch list of Users by Tags and Segments

    Segmented users and leads can be fetched by querying the users resource with a segment_id parameter, indicating the id of the segment to query with.

    To fetch tagged users/leads, you can indicate the id of the tag using the a tag_id parameter.

    Note that you cannot combine tag and segment parameters in the same request.

    Parameter Required Description
    tag_id no A comma separated list of tag_ids to filter by. When included, returns only subscribers who have at least one of the listed tag_ids.
    segment_id no The id of the segment to filter by.

    Returns: A pageable list of Users.

    Delete a User

    Example Request

    $ curl --request DELETE \
    --url https://api.getgist.com/users/265 \
    --header 'Authorization:Bearer <access_token>' \
    --header 'Accept:application/json'
    

    Example Response

    {
        "user": {
            "type": "user",
            "id": 265,
            "name": "wailey Dane",
            "email": "[email protected]",
            "user_id": "265",
            "phone": null,
            "created_at": 1493343068,
            "signed_up_at": 1496894345,
            "last_seen_at": 1496894348,
            "last_contacted_at": 1538552871,
            "updated_at": 1538638752,
            "session_count": 8,
            "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=WA",
            "landing_url": "getgist.com?utm_source=BetaList",
            "original_referrer": "",
            "last_seen_ip": "103.237.57.123",
            "last_seen_user_agent": null,
            "location_data": {
                "city_name": "Kolkata",
                "region_name": null,
                "country_name": "India",
                "country_code": "IN",
                "continent_name": null,
                "continent_code": null,
                "latitude": 22.4610,
                "longitude": 88.3536,
                "postal_code": null,
                "time_zone": null,
                "utc_offset": null
            },
            "segments": [
                {
                    "id": 5,
                    "name": "All Users",
                    "created_at": 1493141363,
                    "updated_at": 1534413183
                }
            ],
            "tags": [],
            "social_profiles": [],
            "custom_properties": {
                "expiry_at": null,
                "form_user": "33161518",
                "age": 28,
                "first_name": null
            },
            "unsubscribed_from_emails": "false"
        }
    }
    

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

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

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

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

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

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

    Returns: A User object.

    Leads

    You can represent users who have logged-out of your application using leads. The Leads resource provides methods to fetch, create, update and delete Leads within Gist.

    Lead Model

    Example Response

    {
        "lead": {
            "type": "lead",
            "id": 182806,
            "name": "Deepak",
            "email": "[email protected]",
            "user_id": null,
            "phone": null,
            "created_at": 1503362556,
            "signed_up_at": 1503363340,
            "last_seen_at": 1510133412,
            "last_contacted_at": 1525086492,
            "updated_at": 1525086493,
            "session_count": 1,
            "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=CI",
            "landing_url": "getgist.com",
            "original_referrer": "",
            "last_seen_ip": "203.17.201.1",
            "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.6702,
                "longitude": 144.8482,
                "postal_code": null,
                "time_zone": null,
                "utc_offset": null
            },
            "segments": [
                {
                    "id": 8,
                    "name": "Slipping Away",
                    "created_at": 1493141363,
                    "updated_at": 1539763645
                }
            ],
            "tags": [
                {
                    "id": 309,
                    "name": "testing"
                }
            ],
            "social_profiles": [],
            "custom_properties": {
                "expiry_at": null,
                "form_user": "33161518",
                "key_test": null,
                "age": 32,
                "first_name": null
            },
            "unsubscribed_from_emails": "false"
        }
    }
    
    Property Type Description
    type string Default is ‘lead’
    id string Internal Gist UUID representing the user
    name string The full name of the user
    email string The email address of the user
    user_id string Leads have null value for the user_id
    phone string The contact number of the user
    created_at timestamp The time the user was added to Gist
    last_seen_at timestamp The time the user was last seen
    updated_at timestamp The time the user was last updated
    last_contacted_at timestamp The time the user was last contacted
    avatar string The URL of user’s avatar image
    landing_url string The URL of the page the user first visited on your website
    original_referrer string The referrer URL the user came to your website from
    last_seen_ip string The last IP address the user visited your website from
    last_seen_user_agent string The last user agent the user was seen using
    location_data json A JSON object containing the location details of the user
    segments string An Array containing one or more segments the user belongs to
    tags string Optional. An Array containing one or more tags the user has. E.g. ["Customer", "VIP"]
    social_profiles json A JSON object listing all the social profiles details of the user
    custom_properties json Optional. A JSON object containing the user’s custom properties. E.g. { "name": "John Doe" }
    unsubscribed_from_emails boolean If the user has unsubscribed from emails or not

    Create or Update a Lead

    Example Request

    $ curl --request POST \
    --url https://api.getgist.com/leads \
    --header 'Authorization:Bearer <access_token>' \
    --header 'Accept:application/json' \
    --data '{
             "email": "[email protected]",
             "name":"Bailey",
             "phone": null,
             "signed_up_at": 1506337696,
             "last_seen_ip": "127.0.0.1",
             "last_seen_user_agent": "To be added",
             "unsubscribed_from_emails": false,
             "custom_properties": {
               "age": 22
             }
           }'
    

    Example Response

    {
        "lead": {
            "type": "lead",
            "id": 11,
            "name": "Bailey",
            "email": "[email protected]",
            "user_id": null,
            "phone": null,
            "created_at": 1493141928,
            "signed_up_at": 1506337696,
            "last_seen_at": 1493737277,
            "last_contacted_at": 1525095798,
            "updated_at": 1540462661,
            "session_count": 11,
            "avatar": "https://d2i5n66vu52qed.cloudfront.net/uploads/person_company/picture/1174980/picture",
            "landing_url": "getgist.com?utm_campaign=trial_started&utm_medium=email&utm_source=notification_mailer",
            "original_referrer": "",
            "last_seen_ip": "127.0.0.1",
            "last_seen_user_agent": "To be added",
            "location_data": {
                "city_name": "Taipei",
                "region_name": null,
                "country_name": "Taiwan",
                "country_code": "TW",
                "continent_name": null,
                "continent_code": null,
                "latitude": 25.1153,
                "longitude": 121.5607,
                "postal_code": null,
                "time_zone": null,
                "utc_offset": null
            },
            "segments": [
                {
                    "id": 473,
                    "name": "Test filter changes",
                    "created_at": 1505220549,
                    "updated_at": 1539763646
                }
            ],
            "tags": [],
            "social_profiles": [
                {
                    "name": "linkedin",
                    "url": "https://www.linkedin.com/in/baileythoda"
                }
            ],
            "custom_properties": {
                "expiry_at": null,
                "form_user": "33161518",
                "age": 22,
                "first_name": null
            },
            "unsubscribed_from_emails": "false"
        }
    }
    

    Leads can be created or updated via a POST method to https://api.getgist.com/leads, which accepts a JSON object describing the lead.

    No identifying information is required to create a Lead.

    Unlike in the case of Users, ‘signed_up’ and sessions are not available for Leads. Otherwise, properties to update on a Lead are the same as for a User.

    Returns: The Lead Object.

    Fetch a Lead

    Example Request

    Leads can be fetched or looked up individually via their id parameter.

    $ curl --request GET \
    --url https://api.getgist.com/leads/11 \
    --header 'Authorization:Bearer <access_token>' \
    --header 'Accept:application/json'
    

    Example Response

    {
        "lead": {
            "type": "lead",
            "id": 11,
            "name": "Bailey",
            "email": "[email protected]",
            "user_id": null,
            "phone": null,
            "created_at": 1493141928,
            "signed_up_at": 1506337696,
            "last_seen_at": 1493737277,
            "last_contacted_at": 1525095798,
            "updated_at": 1540462661,
            "session_count": 11,
            "avatar": "https://d2i5n66vu52qed.cloudfront.net/uploads/person_company/picture/1174980/picture",
            "landing_url": "getgist.com?utm_campaign=trial_started&utm_medium=email&utm_source=notification_mailer",
            "original_referrer": "",
            "last_seen_ip": "127.0.0.1",
            "last_seen_user_agent": "To be added",
            "location_data": {
                "city_name": "Taipei",
                "region_name": null,
                "country_name": "Taiwan",
                "country_code": "TW",
                "continent_name": null,
                "continent_code": null,
                "latitude": 25.1153,
                "longitude": 121.5607,
                "postal_code": null,
                "time_zone": null,
                "utc_offset": null
            },
            "segments": [
                {
                    "id": 473,
                    "name": "Test filter changes",
                    "created_at": 1505220549,
                    "updated_at": 1539763646
                }
            ],
            "tags": [],
            "social_profiles": [
                {
                    "name": "linkedin",
                    "url": "https://www.linkedin.com/in/baileythoda"
                }
            ],
            "custom_properties": {
                "expiry_at": null,
                "form_user": "33161518",
                "age": 22,
                "first_name": null
            },
            "unsubscribed_from_emails": "false"
        }
    }
    

    Note that for leads, Gist automatically generated a random identifier, which looks like ‘ba80b4d7-8b70-c9ed-0c34-0529d97c741c’. And this identifier is not retained when lead converts to a user. The user_id for users is manually set by you, and as such it will generally be a regular integer such as ‘12345’.

    Returns: The Lead Object.

    Fetch a list of Leads

    Example Request

    $ curl --request GET \
    --url https://api.getgist.com/leads/order=desc&order_by=created_at&page=43&per_page=5 \
    --header 'Authorization:Bearer <access_token>' \
    --header 'Accept:application/json'
    

    Example Response

    {
        "leads": [
            {
                "type": "lead",
                "id": 299628,
                "name": "Neyu",
                "email": "[email protected]",
                "user_id": null,
                "phone": null,
                "created_at": 1518087482,
                "signed_up_at": 1518086836,
                "last_seen_at": 1518086836,
                "last_contacted_at": null,
                "updated_at": 1518087482,
                "session_count": null,
                "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=ED",
                "landing_url": null,
                "original_referrer": null,
                "last_seen_ip": null,
                "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.6702,
                    "longitude": 144.8482,
                    "postal_code": null,
                    "time_zone": null,
                    "utc_offset": null
                },
                "segments": [
                    {
                        "id": 5,
                        "name": "All Users",
                        "created_at": 1493141363,
                        "updated_at": 1534413183
                    }
                ],
                "tags": [],
                "social_profiles": [],
                "custom_properties": {},
                "unsubscribed_from_emails": "false"
            },
            {
                "type": "lead",
                "id": 299627,
                "name": "Meagan Brame",
                "email": "[email protected]",
                "user_id": "oepusgi9ueq1ftepsbmp",
                "phone": null,
                "created_at": 1518087482,
                "signed_up_at": 1518086836,
                "last_seen_at": 1518086836,
                "last_contacted_at": null,
                "updated_at": 1518087482,
                "session_count": null,
                "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=ME",
                "landing_url": null,
                "original_referrer": null,
                "last_seen_ip": null,
                "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.6702,
                    "longitude": 144.8482,
                    "postal_code": null,
                    "time_zone": null,
                    "utc_offset": null
                },
                "segments": [],
                "tags": [
                    {
                        "id": 340,
                        "name": "Contacts From Tracey"
                    }
                ],
                "social_profiles": [],
                "custom_properties": {},
                "unsubscribed_from_emails": "false"
            },
            {
                "type": "lead",
                "id": 299626,
                "name": "Rene",
                "email": "[email protected]",
                "user_id": "yb5jzmbjasygcpqxp31y",
                "phone": null,
                "created_at": 1518087482,
                "signed_up_at": 1518086836,
                "last_seen_at": 1518086836,
                "last_contacted_at": null,
                "updated_at": 1518087482,
                "session_count": null,
                "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=RE",
                "landing_url": null,
                "original_referrer": null,
                "last_seen_ip": null,
                "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.6702,
                    "longitude": 144.8482,
                    "postal_code": null,
                    "time_zone": null,
                    "utc_offset": null
                },
                "segments": [],
                "tags": [
                    {
                        "id": 374,
                        "name": "Import: Behavioral Assessment"
                    }
                ],
                "social_profiles": [],
                "custom_properties": {
                    "expiry_at": null,
                    "age": 28,
                    "first_name": null
                },
                "unsubscribed_from_emails": "false"
            },
            {
                "type": "lead",
                "id": 299625,
                "name": "Erin Anderson",
                "email": "[email protected]",
                "user_id": "ftk4reoahzxkyesvtyrq",
                "phone": null,
                "created_at": 1518087482,
                "signed_up_at": 1518086836,
                "last_seen_at": 1518086836,
                "last_contacted_at": null,
                "updated_at": 1518087482,
                "session_count": null,
                "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=ER",
                "landing_url": null,
                "original_referrer": null,
                "last_seen_ip": null,
                "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.6702,
                   "longitude": 144.8482,
                   "postal_code": null,
                   "time_zone": null,
                   "utc_offset": null
                },
                "segments": [
                    {
                        "id": 473,
                        "name": "Test filter changes",
                        "created_at": 1505220549,
                        "updated_at": 1539763646
                    }
                ],
                "tags": [],
                "social_profiles": [],
                "custom_properties": {
                    "expiry_at": null,
                    "user_types": null,
                    "key_test": null,
                    "age": 32,
                    "first_name": null
                },
                "unsubscribed_from_emails": "false"
            },
            {
                "type": "lead",
                "id": 299624,
                "name": "Randall Fabbro",
                "email": "[email protected]",
                "user_id": "s28emsnoipanvkm1soq1",
                "phone": null,
                "created_at": 1518087482,
                "signed_up_at": 1518086836,
                "last_seen_at": 1518086836,
                "last_contacted_at": null,
                "updated_at": 1518087482,
                "session_count": null,
                "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=RA",
                "landing_url": null,
                "original_referrer": null,
                "last_seen_ip": null,
                "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.6702,
                    "longitude": 144.8482,
                    "postal_code": null,
                    "time_zone": null,
                    "utc_offset": null
                },
                "segments": [
                    {
                        "id": 473,
                        "name": "Test filter changes",
                        "created_at": 1505220549,
                        "updated_at": 1539763646
                    }
                ],
                "tags": [
                    {
                        "id": 332,
                        "name": "delete"
                    }
                ],
                "social_profiles": [],
                "custom_properties": {
                    "form_user": null,
                    "key_test": null,
                    "age": 0,
                    "first_name": null
                },
                "unsubscribed_from_emails": "false"
            }
        ],
        "pages": {
            "prev": "https://api.getgist.com/leads?order=desc&order_by=created_at&page=42&per_page=5",
            "next": "https://api.getgist.com/leads?order=desc&order_by=created_at&page=44&per_page=5",
            "first": "https://api.getgist.com/leads?order=desc&order_by=created_at&page=1&per_page=5",
            "last": "https://api.getgist.com/leads?order=desc&order_by=created_at&page=514&per_page=5"
        }
    }
    

    You can fetch a list of all leads. The lead list is sorted by the created_at field and by default is ordered descending, most recently created first. Apart from sorting, the same parameters for the User list apply here.

    Returns: A pageable list of Leads.

    Delete a Lead

    Leads can be deleted via their id parameter, like User deletion.

    Example Request

    $ curl --request DELETE \
    --url https://api.getgist.com/leads/182806 \
    --header 'Authorization:Bearer <access_token>' \
    --header 'Accept:application/json'
    

    Example Response

    {
        "lead": {
            "type": "lead",
            "id": 182806,
            "name": "Xavier",
            "email": "[email protected]",
            "user_id": null,
            "phone": null,
            "created_at": 1503362556,
            "signed_up_at": 1503363340,
            "last_seen_at": 1510133412,
            "last_contacted_at": 1525086492,
            "updated_at": 1525086493,
            "session_count": 1,
            "avatar": "https://avatar.tobi.sh/[email protected]?size=120&type=svg&text=CI",
            "landing_url": "getgist.com",
            "original_referrer": "",
            "last_seen_ip": "203.17.201.1",
            "last_seen_user_agent": null,
            "location_data": {
                "city_name": "Melbourne",
                "region_name": null,
                "country_name": null,
                "country_code": "AU",
                "continent_name": null,
                "continent_code": null,
                "latitude": -37.8103,
                "longitude": 144.9544,
                "postal_code": "3000",
                "time_zone": null,
                "utc_offset": null
            },
            "segments": [
                {
                    "id": 8,
                    "name": "Slipping Away",
                    "created_at": 1493141363,
                    "updated_at": 1539763645
                }
            ],
            "tags": [
                {
                    "id": 309,
                    "name": "testing"
                }
            ],
            "social_profiles": [],
            "custom_properties": {
                "expiry_at": null,
                "form_user": "33161518",
                "age": 0,
                "first_name": null
            },
            "unsubscribed_from_emails": "false"
        }
    }
    

    Returns: The Lead Object.

    Tags

    Tags allow you to mark or label your users and leads and list them using that tag. You can then use group users by tags and create highly targeted user 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 users in bulk.

    Tag Model

    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 updated later to allow tag renaming.

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

    Create and Update Tags

    Example Request

    $ curl --request POST \
    --url https://api.getgist.com/tags \
    --header 'Authorization:Bearer <access_token>' \
    --header 'Accept: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 punctuation.

    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

    Returns: The newly created or updated tag object containing its name and id fields.

    Tag or Untag Users or Leads

    Example Request

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

    Example Response

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

    You can also tag users or leads using a POST to https://api.getgist.com/tags. This lets you assign a tag to multiple users or leads at once. If the tag does not already exist it will be created for you.

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

    Leads can be tagged by supplying a leads array. The array contains objects identifying leads by their id fields.

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

    To untag a user or a lead, each user or lead object sent in the tagging request can be submitted with an untag field whose value is set to true.

    Objects submitted with an untag field can be mixed with other objects being tagged. This allows tag and untag operations to be performed in a single request.

    The default behaviour if untag is not supplied is to tag the object. Setting the untag value to false is the same as requesting the object be tagged.

    Returns: The tag object containing its name and id fields.

    Delete a Tag

    Example Request

    $ curl --request DELETE \
    --url https://api.getgist.com/tags/727 \
    --header 'Authorization:Bearer <access_token>' \
    --header 'Accept: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}.

    List all Tags for a Project

    Example Request

    $ curl --request GET \
    --url https://api.getgist.com/tags \
    --header 'Authorization:Bearer <access_token>' \
    --header 'Accept: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 Project by sending a GET request to https://api.getgist.com/tags.

    Returns: A list of tag objects for the Project.

    Segments

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

    Segment Model

    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 items 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

    Fetch a Segment

    Example Request

    $ curl --request GET \
    --url https://api.getgist.com/segments/7?include_count=true \
    --header 'Authorization:Bearer <access_token>' \
    --header 'Accept: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

    Returns: A segment object.

    Fetch a list of 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 'Accept: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 user segments for your Project by sending a GET request to https://api.getgist.com/segments. You can also include counts in your segment model in the response if you add the parameter include_count=true in the request.

    Returns: A list of segment objects for the Project. The result may also have a pages object if the response is paginated.

    Events

    Event Model

    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 Your identifier for the user
    email yes if no user_id An email address for your user. An email should only be used where your application uses email to uniquely identify users
    id yes if no email or user_id Your identifier for a lead or a user
    occured_at timestamp The time the event occurred in ISO-8601 format. Defaults to the current time
    properties json optional properties about the event

    The event_name field is processed as follows -

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

    Record an Event

    Example Request

    $ curl --request POST \
    --url https://api.getgist.com/events \
    --header 'Authorization:Bearer <access_token>' \
    --header 'Accept: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 record an event by submitting a POST to https://api.getgist.com/events along with a name for the event or the event object. The event name may contain whitespace and punctuation.

    Returns: The newly created event object.

    Fetch all custom events used in a Project

    Example Request

    $ curl --request GET \
    --url https://api.getgist.com/events \
    --header 'Authorization:Bearer <access_token>' \
    --header 'Accept: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"
            },
            {
                "id": 131,
                "name": "MailChimp Connect"
            }
        ],
        "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 the events for a Project 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.

    Returns: A list of event objects for the Project.

    Campaign

    Campaign Model

    Example Response

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

    A Campaign Object describes the campaign and contains the following fields

    Property Type Description
    id string The id of the campaign
    status string The status of the campaign. It can be either draft, paused or live
    name string The name of the campaign
    created_at timestamp The time the campaign was created
    updated_at timestamp The time the campaign was last updated
    email_count integer The count of emails sent by the campaign
    active_subscriber_count integer The count of subscribers current receiving the campaign
    unsubscribed_subscriber_count integer The count of users who unsubscribed from the campaign
    email_open_rate number The average open rate of the campaign
    email_click_rate number 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

    Fetch a campaign

    Example Request

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

    Example Response

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

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

    Returns: A campaign object.

    Fetch all campaigns

    Example Request

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

    Example Response

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

    You can fetch all campaigns for a Project 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.

    Returns: A list of campaign objects for the Project.

    Subscribe/Unsubscribe someone to/from a campaign

    Example Request

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

    Example Response

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

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

    Parameter Required Description
    id yes The id of the campaign
    email yes The email address of the subscriber
    user_id yes if no email Your identifier for the user
    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 user/lead even if they unsubscribed from the campaign earlier.