HomeGuidesAPI Reference

Data API

Starred's Data API is a premium paid feature. Reach out to your Customer Success Manager to learn more.

Suggest Edits

Overview

The Starred DATA API provides you access to all data generated through your respondents. You can get all of the information that is available inside Starred dashboards for further analysis and merge it with your internal/own data to create new insights about your hiring strategy, employee engagement, and many more.

Accessing directly from BI Tools

The majority of BI tools permit you to introduce RestApi as a data source.

Data objects explained

Net Promoter Score (NPS)

The NPS measures the eagerness of respondents to recommend a company's products, processes, or services to others.

Customer Effort Score (CES and CES2)

Customer Effort Score is a metric derived from a customer satisfaction survey that measures a product or service's ease of use to customers. A Customer Effort Score reflects the amount of effort a customer had to exert to use a product or service, find the information they needed, or get an issue resolved. You can read more about CES and CES2 here.

Open-ended Questions

These types of questions allow users to express their opinion using their own words.

Star rating

Star rating is another type of question that has five sub-questions which are answered using star ratings. Grid questions can also be boolean, multiple choice and rating questions.

Please note: If respondents skip a grid question or if they answer with n/a, you will receive a 0 (zero) in the grid ratings. We recommend excluding these from your data.

Custom fields (Tags)

In certain situations you might need to add additional parameters to track your users and know, for instance by which recruiter the survey invitation has been sent to measure their performance. Such variables are called custom fields. For historical reasons, custom fields are also known as tags.

Attentions

  • you see a comment symbol that gives respondents the opportunity to add a comment next to their rating;
  • not all the surveys have all of these elements as you are in control of what you add to your survey;
  • If your survey has multiple languages, for that survey you get two sets of answers in each language, and maybe you think it is a duplication, but filtering over the language field, you can deduplicate the results.

HTTPS Support

Starred API doesn't have support for Transport Layer Security (TLS) 1.0 due to the security issues with this protocol. We only support Transport Layer Security (TLS) 1.1 and TLS 1.2

All API requests must be made over HTTPS. Calls made over plain HTTP are not supported.

API Endpoint

The base URL for Starred Data API's is

https://data-api.starred.com/

Output format: comma separated file (CSV)

Authentication

The Starred API uses API-token authentication. Authenticate the requests when using the API by including the Authorization header in the request. You can manage your API-tokens in your Company Settings

Generate token

1440

Generate Token

How you use your Authentication token to fetch data from Postman
We suggest using Postman allows you to run end-to-end API tests to test the functionality of your API.

2020

How you use your Authentication token to fetch data from Postman

Multiple ways of downloading data

For your convenience, we designed multiple ways to download your data

  • Download based on the question types
  • Download in Batch mode
  • Download Batch monthly data

Attention: In some cases, it is possible that a survey does not have all of these question types. In such cases, you do not have any data for that type of question. You will receive '404 Not Found Error' in the case of running the API for that question type.

Notice: In order to control the data size, we only kept tag values in the custom fields (tags)tables. So, if you use Batch or Incremental mode, you need to download custom fields (tags) separately and merge them on your side.

Download data based on question type

If you have plenty of data or you are interested in some part of the answers, you can use these endpoints. There are seven different tables which are:

  • Invitations (invitations information)
  • Open-ended
  • NPS
  • Grid
  • CES
  • CES2
  • Tags

In the following, you can see the schema of each of these tables:

Invitations table schema

|-- companyName: string (nullable = true)
 |-- formId: string (nullable = true)
 |-- formTitle: string (nullable = true)
 |-- ratingId: string (nullable = true)
 |-- invitationId: string (nullable = true)
 |-- dateRequested: string (nullable = true)
 |-- dateAnswered: string (nullable = true)
 |-- senderEmailAddress: string (nullable = true)
 |-- senderFirstName: string (nullable = true)
 |-- journeyType: string (nullable = true)
 |-- senderLastName: string (nullable = true)
 |-- respondentEmailAddress: string (nullable = true)
 |-- respondentFirstName: string (nullable = true)
 |-- respondentLastName: string (nullable = true)
 |-- defaultLanguageName: string (nullable = true)
 |-- anonymous: string (nullable = true)
 |-- subject: string (nullable = true)
 |-- responseURL: string (nullable = true)

https://data-api.starred.com/etl/table/invitations

Open-ended table schema

|-- formId: string (nullable = true)
 |-- ratingId: string (nullable = true)
 |-- openEndedBlockType: string (nullable = true)
 |-- openEndedBlockTitle: string (nullable = true)
 |-- openEndedComment: string (nullable = true)
 |-- openEndedQuestion: string (nullable = true)
 |-- language: string (nullable = true)
 |-- openEndedQuestionId (nullable = true)

