Introduction

Welcome to the API documentation of Refiner!

You can use our API to access survey data that you collected with Refiner. The API can also be used to import additional user data from your backend database into your Refiner account.

This API returns JSON. Request data can be sent as URL query parameters, as form-encoded fields in the request body, or as a JSON object in the request body.

Please note that rate limits apply to all API requests.

Authentication

Authenticate with the Bearer Token method

curl "https://api.refiner.io/v1/"
  -H "Authorization: Bearer YOUR_API_KEY"

Authenticate using a request parameter

curl "https://api.refiner.io/v1/" \
  -d api_key=YOUR_API_KEY

Authenticate using the HTTP Basic Auth method

curl "https://api.refiner.io/v1/" \
  -u YOUR_API_KEY:

The above commands return JSON structured like this:

{
  "project_uuid": "55cc62c0-ebc6-11ec-8c30-b1d2c2514c88",
  "project_name": "Production",
  "message": "Authentication successful"
}

Refiner uses API keys to allow access to the API. You can obtain your personal API key in your Refiner dashboard under "Integrations > Rest API".

Refiner expects the API key to be included in all API requests. Your API key can be provided in three different ways.

The recommended authentication method is to provide your API key as a Bearer token as shown in the example below.

Authorization: Bearer YOUR_API_KEY

Alternatively, you can also provide your API key as a request parameter. For this method, include an api_key=YOUR_API_KEY parameter either in the request URL or in the request body.

As a third option, you can authenticate with the HTTP Basic authentication method by using your API key as the username and leaving the password blank (YOUR_API_KEY:). Please note that the trailing : is needed.

You can verify that your API key works by calling GET https://api.refiner.io/v1/. A successful request returns the environment UUID and name as shown on the right.

You must replace YOUR_API_KEY with your personal API key.

User Tracking

Identify User

In its simplest form, you can just send a user ID or an email to identify a user

curl "https://api.refiner.io/v1/identify-user" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id="Your-User-Id" \
  -d email="user@email.com" \
  -d some_attribute="Manager" \
  -d created_at="2020-08-20T14:48:00.000Z"

Most likely you want to provide additional data

curl "https://api.refiner.io/v1/identify-user" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id="Your-User-Id" \
  -d email="user@email.com" \
  -d some_attribute="Manager" \
  -d another_attribute=true \
  -d created_at="2020-08-20T14:48:00.000Z"

The above commands return JSON structured like this:

{
  "message": "ok",
  "contact_uuid": "15cce3d0-ed5d-11ea-aaef-e58a2a43e996"
}

This endpoint lets you identify users as you would normally do with our JavaScript client. This function is typically used alongside our Javascript client to provide additional user traits which you don't want to expose publicly.

When you identify a user for the first time, a new contact will be created in Refiner. All subsequent calls with the same user ID will update their attributes.

User data provided through this backend call will be merged with data provided by our Web-Client or Mobile SDKs based on the User ID you provide.

You are free to choose the attribute names and what data you are importing. Please note that there are a couple of reserved keywords which have a special function in Refiner.

A successful request returns HTTP status 201. If another identify request for the same user is still in progress, the API returns HTTP 409.

HTTP Request

POST https://api.refiner.io/v1/identify-user

Mandatory Request Parameters

You need to provide either the user ID or an email address to identify your user.

Parameter	Description
id	The ID of the user which you want to identify. If the user does not exist in your Refiner account yet, it will be created automatically.
email	As an alternative to the user ID, you can also identify users with their email address.

User Traits Parameters

You can send in any user traits alongside the user ID or email address as shown in the code sample to the right.

Any user data you send will be attached to the user record as a trait. The trait is identified by the attribute slug and data type (string, date or number). If a trait does not exist in your Refiner account yet, it will be created on the fly.

Type	Description
string	Provide any string data with up to 255 in length (e.g. `country: "france"`, `subscription: "pro"`, ...)
date	When the attribute slug ends with a `_at` (e.g. `created_at: "2022-07-09"`, `upgraded_at: "2022-07-09 10:01:01"`, ...), Refiner will try to parse the string as a date. All standardized date strings (e.g. ISO 8601) should work.
number	Integer numbers are automatically detected if they are not wrapped in quotes (e.g. `a_number: 42`)
boolean	A boolean value that is not wrapped in quotes (e.g. `ok: true`)

Group Users

You provide a nested account object to group users together

curl "https://api.refiner.io/v1/identify-user" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id="Your-User-Id" \
  -d email="user@email.com" \
  -d some_attribute="Manager" \
  -d another_attribute=true \
  -d created_at="2020-08-20T14:48:00.000Z" \
  -d account[id]="Your-Account-Id" \
  -d account[name]="Awesome Inc."

