UserBit API Beta

UserBit API can be used for integration with 3rd party services.

Base URL

https://userbit.com/api/

Authentication

UserBit uses OAuth 2.0 for authentication. To use the API, you'd need to add the ID token to the header of your requests. It'll look like the following:

Authorization: Bearer [YOUR_ID_TOKEN]

How to exchange custom token to get ID and refresh token

To get your ID token, get your custom Token from the App. Once you have the custom token, make a call to /v1/access to retreive the access token.

How to refresh the access token

Once the access token expires, you can use the refresh token (received in the call above) to refresh your access token at any time.

ENDPOINT
POST /v1/access

Exchange custom token for ID and refresh token.

const params = {
  token: [CUSTOM_TOKEN],
}

const response = await fetch('https://userbit.com/api/v1/access', {
  method: 'POST',
  body: JSON.stringify(params),
});
console.log(response.json());

Response

{
  "idToken": "id-token-here",
  "refreshToken": "refresh-token-here",
  "expiresIn": "200" // no. of seconds in which the ID token expires.
}
ENDPOINT
POST /v1/token

Exchange custom token for ID and refresh token.

const params = {
  refreshToken: [CUSTOM_TOKEN],
}

const response = await fetch('https://userbit.com/api/v1/token', {
  method: 'POST',
  body: JSON.stringify(params),
});
console.log(response.json());

Response

{
  "idToken": "id-token-here",
  "refreshToken": "refresh-token-here",
  "expiresIn": "200" // no. of seconds in which the ID token expires.
}

Workspaces

List workspaces

List all workspaces that user has access to.

ENDPOINT
GET /v1/workspaces/list

Sample request

const response = await fetch('https://userbit.com/api/v1/workspaces/list', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${ID_TOKEN}`,
  },
});
console.log(response.json());

Response

[
  {
    "id": "workspace-id",
    "label": "My Team",
  },
  ...
]

Repository projects

List projects

List all repository projects in a workspace that user has access to.

Parameters

workspaceId string required
Unique identifier for workspace.
ENDPOINT
GET /v1/projects/list

Sample Request

const params = { workspaceId: 'my-workspace-id' };
const response = await fetch('https://userbit.com/api/v1/projects/list?' + new URLSearchParams(params), {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${ID_TOKEN}`,
  }
});
console.log(response.json());

Response

[
  {
    "id": "project-id",
    "name": "Sample Project",
    "description": "A sample project description"
  },
  ...
]

Insights

List insights

List all insights in a repository project.

Parameters

workspaceId string required
Unique identifier for the workspace.
projectId string required
Unique identifier for the repository project.
ENDPOINT
GET /v1/insights/list

Sample Request

const params = {
  workspaceId: 'my-workspace-id',
  projectId: 'my-project-id',
};
const response = await fetch('https://userbit.com/api/v1/insights/list?' + new URLSearchParams(params), {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${ID_TOKEN}`,
  }
});
console.log(response.json());

Response

[
  {
    "id": "insight-id",
    "title": "Sample Insight",
    "htmlContent": "<p>Content for insight in HTML</p>",
    "textContent": "Content for insight in plain text",
    "createdBy": "Joe Smith",
    "imageUrl": "https://link/to/url",
    "priority": "Low",
  },
  ...
]

Notes

Create or update a note

Create a note in your research repository. If the note already exists, update it.

Parameters

workspaceId string required
Unique identifier for workspace.
projectId string required
Unique identifier for the repository project.
noteId string required
Unique identifier for the note. If already exists, the note will be updated.
title string required
Title for the note.
sourceType string required
Choice
"htmlContent" If content being used for the note is html directly.
"textContent" If content being used for note is plain text.
"htmlFileUrl" If content is html that needs to be downloaded from a remote URL.
content string required
Actual content for the note. if the source is htmlFileUrl then this param should contain the URL.
ENDPOINT
POST /v1/notes/create-update

Sample Request

const params = {
  workspaceId: 'my-workspace-id',
  projectId: 'my-project-id',
  noteId: 'my-note-id',
  title: 'Note Title',
  sourceType: 'htmlContent',
  content: '<p>This is content for my Note.</p>',
};

await fetch('https://userbit.com/api/v1/notes/create-update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${ID_TOKEN}`,
  },
  body: JSON.stringify(params),
});

Surveys

List surveys

List all surveys in a repository project.

Parameters

workspaceId string required
Unique identifier for the workspace.
projectId string required
Unique identifier for the repository project.
ENDPOINT
GET /v1/surveys/list

Sample Request

const params = {
  workspaceId: 'my-workspace-id',
  projectId: 'my-project-id',
};

const response = await fetch('https://userbit.com/api/v1/surveys/list?' + new URLSearchParams(params), {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${ID_TOKEN}`,
  }
});
console.log(response.json());

Response

[
  {
    "id": "survey-id",
    "name": "Survey Name",
  },
  ...
]

List survey questions

List all survey questions given a survey.

Parameters

workspaceId string required
Unique identifier for the workspace.
projectId string required
Unique identifier for the repository project.
surveyId string required
Unique identifier for the survey.
ENDPOINT
GET /v1/surveys/questions/list

Sample Request

const params = {
  workspaceId: 'my-workspace-id',
  projectId: 'my-project-id',
  surveyId: 'my-survey-id',
};

const response = await fetch('https://userbit.com/api/v1/surveys/questions/list?' + new URLSearchParams(params), {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${ID_TOKEN}`,
  }
});
console.log(response.json());

Response

[
  {
    "id": "survey-question-id",
    "content": "question content",
    "order": 2, // order of qustion in survey
  },
  ...
]

Create a survey response

List all survey questions given a survey.

Parameters

workspaceId string required
Unique identifier for the workspace.
projectId string required
Unique identifier for the repository project.
surveyId string required
Unique identifier for the survey.
surveyId string required
Unique identifier for the survey.
participantId string required
Unique identifier for the participant (eg. email).
participantName string required
Name for survey participant.
question1 Id dynamic string required
question2 Id dynamic string required
...
Add each question's id as the property and the response as value.
ENDPOINT
GET /v1/surveys/questions/list

Sample Request

const params = {
  workspaceId: 'my-workspace-id',
  projectId: 'my-project-id',
  surveyId: 'my-survey-id',
  participantId: 'participant@survey.com',
  participantName: 'Participant Name',
};

const questions = [
  {
    id: 'first-question',
    content: 'What is your name?'
  },
  {
    id: 'second-question',
    content: 'Where do you work?'
  },
  ...
];

const answers = [
  'Joe Smith',
  'Apple Inc.',
]

questions.forEach((question, i) => {
  params[question.id] = answers[i];
});

await fetch('https://userbit.com/api/v1/surveys/questions/list', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${ID_TOKEN}`,
  },
  body: JSON.stringify(params),
});