https://data-api.starred.com/etl/table/openended

NPS table schema

|-- formId: string (nullable = true)
 |-- ratingId: string (nullable = true)
 |-- npsQuestion: string (nullable = true)
 |-- npsQuestionId string (nullable = true)
 |-- npsRating: string (nullable = true)
 |-- npsComment: string (nullable = true)
 |-- language: string (nullable = true)
 |-- npsQuestionId (nullable = true)
 |-- npsGeneralQuestion (nullable = true)
 |-- npsGeneralComment (nullable = true)

https://data-api.starred.com/etl/table/nps

Grid table schema

|-- formId: string (nullable = true)
 |-- ratingId: string (nullable = true)
 |-- gridBlockQuestion: string (nullable = true)
 |-- gridQuestion: string (nullable = true)
 |-- gridRating: string (nullable = true)
 |-- gridComment: string (nullable = true)
 |-- language: string (nullable = true)
 |-- gridQuestionId (nullable = true)
 |-- gridBlockId (nullable = true)
 |-- blockTitle (nullable = true)

https://data-api.starred.com/etl/table/grid

CES2 table schema

|-- formId: string (nullable = true)
 |-- ratingId: string (nullable = true)
 |-- ces2Question: string (nullable = true)
 |-- ces2Rating: string (nullable = true)
 |-- ces2Comment: string (nullable = true)
 |-- language: string (nullable = true)
 |-- ces2QuestionId (nullable = true)

https://data-api.starred.com/etl/table/ces2

CES table schema

|-- formId: string (nullable = true)
 |-- ratingId: string (nullable = true)
 |-- cesQuestion: string (nullable = true)
 |-- cesRating: string (nullable = true)
 |-- cesComment: string (nullable = true)
 |-- language: string (nullable = true)
 |-- cesQuestionId (nullable = true)

https://data-api.starred.com/etl/table/ces

Tags schema