The above command returns JSON structured like this:

{
  "message": "ok",
  "contact_uuid": "15cce3d0-ed5d-11ea-aaef-e58a2a43e996"
}

Refiner stores users as two separate objects, a contact and an account.

Both objects are automatically created when you identify a new user. If you don't provide any additional account data, one account is created alongside each user.

You can however choose to group multiple contacts together under one account.

To do so you need to provide an account object within the payload of your identify-user call as shown in the code example.

At a minimum, your account object needs to contain an id attribute. As with contacts, you can provide additional traits for accounts.

Track Event

Track an event for an existing user by providing their ID and an event name

curl "https://api.refiner.io/v1/track-event" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id="Your-User-Id" \
  -d event="Your event name"

The above command returns JSON structured like this:

{
  "message": "ok"
}

This endpoint provides a simple way to track user events. To track a user event, you need to provide the ID of your user and a name for the event that occurred.

If no user matches the provided id or email, a new user is created.

Event data tracked through this backend call will be merged with event data provided by our Javascript client library.

HTTP Request

POST https://api.refiner.io/v1/track-event

Request Payload

Parameter	Description
id	The ID of the user for which you want to track an event
email	You can also choose to identify a user with their email address
event	The name of the event that you want to track for your user

Responses

Get Responses

Filter by survey and date range

curl -X GET "https://api.refiner.io/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d form_uuid="FORM_UUID" \
  -d date_range_start="2024-01-01" \
  -d date_range_end="2024-12-31"

Filter by survey answers, contact traits, and account traits

curl -X GET "https://api.refiner.io/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d form_uuid="FORM_UUID" \
  -d date_range_start="2024-01-01" \
  -d date_range_end="2024-12-31" \
  -d response_data[nps]=9 \
  -d contact_data[country]="France" \
  -d account_data[plan]="pro"

The above command returns JSON structured like this:

{
  "items": [
    {
      "uuid": "cb47c260-ed64-11ea-8187-a7fc8351fba4",
      "first_shown_at": "2020-09-02 21:53:33",
      "last_shown_at": "2020-09-02 21:53:33",
      "show_counter": 1,
      "first_data_reception_at": "2020-09-02 21:53:33",
      "last_data_reception_at": "2020-09-02 21:53:33",
      "completed_at": "2020-09-02 21:53:33",
      "received_at": "2020-09-02 21:53:33",
      "dismissed_at": null,
      "form": {
        "uuid": "3894dc20-8fe9-11ea-892e-d13af52e06ae",
        "name": "My first survey"
      },
      "data": {
        "first_question": "First Reply",
        "second_question": "Second Reply"
      },
      "contact": {
        "uuid": "e5365340-ed47-11ea-9a73-61d23f380055",
        "remote_id": "YOUR-USER-ID-123",
        "email": "jane@awesome.com",
        "display_name": "Jane Doe",
        "account": {
          "uuid": "5ab55ab0-ebf3-11ea-a442-4fa2c72e1cf7",
          "remote_id": "Your account ID",
          "display_name": "Awesome Inc.",
          "domain": null
        }
      }
    },
    {
      "uuid": "cb47c260-ed64-11ea-8187-a7fc8351fba4",
      "first_shown_at": "2020-09-02 21:53:33",
      "last_shown_at": "2020-09-02 22:53:33",
      "show_counter": 2,
      "first_data_reception_at": null,
      "last_data_reception_at": null,
      "completed_at": null,
      "received_at": null,
      "dismissed_at": null,
      "form": {
        "uuid": "3894dc20-8fe9-11ea-892e-d13af52e06ae",
        "name": "My first survey"
      },
      "data": {
        "first_question": null,
        "second_question": null
      },
      "contact": {
        "uuid": "e5365340-ed47-11ea-9a73-61d23f380055",
        "remote_id": "YOUR-USER-ID-123",
        "email": "jane@awesome.com",
        "display_name": "Jane Doe",
        "attributes": [],
        "account": {
          "uuid": "5ab55ab0-ebf3-11ea-a442-4fa2c72e1cf7",
          "remote_id": "Your account ID",
          "display_name": "Awesome Inc.",
          "domain": null,
          "attributes": []
        }
      }
    },
    ...
  ],
  "pagination": {
    "items_count": 1100,
    "current_page": 1,
    "last_page": 22,
    "page_length": 55,
    "next_page_cursor": "eyJpdiI6ImpCMlY3cERCbEo0Qk1Ge..."
  }
}

This endpoint retrieves all survey views and responses.

Included in the response is the response data itself, information about survey and basic information about the contact who responded.

