NAV
shell

Introduction

Welcome to the Refiner API!

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 uses the JSON format and all requests made to the API need to be JSON encoded. All requested data is returned JSON encoded.

Query parameters and data that is sent to the API can either be provided as URL parameters or inside the the request body as a JSON object.

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: 

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 for 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 the your API key as request a 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.

HTTP Request

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

Track Users

Identify a 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 returns 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.

User data provided through this backend call will be merged with data provided by our Javascript client library based on the User ID you provide.

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.

HTTP Request

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

Group users

You provide an 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.

HTTP Request

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

Track event

Track a user event by providing a user ID and an event name

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

The above commands 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 occured.

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

Responses

Get All Responses

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

The above command returns JSON structured like this:

{
  "items": [
    {
      "uuid": "cb47c260-ed64-11ea-8187-a7fc8351fba4",
      "received_at": "2020-09-02 21:53:33",
      "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",
      "received_at": "2020-09-02 21:53:33",
      "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
        }
      }
    },
    ...
  ],
  "pagination": {
    "items_count": 1100,
    "current_page": 1,
    "last_page": 22,
    "page_length": 55
  }
}

This endpoint retrieves all survey responses in reverse chronological order.

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.

HTTP Request

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

Query Parameters

All query parameters are optional. Dates need to be provided as a ISO 8601 string (YYYY-MM-DD).

Parameter Default Description
page 1 Used to paginate through all results
page_length 50 One request can return up to 1000 list times
form_uuid null Only return responses linked to a specific survey
segment_uuid null Only return responses for users matching a specific segment
date_range_start null Only return responses given on or after provided date
date_range_end null Only return responses given on or before provided date

Receive as Webhook

Instead of polling our API continously for new contact data, we recommend to use our Webhook integration to receive new data in real time.

Contacts

Get All 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
  }
}

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.

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

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 first_seen_at, last_seen_at, display_name or email
page 1 Used to paginate through all results
page_length 50 One request can return up to 1000 list times
form_uuid null Only return responses linked to a specific survey
segment_uuid null Only return responses for users matching a specific segment

Receive as Webhook

Instead of polling our API continously for new contact data, we recommend to use our Webhook integration to receive new data in real time.

Forms

Get All 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"
  }
}

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
page 1 Used to paginate through all results
page_length 50 One request can return up to 1000 list times

Segments

Get All 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"
    },
    {
        "uuid": "8d752bf0-3d0e-11ea-aeff-d7282664f71b",
        "name": "Signed Up 30 Days Ago"
    },
    ...
  ],
  "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 50 One request can return up to 1000 list times

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, a error message is included in the JSON response body.

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
429 Too Many Requests -- You're requesting too many kittens! 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.