information about tagCategory and tagValues are stored in this table

 |-- formId: string (nullable = true)
 |-- invitationId: string (nullable = true)
 |-- recruiter: string (nullable=true)
 |-- source: string (nullable=true)
 |-- department: string (nullable=true)
 |-- sourcer: string (nullable=true)
 |-- coordinator: string (nullable=true)
 |-- hiringmanager: string (nullable=true)
 |-- location: string (nullable=true)
 |-- country: string (nullable=true)
 |-- region: string (nullable=true)
 |-- application_id: string (nullable=true)
 |-- time_to_process: string (nullable=true)
 |-- office: string (nullable=true)
 |-- job_name: string (nullable=true)
 |-- rejection_stage: string (nullable=true)
 |-- tagCategory1: string (nullable = true)
 |-- tagCategory2: string (nullable = true)
 |-- tagCategory3: string (nullable = true)
 |-- tagCategory4: string (nullable = true)
 |-- tagCategory5: string (nullable = true)
 |-- tagCategory6: string (nullable = true)
 |-- tagCategory7: string (nullable = true)
 |-- tagCategory8: string (nullable = true)
 |-- tagCategory9: string (nullable = true)
 |-- tagCategory10: string (nullable = true)
 |-- tagCategory11: string (nullable = true)
 |-- tagCategory12: string (nullable = true)
 |-- tagCategory13: string (nullable = true)
 |-- tagCategory14: string (nullable = true)
 |-- tagCategory15: string (nullable = true)
 |-- tagCategory16: string (nullable = true)
 |-- tagCategory17: string (nullable = true)
 |-- tagCategory18: string (nullable = true)
 |-- tagCategory19: string (nullable = true)
 |-- tagCategory20: string (nullable = true)
 |-- tagCategory21: string (nullable = true)
 |-- tagCategory22: string (nullable = true)
 |-- tagCategory23: string (nullable = true)
 |-- tagCategory24: string (nullable = true)
 |-- tagCategory25: string (nullable = true)
 |-- tagCategory26: string (nullable = true)
 |-- tagCategory27: string (nullable = true)
 |-- tagCategory28: string (nullable = true)
 |-- tagCategory29: string (nullable = true)
 |-- tagCategory30: string (nullable = true)
 |-- tagCategory31: string (nullable = true)
 |-- tagCategory32: string (nullable = true)
 |-- tagCategory33: string (nullable = true)
 |-- tagCategory34: string (nullable = true)
 |-- tagCategory35: string (nullable = true)
 |-- tagCategory36: string (nullable = true)
 |-- tagCategory37: string (nullable = true)
 |-- tagCategory38: string (nullable = true)
 |-- tagCategory39: string (nullable = true)
 |-- tagCategory40: string (nullable = true)
 |-- tagCategory41: string (nullable = true)
 |-- tagCategory42: string (nullable = true)
 |-- tagCategory43: string (nullable = true)
 |-- tagCategory44: string (nullable = true)
 |-- tagCategory45: string (nullable = true)
 |-- tagCategory46: string (nullable = true)
 |-- tagCategory47: string (nullable = true)
 |-- tagCategory48: string (nullable = true)
 |-- tagCategory49: string (nullable = true)
 |-- tagCategory50: string (nullable = true)
 |-- tagValue1: string (nullable = true)
 |-- tagValue2: string (nullable = true)
 |-- tagValue3: string (nullable = true)
 |-- tagValue4: string (nullable = true)
 |-- tagValue5: string (nullable = true)
 |-- tagValue6: string (nullable = true)
 |-- tagValue7: string (nullable = true)
 |-- tagValue8: string (nullable = true)
 |-- tagValue9: string (nullable = true)
 |-- tagValue10: string (nullable = true)
 |-- tagValue11: string (nullable = true)
 |-- tagValue12: string (nullable = true)
 |-- tagValue13: string (nullable = true)
 |-- tagValue14: string (nullable = true)
 |-- tagValue15: string (nullable = true)
 |-- tagValue16: string (nullable = true)
 |-- tagValue17: string (nullable = true)
 |-- tagValue18: string (nullable = true)
 |-- tagValue19: string (nullable = true)
 |-- tagValue20: string (nullable = true)
 |-- tagValue21: string (nullable = true)
 |-- tagValue22: string (nullable = true)
 |-- tagValue23: string (nullable = true)
 |-- tagValue24: string (nullable = true)
 |-- tagValue25: string (nullable = true)
 |-- tagValue26: string (nullable = true)
 |-- tagValue27: string (nullable = true)
 |-- tagValue28: string (nullable = true)
 |-- tagValue29: string (nullable = true)
 |-- tagValue30: string (nullable = true)
 |-- tagValue31: string (nullable = true)
 |-- tagValue32: string (nullable = true)
 |-- tagValue33: string (nullable = true)
 |-- tagValue34: string (nullable = true)
 |-- tagValue35: string (nullable = true)
 |-- tagValue36: string (nullable = true)
 |-- tagValue37: string (nullable = true)
 |-- tagValue38: string (nullable = true)
 |-- tagValue39: string (nullable = true)
 |-- tagValue40: string (nullable = true)
 |-- tagValue41: string (nullable = true)
 |-- tagValue42: string (nullable = true)
 |-- tagValue43: string (nullable = true)
 |-- tagValue44: string (nullable = true)
 |-- tagValue45: string (nullable = true)
 |-- tagValue46: string (nullable = true)
 |-- tagValue47: string (nullable = true)
 |-- tagValue48: string (nullable = true)
 |-- tagValue49: string (nullable = true)
 |-- tagValue50: string (nullable = true)

https://data-api.starred.com/etl/table/tags

Based on your demand after downloading the data, you can join these tables to have a general overview of your data.

TagCategories and tagValues are matched based on their numbers, it means tagCategory1 is holding the title for the value that is stored in tagValue1 and etc.

How to Join these table to get the whole data?

As in each data table, question and answer exist, you only need to join the table over formId and ratingId or in the case of tags, formId and invitationId. Notice that not all of the forms have different kinds of questions, so you may need to consider Left-outer-Join or Right-outer-join. The essential data like sender, receiver, date, and tags are available in the tags table which can be the main element of your join tables.

for joining tag values you can join over formId and invitationId.

invitations.join(tags, on=["formId","invitationId"])

Download your data in Batch Mode

For accessing the whole of your data in CSV format you need to call the Data API base URL with ‘/etl’ extension:

https://data-api.starred.com/etl

Data Structure

Below you can see the data schema of the Data API.