Like all list calls, the response body contains an items array and a pagination object. For larger data sets (e.g. > 10.000 entries), we recommend cursor based pagination (page_cursor) instead of using numeric page numbers (page). The cursor pointing to the next page is provided in the pagination object as next_page_cursor.

The list is returned in reverse chronological order using the last_data_reception_at field. If include is set to all (survey views included), the last_shown_at field is used for ordering.

When using date_range_start or date_range_end filter, the reference time stamp is last_data_reception_at. If include is set to all (survey views included), the last_shown_at field is used for the date range filter. Please note that both timestamps can evolve over time, for example when using the Follow-Up feature of in-product surveys.

You can further filter the list with response_data, contact_data and account_data. Each parameter is an object of attribute slugs and values (strings, numbers or booleans). When multiple keys are provided, all of them must match.

HTTP Request

GET https://api.refiner.io/v1/responses

Query Parameters

All query parameters are optional. Dates & times need to be provided as a ISO 8601 string (e.g. YYYY-MM-DD or YYYY-MM-DD hh:mm:ss).

Parameter	Default	Description
page	1	Used to paginate through results. On larger result sets we recommend to use the `page_cursor` to go through all results as it is much faster.
page_cursor	null	On larger data sets, we recommend using the page cursor provided in the pagination response as `next_page_cursor` to go through all result pages.
page_length	100	One request can return up to 1000 items
form_uuid	null	Only return responses linked to a specific survey. It is also possible to return results for multiple surveys by using `form_uuids` (with an additional s) and providing an array of UUIDs.
segment_uuid	null	Only return responses for users matching a specific segment. It is also possible to return results for multiple user segments by using `segment_uuids` (with an additional s) and providing an array of UUIDs.
tag_uuid	null	Only return responses tagged with a specific tag. It is also possible to return results for multiple tags by using `tag_uuids` (with an additional s) and providing an array of UUIDs.
date_range_start	null	Only return responses where `last_shown_at` or `last_data_reception_at` is equal or after provided time (see details above)
date_range_end	null	Only return responses where `last_shown_at` or `last_data_reception_at` is before provided time (see details above)
include	completed	Return responses with a certain status. Supported values are `completed`, `partials` (includes partials & completed responses) and `all` (includes dismissed survey views).
search	null	Return only responses where the contact User ID, Refiner UUID, email or name matches your search query.
response_data	null	Only return responses matching the given survey answers (e.g. `response_data[nps]=9`). Keys are question identifiers. All provided keys must match.
contact_data	null	Only return responses matching the given contact traits (e.g. `contact_data[country]=France`). Keys are trait slugs. All provided keys must match.
account_data	null	Only return responses matching the given account traits (e.g. `account_data[plan]=pro`). Keys are trait slugs. All provided keys must match.
with_attributes	null	If set to `1`, the `contact` object of each survey response includes all attributes we have on record for a given user.

Store Responses

curl "https://api.refiner.io/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id="Your-User-Id" \
  -d form_uuid="The-Survey-Uuid" \
  -d a_question_identifier="Some value" \
  -d nps_question=9 \

The above command returns JSON structured like this:

{
  "message": "ok",
  "uuid": "fcbb8b30-3dfe-11f0-a0bf-6b2696a5a3c8"
}

This endpoint lets you store a survey response for a user. It allows you to store historical survey data, or use your own UI for surveying your users.

The endpoint is similar to the identify-user endpoint. The difference is that data provided through this endpoint results in a survey response object.

A form_uuid parameter is required to identify the survey to which you want to attach the response. The survey needs to exist in your Refiner environment, but can be empty and unpublished. You can reuse an existing survey or create a new dummy survey as a container for the responses. You can find the survey ID in the URL when opening the survey editor.

To help Refiner better display survey responses in your dashboard (e.g. NPS values, CSAT ratings, ...), we recommend to create questions in your survey that corresponds to the data you are sending in via the API and use the same question identifiers.

HTTP Request

POST https://api.refiner.io/v1/responses

Mandatory Request Parameters

You need to provide a form_uuid and either the user ID, an email address, or the Refiner contact UUID to identify your user.

Parameter	Description
id	The ID of the user which you want to identify. If the user does not exist in your Refiner account yet, it will be created automatically.
email	As an alternative to the user ID, you can identify users with their email address.
uuid	As an alternative to the user ID or email, you can identify users with their Refiner contact UUID.
form_uuid	The ID of the survey (see above) you want attach the responses to.

Optional Request Parameters

Parameter	Description
date	The date (ISO 8601) when the survey response was initially recorded. The default value is `now`.
prevent_duplicates	By default the API tries to detect and prevent duplicate entries. This option can be disabled by providing a boolean `false` value.
tags	An array of tags to attach to the survey response (max 20 tags).
account	A nested account object to group the user under an account (see Group Users). At a minimum, provide `account[id]`.

