Chattermill API

This is Chattermill's official REST API. You can use it to add or update responses on Chattermill or query your data on Chattermill.

Authentication

You need to provide an API Key for every request. You can get your API Key here. The key should be provided in the Authorization header:

Plain Text

curl 'https://api.chattermill.com/v1/projects' \
        -H 'Authorization: Bearer {key}'

Data Structure

Your main data model in Chattermill is Response. Once processed, this object contains the comment, score, any meta-data, and the themes.

You may have several projects on Chattermill, so you would need to specify a Project when querying other data in the URL.

You also have several datasets characterised by different data_types (think nps, review etc.) and data_sources (Zendesk, Typeform etc.). These can be handy if you need to work with only one group of responses.

We currently provide only read endpoints for Projects, Data Types and Data Sources.

Typical Workflows

Fetching new responses

You will probably need to query the /projects endpoint first to find the key of the project you need. Typically, this is similar to a lowercase version of your company's name.

Once you have that, you can query the /responses endpoint specifying the right group of filters. We recommend scoping by a specific date range based on how often your workflow runs (e.g. previous day or previous hour) or storing the last processed id and scrolling through the pages until you hit it.

Adding feedback to Chattermill

Then query /data_sources and /data_types endpoints to get the keys for those variables. If the correct sources or types do not exist, please contact our Support team to create them.

Finally, you would need to send a POST request to the /responses endpoint.

Actioning Data Erasure Requests (eg. per GDPR)

Typically, Chattermill will not store your users' PII data, meaning there is no GDPR liability. However, if you need to delete a specific Response, you can find it by any response attribute (e.g. email or customer ID) through the /responses/search endpoint and then trigger permanent deletion through the DELETE /responses/{id} endpoint.

Enriching Chattermill Data

Frequently, you will want to add additional attributes (aka enrich) to the data you already have in Chattermill, perhaps from your CRM or your own database / data warehouse.

To do this, we recommend one of two approaches:

• Periodically poll for new responses using the GET /responses endpoint, using filters to only find new data (either by maintaining an ID-based or date-based cursor on your end or by using filters to find responses without the attribute in question. Then, when a response needs to be enriched, use the PUT /responses/{id} endpoint to add the attribute.

• Set up a Webhook on Chattermill Workflows to receive an automated notification for new responses, then update them using the PUT /responses/{id} endpoint.

An anti-pattern that should be avoided is using POST responses/search endpoint to find a given response and then update it. This can lead to unpredictable results because the response might not have been fully processed when you kick off your workflow. The approaches above ensure consistency.

Full Data Export

Chattermill offers a separate service for full data export which allows you to push the data from Chattermill to shared buckets at AWS S3 or Google Cloud Storage (GCS). From there, you can route it to your data warehouse such as Databricks, Redshift, BigQuery, or Snowflake. It is primarily used to enhance customer feedback with financial and business data for deeper analysis. Additionally, Chattermill customers can use it to create powerful visualizations in their Business Intelligence tools for advanced reporting. Please reach out to your Customer Success Manager or support@chattermill.com to speak about this service.

Getting Help

Please get in touch via api@chattermill.com if you have any questions. We will reply quickly.

Projects

Operations related to Projects

GET

Get a Project by Project ID

https://api.chattermill.com/v1/projects/:id

Returns a single Project

AUTHORIZATION

Bearer Token

HEADERS

Accept

application/json Content-Type

application/json PATH VARIABLES

id

{{id}}
[Required] id of Project to fetch

Example Request: Get a Project by Project ID

curl --location -g 'https://api.chattermill.com/v1/projects/{{id}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Example Response

{
    "project": {
        "id": 121435353423462,
        "name": "Project One",
        "key": "project_one"
    }
}

GET

Get a list of Projects

https://api.chattermill.com/v1/projects

Returns all projects the user has access to

AUTHORIZATION

Bearer Token

HEADERS

Accept

application/json Content-Type

application/json

Example Request: Get a list of Projects

curl --location 'https://api.chattermill.com/v1/projects' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Example Response

{
  "projects": [
    {
      "id": 232324435353,
      "key": "project_one",
      "name": "Project One"
    },
    {
      "id": 134532323232,
      "key": "project_two",
      "name": "Project Two"
    }
  ]
}

Responses

Operations related to Responses

GET

Get a Response by ID

https://api.chattermill.com/v1/:project/responses/:id

Returns a single response

AUTHORIZATION

Bearer Token

HEADERS

Accept

application/json Content-Type

application/json PATH VARIABLES

project

{{project}}
[Required] Project key to fetch responses from (can be obtained from List Projects endpoint) id

{{id}}
[Required] id of Response to fetch

Example Request: Get a Response by ID

curl --location -g 'https://api.chattermill.com/v1/{{project}}/responses/{{id}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Example Response

{
  "response": {
    "id": 12345678901234567000,
    "score": 10,
    "comment": "Example Comment",
    "original_comment": "Example Comment",
    "created_at": "2023-03-15T10:28:50.077Z",
    "updated_at": "2023-03-17T08:40:09.525Z",
    "user_attributes": {
      "name": {
        "name": "Name",
        "value": "James Bond"
      },
      "site": {
        "name": "Site",
        "value": "UK"
      },
      "order": {
        "name": "Order ID",
        "value": "007"
      }
    },
    "themes": [
      {
        "name": "Example Theme",
        "id": 1,
        "parent_id": 2,
        "sentiment": -1,
        "parent": "Example Category"
      }
    ],
    "phrases": [
      {
        "label": "example_phrase",
        "parent": "example_phrase_cluster",
        "sentiment": -1
      }
    ]
  }
}

PUT

Update a Response by Response ID

https://api.chattermill.com/api/v1/:project/responses/:response_id

Update response with attributes given

AUTHORIZATION

Bearer Token

HEADERS

Accept

application/json Content-Type

application/json Authorization

Bearer {{token}}

PATH VARIABLES

project

[Required] Project key to update responses in (can be obtained from List Projects endpoint) response_id

[Required] id of Project to update

Body raw

{
    "response": {
        "user_meta": {
            "customer_id": {
                "type": "text",
                "value": "1234",
                "name": "Customer ID"
            }
        },
        "segments": {
            "customer_type": {
                "type": "text",
                "value": "New",
                "name": "Customer Type"
            }
        }
    }
}

Example Request: Update a Response by Response ID

curl --location --request PUT 'https://api.chattermill.com/api/v1/:project/responses/:response_id' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data '{
    "response": {
        "user_meta": {
            "customer_id": {
                "type": "text",
                "value": "1234",
                "name": "Customer ID"
            }
        },
        "segments": {
            "customer_type": {
                "type": "text",
                "value": "New",
                "name": "Customer Type"
            }
        }
    }
}'