|-- formId: integer (nullable = true)
 |-- ratingId: integer (nullable = true)
 |-- companyName: string (nullable = true)
 |-- formTitle: string (nullable = true)
 |-- invitationId: integer (nullable = true)
 |-- dateRequested: timestamp (nullable = true)
 |-- dateAnswered: timestamp (nullable = true)
 |-- senderEmailAddress: string (nullable = true)
 |-- senderFirstName: string (nullable = true)
 |-- journeyType: string (nullable = true)
 |-- senderLastName: string (nullable = true)
 |-- respondentEmailAddress: string (nullable = true)
 |-- respondentFirstName: string (nullable = true)
 |-- respondentLastName: string (nullable = true)
 |-- npsQuestion: string (nullable = true)
 |-- npsRating: integer (nullable = true)
 |-- npsComment: string (nullable = true)
 |-- openEndedBlockType: string (nullable = true)
 |-- openEndedBlockTitle: string (nullable = true)
 |-- openEndedComment: string (nullable = true)
 |-- openEndedQuestion: string (nullable = true)
 |-- cesQuestion: string (nullable = true)
 |-- cesRating: integer (nullable = true)
 |-- cesComment: string (nullable = true)
 |-- ces2Question: string (nullable = true)
 |-- ces2Rating: integer (nullable = true)
 |-- ces2Comment: string (nullable = true)
 |-- gridBlockQuestion: string (nullable = true)
 |-- gridQuestion: string (nullable = true)
 |-- gridRating: integer (nullable = true)
 |-- gridComment: string (nullable = true)
 |-- gridBlockId (nullable = true)
 |-- blockTitle (nullable = true)
 |-- language: string (nullable = true)
 |-- defaultLanguageName (nullable = true)

Field descriptions

  • formId: unique integer number for each survey in each company

  • ratingId: every reply that you receive from the candidate will have a unique id as rating

  • companyName: name of your company

  • formTitle: title of the survey

  • _invitationId: _unique integer that is assigned to each invitation

  • _department: _department associated with job or candidate

  • _sourcer: _person responsible for sourcing

  • hiringManager: person responsible for sourcing

  • _location: _location associated with job or candidate

  • _country: _country associated with job or candidate

  • _region: _region associated with job or candidate

  • _applicationID: _unique identifier for combination of job and candidate

  • _timeToProcess: _amount of days between start and end of process for a candidate or application

  • _office: _office associated with job or candidate

  • _jobName: _name of job

  • _rejectionStage: _stage of job where candidate was rejected

  • _coordinator: _person responsible for coordinating the hiring process

  • _dateRequested: _the date and time that the invitation is sent

  • _dateAnswered: _the date and time that the candidate replies to the survey

  • senderEmailAddress: sender email

  • senderFirstName: the name of the sender of the survey

  • senderLastName: the last name of the sender of the survey

  • respondentEmailAddress: email address of candidate who receives the invitation

  • respondentFirstName: first name of the candidate

  • respondentLastName: last name of the candidate

  • journeyType: name of the journey type

  • _tagValue1-50: _these are customized labels that can be defined by each company

  • npsQuestion: question for NPS type

  • npsComment: candidate’s comment to NPS type question

  • npsRating: rating of the candidate to NPS question

  • openEndedQuestion: open-ended question

  • openEndedComment: candidate’s comment to open-ended question

  • cesQuestion: ces type question

  • cesComment: candidate’s comment to CES type question

  • cesRating: rating of the candidate to CES question

  • ces2Question: CES2 type question

  • _ces2Comment: _candidate’s comment to CES2 type question

  • ces2Rating: rating of the candidate to CES question

  • gridQuestion: grid question type

  • gridComment: candidate’s comment to grid type question

  • gridRating: rating of the candidate to grid question

  • gridBlockQuestion: each grid block question can have up to five grid question

  • language: the language of the form that the answer is received

  • defaultLanguageName: the default language of the form

  • subject: grid5x5 subject

  • anonymous: it shows whether the respondent could be remained anonymous

  • responseURL: URL of the response

Download batch-mode based on year and month

If you only need to download your data in a specific month, you just need to provide ‘year’ and ‘month’ as query parameters to fetch data:

https://data-api.starred.com/etl/monthly?year=2021&month=06

in this case the schema is exactly the same as the batch mode’s schema.

Accessing Programmatically

Most modern programming languages let you access RestAPI data. Below you can see a snippet that is written in Python:

import requests
  
header = {'Authorization':'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'}

r = requests.get('https://data-api.starred.com/etl', headers=header)
print(r.text)

Attention Some programming languages such as R (HTTR package) try to call the redirected URL from API call with the header again and it can cause 400 errors.

Accessing directly from BI Tools

The majority of BI tools permit you to introduce RestApi as a data source.

For example in Excel or Power BI, you must select ‘From Web’ or 'Web' and in advance mode, set the correct URL and header (https://docs.microsoft.com/en-us/power-query/connectors/web/web).

Please note: all date/time values are in UTC time zone.

Updated 24 days ago