Response Data Parameters

You can send in any data alongside the user ID or email address as shown in the code sample to the right.

Any user data you send will be attached to the response record. The survey question is identified by the data slug and data type (string, date or number).

Type	Description
string	Provide any string data with up to 255 in length (e.g. `position: "manager"`)
number	Integer numbers are automatically detected if they are not wrapped in quotes (e.g. `nps_score: 9`)
boolean	A boolean value that is not wrapped in quotes. (e.g. `ok: true`)

Tag Responses

curl "https://api.refiner.io/v1/responses/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d uuid="Survey-Response-UUID" \
  -d tags[]="First tag" \
  -d tags[]="Second tag" \
  -d tags[]="Third tag" \

The above command returns JSON structured like this:

{
  "message": "ok"
}

This endpoint lets you tag an existing survey response. The endpoint expects two parameters, a uuid identifying the survey response and a tags array containing tags you want to add.

HTTP Request

POST https://api.refiner.io/v1/responses/tags

Mandatory Request Parameters

Parameter	Description
uuid	The `uuid` of the survey response you want to tag
tags	An array of tags to the survey response (max 20 tags)

Reporting

Get Reporting

Fetch an NPS report for a survey and date range

curl -X GET "https://api.refiner.io/v1/reporting" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d type=nps \
  -d form_uuids[]="FORM_UUID" \
  -d date_range_start="2024-12-12" \
  -d date_range_end="2025-04-18"

Filter the report by survey answers, contact traits, and account traits

curl -X GET "https://api.refiner.io/v1/reporting" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d type=nps \
  -d form_uuids[]="FORM_UUID" \
  -d date_range_start="2024-12-12" \
  -d date_range_end="2025-04-18" \
  -d response_data[nps]=9 \
  -d contact_data[country]="France" \
  -d account_data[plan]="pro"

Returned JSON for nps report:

{
    "data": {
        "detractors": 5,
        "passives": 21,
        "promoters": 40
    },
    "count": 66,
    "nps": 53,
    "date_range_start": "2024-12-12T08:08:00.000000Z",
    "date_range_end": "2025-04-18T00:00:00.000000Z"
}

Returned JSON for csat report:

{
    "data": {
        "veryunsatisfied": 0,
        "unsatisfied": 2,
        "neutral": 10,
        "satisfied": 37,
        "verysatisfied": 23
    },
    "count": 72,
    "csat": 83,
    "date_range_start": "2024-12-12T08:08:00.000000Z",
    "date_range_end": "2025-04-18T00:00:00.000000Z"
}

Returned JSON for ratings report:

{
    "data": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 1,
        "6": 0,
        "7": 0,
        "8": 0,
        "9": 0,
        "10": 0
    },
    "sum": 5,
    "count": 1,
    "average": 5,
    "date_range_start": "2024-12-12T00:00:00.000000Z",
    "date_range_end": "2025-04-17T15:14:27.541221Z"
}

Returned JSON for distribution report:

{
    "data": {
        "8": 15,
        "9": 16,
        "6": 3,
        "4": 1,
        "7": 6,
        "5": 2,
        "10": 24
    },
    "responses": 66,
    "datapoints": 67,
    "date_range_start": "2024-12-12T08:08:00.000000Z",
    "date_range_end": "2025-04-18T00:00:00.000000Z"
}

Returned JSON for count report:

{
    "views": 148,
    "responses": 130,
    "date_range_start": "2024-12-12T08:08:00.000000Z",
    "date_range_end": "2025-04-18T00:00:00.000000Z"
}

This endpoint retrieves aggregated reporting data similar to our Reporting Dashboards.

Multiple reports are available:

Type	Description
nps	Returns the aggregated NPS rating alongside the response distribution
csat	Returns the aggregated CSAT score alongside the response distribution
ratings	Returns the aggregated rating average alongside the response distribution
distribution	Returns the distribution of all response values
count	Returns the aggregated response and view count

You can further filter reports with response_data, contact_data and account_data. Each parameter is an object of attribute slugs and values (strings, numbers or booleans). When multiple keys are provided, all of them must match.

HTTP Request

GET https://api.refiner.io/v1/reporting

Query Parameters

All query parameters except type are optional. Dates & times need to be provided as a ISO 8601 string (e.g. YYYY-MM-DD or YYYY-MM-DD hh:mm:ss). The default range is set to the last seven days.