Example Response

No response body

This request doesn't return any response body

No response headers

This request doesn't return any response headers

DELETE

Destroy a Response by Response ID

https://api.chattermill.com/v1/:project/responses/:response_id

Permanently delete a response with a given ID.

Please note, this operation is not reversible and should thus only be utilised for automating data erasure requests in tandem with a /search call to find the correct Response ID (for example to comply with GDPR).

AUTHORIZATION

Bearer Token

HEADERS

Accept

application/json Content-Type

application/json Authorization

Bearer {{token}}

PATH VARIABLES

project

[Required] Project key to update responses in (can be obtained from List Projects endpoint) response_id

[Required] id of Project to update

Example Request: Destroy a Response by Response ID

curl --location --request DELETE 'https://api.chattermill.com/v1/:project/responses/:response_id' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}'

Example Response

No response body

This request doesn't return any response body

No response headers

This request doesn't return any response headers

GET

Get a list of Responses for a project

https://api.chattermill.com/v1/:project/responses?page={{page}}&per_page={{per_page}}&from={{from}}&to={{to}}&data_type={{data_type}}&data_source={{data_source}}&filter_property={{filter_property}}&filter_value={{filter_value}}&text_analytics_processed={{text_analytics_processed}}&comment_present={{comment_present}}&score_from={{score_from}}&score_to={{score_to}}&custom_segment_id={{custome_segment_id}}&theme_id={{theme_id}}&updated_from={{updated_from}}&updated_to={{updated_to}}

Returns a paginated collection of responses.

AUTHORIZATION

Bearer Token

HEADERS

Accept

application/json Content-Type

application/json

PARAMS

page

{{page}}
[Optional] Results page requested (defaults to 1) per_page

{{per_page}}
[Optional] # of results per page (defaults to 20, max. 100) from

{{from}}
[Optional] Date From to filter by (YYYYMMDD_HHMMSS format) to

{{to}}
[Optional] Date to to filter by (YYYYMMDD_HHMMSS format) data_type

{{data_type}}
[Optional] Data Type key to filter by (can be obtained via List Data Types endpoint) data_source

{{data_source}}
[Optional] Data Source key to filter by (can be obtained via List Data Sources endpoint filter_property

{{filter_property}}
[Optional] Segment property to filter by filter_value

{{filter_value}}
[Optional] Segment value to filter by text_analytics_processed

{{text_analytics_processed}}
[Optional] Set to true to only fetch responses that were processed by machine learning model (by default both processed and unprocessed responses will be returned). comment_present

{{comment_present}}
[Optional] Set to true to only fetch responses with a comment (false by default). score_from

{{score_from}}
[Optional] Score From to filter by (defaults to 0) score_to

{{score_to}}
[Optional] Score To to filter by (defaults to 10) custom_segment_id

{{custome_segment_id}}
[Optional] Choose a Custom Segment to filter by theme_id

{{theme_id}}
[Optional] Choose a Theme to filter by updated_from

{{updated_from}}
[Optional] Last Update Date From to filter by (YYYYMMDD_HHMMSS format) updated_to

{{updated_to}}
[Optional] Last Update Date To to filter by (YYYYMMDD_HHMMSS format)

PATH VARIABLES

project

{{project}}
[Required] Project key to fetch responses from (can be obtained from List Projects endpoint)

Example Request: Get a list of Responses for a project

curl --location -g 'https://api.chattermill.com/v1/{{project}}/responses?page={{page}}&per_page={{per_page}}&from={{from}}&to={{to}}&data_type={{data_type}}&data_source={{data_source}}&filter_property={{filter_property}}&filter_value={{filter_value}}&text_analytics_processed={{text_analytics_processed}}&comment_present={{comment_present}}&score_from={{score_from}}&score_to={{score_to}}&custom_segment_id={{custome_segment_id}}&theme_id={{theme_id}}&updated_from={{updated_from}}&updated_to={{updated_to}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Example Response

No response body

This request doesn't return any response body:

No response headers

This request doesn't return any response headers