Parameter	Default	Description
type	none	Can be `nps`, `csat`, `ratings`, `distribution` or `count` as described above
question_identifiers	all matching questions	Only count data points that correspond to one of the provided question identifiers. If no question identifiers are provided, all questions matching the reporting type are taken into account.
tag_uuids	all tags	Only count data points linked to survey responses that are tagged with one of the provided tags.
form_uuids	null	Only count data points linked to one of the provided forms (surveys).
segment_uuids	null	Only count data points linked to users that are part of one of the provided segments.
date_range_start	7d ago	Only count data points that were recorded after given date time.
date_range_end	end of day	Only count data points that were recorded before given date time.
response_data	null	Only count data points matching the given survey answers (e.g. `response_data[nps]=9`). Keys are question identifiers. All provided keys must match.
contact_data	null	Only count data points matching the given contact traits (e.g. `contact_data[country]=France`). Keys are trait slugs. All provided keys must match.
account_data	null	Only count data points matching the given account traits (e.g. `account_data[plan]=pro`). Keys are trait slugs. All provided keys must match.

Contacts

Get Contacts

curl "https://api.refiner.io/v1/contacts"
  -H "Authorization: Bearer YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "items": [
    {
        "uuid": "15cce3d0-ed5d-11ea-aaef-e58a2a43e996",
        "remote_id": "Your-Contact-ID",
        "email": "jane@awesome.com",
        "display_name": "Jane Doe",
        "first_seen_at": "2020-09-02T20:44:24.000000Z",
        "last_seen_at": "2020-09-02T21:57:50.000000Z",
        "attributes": {
            "a_user_attribute": "Manager",
            "another_one": "Marketing",
            "a_survey_answer": "9",
            "another_answer": "ABC",
            ...
        },
        "segments": [
            {
                "uuid": "0ff87720-9ae5-11ea-bce5-65a395204572",
                "name": "Power Users Segment"
            },
            ...
        ],
        "account": {
            "uuid": "15d08cc0-ed5d-11ea-b2ce-c1b46bd4b7c4",
            "remote_id": "Your-Account-Id",
            "domain": "awesome.com",
            "display_name": "Awesome Inc.",
            "first_seen_at": "2020-09-02T20:44:24.000000Z",
            "last_seen_at": "2020-09-02T21:57:50.000000Z",
            "attributes": {
                "an_account_attribute": "Computer Software",
                "another_one": "2020",
                ...
            }
        }
    },
    ...
  ],
  "pagination": {
    "items_count": 1100,
    "current_page": 1,
    "last_page": 22,
    "page_length": 55,
    "next_page_cursor": "eyJpdiI6ImpCMlY3cERCbEo0Qk1Ge..."
  }
}

This endpoint retrieves all contacts and their associated data.

A contact is created each time you identify a user or when we receive a survey response from an anonymous user.

A contact object consists of an identifier (typically your user ID), meta data, attributes, the segments they belong to and the associated account.

The attributes object consists all data points you provided merged with the survey responses we received.

HTTP Request

GET https://api.refiner.io/v1/contacts

Query Parameters

All query parameters are optional.

Parameter	Default	Description
order_by	first_seen_at	Order the list by `display_name`, `email`, `first_seen_at`, `last_seen_at`, or `last_form_submission_at`
page	1	Used to paginate through results. On larger result sets we recommend to use the `page_cursor` to go through all results as it is much faster.
page_cursor	null	On larger data sets, we recommend using the page cursor provided in the pagination response as `next_page_cursor` to go through all result pages.
page_length	100	One request can return up to 1000 items
form_uuid	null	Only return users linked to a specific survey
segment_uuid	null	Only return users linked to a specific segment
search	null	Only return results where contact email, ID or name matches the search

Get Contact

Identify the contact that you want to get data for with the same ID that you used to identify them.

curl -X GET "https://api.refiner.io/v1/contact" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id="Your-User-Id" \

Alternatively you can also identify them by email address if you don't have an ID.

curl -X GET "https://api.refiner.io/v1/contact" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id="user@email.com" \

The above commands returns JSON structured like this:

{
    "uuid": "15cce3d0-ed5d-11ea-aaef-e58a2a43e996",
    "remote_id": "Your-Contact-ID",
    "email": "jane@awesome.com",
    "display_name": "Jane Doe",
    "first_seen_at": "2020-09-02T20:44:24.000000Z",
    "last_seen_at": "2020-09-02T21:57:50.000000Z",
    "attributes": {
        "a_user_attribute": "Manager",
        "another_one": "Marketing",
        "a_survey_answer": "9",
        "another_answer": "ABC",
        ...
    },
    "segments": [
        {
            "uuid": "0ff87720-9ae5-11ea-bce5-65a395204572",
            "name": "Power Users Segment"
        },
        ...
    ],
    "account": {
        "uuid": "15d08cc0-ed5d-11ea-b2ce-c1b46bd4b7c4",
        "remote_id": "Your-Account-Id",
        "domain": "awesome.com",
        "display_name": "Awesome Inc.",
        "first_seen_at": "2020-09-02T20:44:24.000000Z",
        "last_seen_at": "2020-09-02T21:57:50.000000Z",
        "attributes": {
            "an_account_attribute": "Computer Software",
            "another_one": "2020",
            ...
        }
    }
}

This endpoint lets you fetch all data that we have on record for a specific contact in your Refiner project.

To identify the contact, you need to provide the ID which was used when the contact was created. This is usually user ID which you also use in other tools and databases.

Alternatively you can also identify the user with their email address. Please note that multiple users with the same email address can exists in your account. We recommend to identify a users with their unique ID whenever possible.

Finally, you can also use the automatically generated UUID returned by our API when you create a contact.

HTTP Request

GET https://api.refiner.io/v1/contact

Query Parameters

To identify your users, you need to provide at least one of the following parameters.

Parameter	Description
id	Your user ID
email	The email address of the user
uuid	The automatically generated Refiner UUID

Delete Contact

Identify the contact that you want to delete with the same ID that you used to identify them.

curl -X DELETE "https://api.refiner.io/v1/contact" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id="Your-User-Id" \

Alternatively you can also identify them by email address if you don't have an ID.

curl -X DELETE "https://api.refiner.io/v1/contact" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id="user@email.com" \

The above commands returns JSON structured like this:

{
  "message": "ok"
}

This endpoint lets you delete a contact from your Refiner project.

To delete a contact, you need to provide the ID which was used when the contact was created. This is usually user ID which you also use in other tools and databases.

Finally, you can also use the automatically generated UUID returned by our API when you create a contact.

Deleting a user will also remove their survey responses. If you want to delete a user for compliance reasons but want to keep their survey responses, consider using the identifyUser command to overwrite sensitive user data with empty values.

HTTP Request

DELETE https://api.refiner.io/v1/contact

Query Parameters

To identify your users, you need to provide at least one of the following parameters.

Parameter	Description
id	Your user ID
email	The email address of the user
uuid	The automatically generated Refiner UUID

Forms

Get Forms

Fetch all forms from your account

curl "https://api.refiner.io/v1/forms"
  -H "Authorization: Bearer YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "items": [
    {
        "uuid": "4f5637d0-3d0d-11ea-b965-614418dec30c",
        "name": "My first survey"
    },
    {
        "uuid": "8d752bf0-3d0e-11ea-aeff-d7282664f71b",
        "name": "My second survey"
    },
    ...
  ],
  "pagination": {
    "items_count": 10,
    "current_page": 1,
    "last_page": 1,
    "page_length": 10
  }
}

When include_info is set, additional data fields are included

{
  "items": [
    {
        "uuid": "4f5637d0-3d0d-11ea-b965-614418dec30c",
        "name": "My first survey",
        "channels": [
          "link"
        ],
        "published_at": "2024-06-05T13:02:57.000000Z",
        "archived_at": null,
        "created_at": "2024-06-05T13:02:53.000000Z",
        "updated_at": "2024-06-05T13:02:57.000000Z",
        "responses_count": 0,
        "views_count": 0,
        "first_form_view_at": null,
        "last_form_view_at": null,
        "folder": null,
        "page_url": "https://survey.refiner.io/s/0mn1eq-odkpm3"        
    },
    ...
  ],
  "pagination": {
    "items_count": 10,
    "current_page": 1,
    "last_page": 1,
    "page_length": 10
  }
}

This endpoint retrieves all forms (surveys) ordered by their name.

Like all list calls, the response body contains an items array and a pagination object.

HTTP Request

GET https://api.refiner.io/v1/forms

Query Parameters

All query parameters are optional.

Parameter	Default	Description
list	'all'	Determines which surveys are shown based on their current state. Allowed values are `all`, `published`, `drafts`, `archived`, and `all_with_archived`.
page	1	Used to paginate through all results
page_length	100	One request can return up to 1000 items
include_config	0	If set to `1`, the response includes the configuration of the survey and each survey element. Please note that the format and syntax might slightly change as we are adding more survey features.
include_info	0	If set to `1`, the response includes additional meta data such as the creation and publishing date, response and view counts, as well as the folder a survey belongs to.

Publish Form

Publish or unpublish a form (survey).

curl "https://api.refiner.io/v1/forms/publish" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d form_uuid="FORM_UUID"

The above command returns JSON structured like this:

{
  "message": "Your form was published successfully."
}

This endpoint lets you publish or unpublish an existing form (survey).

HTTP Request

POST https://api.refiner.io/v1/forms/publish

Query Parameters

Parameter	Default	Description
form_uuid	null	The UUID of the form (survey) which you want to publish or unpublish.
published	1	Optional parameter. If set to `0`, the survey is unpublished.

Delete Form

Archive a form

curl -X DELETE "https://api.refiner.io/v1/forms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d form_uuid="FORM_UUID"

The above command returns JSON structured like this:

{
  "message": "ok"
}

This endpoint lets you archive an existing form (survey) in your account.

HTTP Request

DELETE https://api.refiner.io/v1/forms

Query Parameters

Parameter	Description
form_uuid	The UUID of the form (survey) which you want to archive.

Duplicate Form

Duplicate a form

curl "https://api.refiner.io/v1/forms/duplicate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d form_uuid="FORM_UUID" \
  -d name="NEW_FORM_NAME"

The above command returns JSON structured like this:

{
  "message": "ok",
  "source_form_uuid" : "FORM_UUID",
  "new_form_uuid" : "NEW_FORM_UUID"
}

This endpoint lets you duplicate an existing form (survey) in your account. The new form will be stored as a draft and will be named according to the name parameter.

HTTP Request

POST https://api.refiner.io/v1/forms/duplicate

Query Parameters

Parameter	Description
form_uuid	The UUID of the form (survey) which you want to duplicate.
name	The name of the new form.

Change Log

List all previous versions of a form (survey)

curl -X GET "https://api.refiner.io/v1/forms/history" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d form_uuid="FORM_UUID"

The above command returns JSON structured like this:

{
    "items": [
        {
            "uuid": "4cfe55b0-2bc6-11f1-a89d-2107ac9c5d43",
            "action": "update",
            "snapshot": {
                "name": "Net Promoter Score (NPS)",
                "config": {
                    ...
                },
                "channels": [
                    "web-app"
                ],
                "elements": [
                    {
                        "name": "Your Question Goes Here ...",
                        "slug": "your_question_goes_here",
                        "uuid": "04949185-5ced-265c-f18d-7ca8a1b3d1da",
                        "order": 0,
                        "config": {
                            ...
                        },
                        "created_at": "2026-03-09T14:00:06.000000Z",
                        "deleted_at": null,
                        "updated_at": "2026-03-29T23:18:36.000000Z",
                        "element_type": "select",
                        "is_account_related": false,
                        "advanced_config_mode": true,
                        "slug_update_behaviour": 2
                    },
                    {
                        "name": "How likely are you to recommend our service to a friend or colleague?",
                        "slug": "nps",
                        "uuid": "ede973f0-0b49-11f1-b3cb-d77341a53e22",
                        "order": 4,
                        "config": {
                            ...
                        },
                        "created_at": "2026-02-16T15:12:37.000000Z",
                        "deleted_at": null,
                        "updated_at": "2026-03-29T23:18:36.000000Z",
                        "element_type": "nps",
                        "is_account_related": false,
                        "advanced_config_mode": false,
                        "slug_update_behaviour": 2
                    }
                ],
                "updated_at": "2026-03-29T23:18:36.000000Z",
                "published_at": "2026-03-09T13:56:24.000000Z"
            },
            "created_at": "2026-03-29T23:23:32.000000Z"
        },
        {
            "uuid": "9cecaac0-2bc5-11f1-a09e-d19a60eb012d",
            "action": "update",
            "snapshot": {
                "name": "Net Promoter Score (NPS)",
                "config": {
                    ...
                },
                "channels": [
                    "web-app"
                ],
                "elements": [
                    {
                        "name": "Your Question Goes Here ...",
                        "slug": "your_question_goes_here",
                        "uuid": "04949185-5ced-265c-f18d-7ca8a1b3d1da",
                        "order": 0,
                        "config": {
                            ...
                        },
                        "created_at": "2026-03-09T14:00:06.000000Z",
                        "deleted_at": null,
                        "updated_at": "2026-03-29T23:17:17.000000Z",
                        "element_type": "select",
                        "is_account_related": false,
                        "advanced_config_mode": true,
                        "slug_update_behaviour": 2
                    }
                ],
                "updated_at": "2026-03-29T23:17:17.000000Z",
                "published_at": "2026-03-09T13:56:24.000000Z"
            },
            "created_at": "2026-03-29T23:18:36.000000Z"
        }
    ],
    "pagination": {
        "items_count": 18,
        "current_page": 1,
        "last_page": 9,
        "page_length": 2,
        "next_page_cursor": null
    }
}

This endpoint provides access to all changes made to a survey. The response returns a paginated list of survey versions, each capturing the full configuration and the set of questions at that point in time.

HTTP Request

GET https://api.refiner.io/v1/forms/history

Query Parameters

Parameter	Default	Description
form_uuid	none	The UUID of the form (survey)
page	1	Used to paginate through all results
page_length	100	One request can return up to 1000 items

Segments

Get Segments

Fetch all segments from your account

curl "https://api.refiner.io/v1/segments"
  -H "Authorization: Bearer YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "items": [
    {
        "uuid": "4f5637d0-3d0d-11ea-b965-614418dec30c",
        "name": "Power Users",
        "is_manual": true
    },
    {
        "uuid": "8d752bf0-3d0e-11ea-aeff-d7282664f71b",
        "name": "Signed Up 30 Days Ago",
        "is_manual": false
    },
    ...
  ],
  "pagination": {
    "items_count": 10,
    "current_page": 1,
    "last_page": 1,
    "page_length": 10
  }
}

This endpoint retrieves all segments ordered by their name.

Like all list calls, the response body contains an items array and a pagination object.

HTTP Request

GET https://api.refiner.io/v1/segments

Query Parameters

All query parameters are optional.

Parameter	Default	Description
page	1	Used to paginate through all results
page_length	100	One request can return up to 1000 items

Link Users

Add a new or existing user to a manual segment

curl "https://api.refiner.io/v1/sync-segment" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id="Your-User-Id" \
  -d segment_uuid="4f5637d0-3d0d-11ea-b965-614418dec30c"

The above command returns JSON structured like this:

{
  "message": "ok",
  "contact_uuid": "15cce3d0-ed5d-11ea-aaef-e58a2a43e996",
  "segment_uuid": "4f5637d0-3d0d-11ea-b965-614418dec30c"
}

This endpoint allows you to add and remove users to a manual segment in Refiner. You can identify the user either with an id or their email.

If no user matches the provided id or email, a new user is created.

HTTP Request

POST https://api.refiner.io/v1/sync-segment

DELETE https://api.refiner.io/v1/sync-segment

Request Payload

Parameter	Description
id	The ID of the user you want to add or remove
email	You can also choose to identify a user with their email address
segment_uuid	The UUID of the manual segment

Account

Get Account Info

Fetch information about your Refiner account

curl "https://api.refiner.io/v1/account"
  -H "Authorization: Bearer YOUR_API_KEY"

The above command returns JSON structured like this:

{
    "subscription": {
        "plan": "Friends & Family",
        "mtu_count_updated_at": "2024-02-05T16:29:18.000000Z",
        "mtu_count": 9,
        "mtu_limit": 5000,
        "mte_count_updated_at": "2024-02-05T16:29:18.000000Z",
        "mte_count": 128,
        "mpv_count_updated_at": "2024-02-05T16:29:18.000000Z",
        "mpv_count": 42,
        "mpv_limit": 1000000,
        "msr_count_updated_at": "2024-02-05T16:29:18.000000Z",
        "msr_count": 23,
        "msr_limit": 1000
    },
    "environments": [
        {
            "uuid": "55cc62c0-ebc6-11ec-8c30-b1d2c2514c88",
            "name": "Production",
            "mtu": 9,
            "mte": 141,
            "mpv": 42,
            "msr": 23
        },
        {
            "uuid": "489e4c80-8dd0-11ed-99a5-8b847483cb52",
            "name": "Testing",
            "mtu": 0,
            "mte": 0,
            "mpv": 0,
            "msr": 0
        }
    ]
}

This endpoint returns information about your Refiner account, such as your current subscription usage and the environments you've created.

HTTP Request

GET https://api.refiner.io/v1/account

Query Parameters

This route does not require any parameters besides a valid API key.

Errors

Errors are returned with additional information

{
  "error": "Some additional information"
}

The Refiner API uses the following HTTP error codes. Beside returning a HTTP error code in the response header, an error message is included in the JSON response body. Some errors also include a code field with the HTTP status code.

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong or missing.
403	Forbidden -- You don't have permission to access this resource.
404	Not Found -- The requested resource could not be found.
405	Method Not Allowed -- The HTTP method is not supported for this endpoint.
409	Conflict -- Another request for the same user is already in progress.
429	Too Many Requests -- You are doing this too often. Please slow down.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Rate Limits

Hitting a rate limit returns a 429 response

{
  "error": "You are doing this too often. Please slow down.",
  "code": 429
}

The following rate limits apply to all requests made to the Refiner API:

Limit	Description
4,000 requests/min	Per API key
100 requests/min	Per user ID

When a rate limit is exceeded, the API returns HTTP 429 Too Many Requests. Wait until the window resets before retrying. The response includes Retry-After and X-RateLimit-* headers that tell you when you can send the next request.

The per-user limit only applies to endpoints that include a user identifier (id, email or uuid), such as Identify User or Track Event. List endpoints are only subject to the per-API-key limit.