Introduction
Approved partners and organizations can use the features, APIs and integrations described in this document to provide a deeper level of integration for their users between their applications and the Big Interview system.

Partner API: Getting Started
This section describes generating API Keys for authenticating requests, making those requests, and the API endpoints available to your organization. Some of these endpoints go hand-in-hand with our integration guides below. For instance, our Single Sign On integration requires generating a temporary token through our API before redirecting your user to the Big Interview application.

Everything you need to communicate with the Big Interview Partner API is described in the sections below.

API Keys
To access the API described below, you need to generate API Keys through your organization’s admin area. It can be reached by replacing {org} in the following url with the subdomain for your organization:

https://{org}.biginterview.com/login/admin

Logging in and managing API Keys requires that an administrator account has already been created for you.

Once there, a link entitled** API Settings** will be visible in the dropdown list under your name in the top navigation menu. Visiting that section will allow you to both create and delete API Keys for your organization. Our API Keys will take the format of a 32 character, randomized string similar to the following example key:

935d85189822bf96c28c4fa79d3d8f31

It is important to note that API Keys are not specific to the admin that created them and that all API Keys generated for an organization will be visible to all administrators of that organization. There are plans to provide scoped access on a per-user basis to the organization admin area, but they have not been implemented.
Once you have at least one valid API key for your organization you will be able to access the endpoints specific to your organization in the way described in the section below.

Making Requests

Once your organization has at least one API Key, you can start making requests to the Big Interview API. These requests should, at a minimum, take the following HTTP format:


Take, for example, the following scenario for XYZ Corporation:

They have a Big Interview account at${color}[#e51010]( xyz.biginterview.com.)
They created the following API Key: 935d85189822bf96c28c4fa79d3d8f31.
They would like to get a user’s track progress and that user has a${color}[##e51010]( partner_id) of ${color}[##e51010](abc123def.)

A request based on that information will, at a minimum, have the following HTTP format:



Identifying Users

Most REST-based APIs identify singular resources by a unique id attribute. For example, fetching a single User in any given API might have a resource URI like /users/:id. Most of the time, the application backing the API will generate these unique ids for you, however, the Big Interview Partner API works a bit differently in that these unique ids are actually supplied by the partner during initial account creation.

When making API calls on behalf of a user, you will be responsible for supplying a partner_id attribute that will uniquely identify the user in your system.

The only instance in which you will not be providing the API with the partner_id is in the case of Anonymous Users, which is explained below.

ID Format
The partner_id provided should abide by the following rules.

May contain any number: 0-9.
May contain any letter (lower or uppercase): a-z/A-Z.
May contain a - (dash) or a _ (underscore).
May not contain any other characters.

Anonymous Users

The ability to create temporary, anonymous users must be approved by Big Interview before your organization can utilize this feature.
Simply put, anonymous users are just regular users. However, there are two significant differences between them:

These users are* temporary.** Anonymous accounts will remain active for 24 hours. Big Interview reserves the right to delete these accounts at any point after the initial 24-hour period.
An anonymous user’s partner_id is generated by the API. It is unique to our system and will be returned in the create response.

Those differences aside, you can use the partner_id returned from the create response anywhere else in the API that a partner_id is referenced or required. Again, you can find out how to create anonymous users by reading our API method documentation.

API Errors

Big Interview uses basic HTTP response codes to indicate success or failure of a request. For the most part, codes in the 2xx range indicate a success, codes in the 4xx range indicate a failure due to the information provided by the client, and codes in the 5xx range indicate a server error on our part.

Error Responses


Whenever possible, we will return an error object in the JSON response containing the following attributes:



Partner API: Reference
Users
A user is a unique record who shares a single account between your partner application and Big Interview.

Endpoints that result in the creation of a user account also handle the initial generation of Single Sign On tokens. All responses to these endpoints will include a token object as part of the response. These tokens follow the same rules outlined in the Create/Refresh a User endpoint.

The user object
The following describes the attributes related to a response containing user information.



Create an Anonymous User
POST /api/users/anonymous
Anonymous users are simply temporary user’s whose partner_id is generated by the API. Read the Anonymous Users section for more information.

Request


Response



Create/Refresh a User
POST /api/users/{partner_id}
Creating a User or refreshing their token in the Big Interview system both can be done with the same endpoint. This simplifies the process of ensuring User accounts exist on our system and reduces the functional and logical overhead on your end. Essentially, this endpoint is idempotent. User accounts are never duplicated, and the parameters required during create are simply ignore when submitted for an existing user.

Partner ID
As noted in the Identifying Users section, it is your responsibility to ensure that the partner_id is unique in your system for the user being created. That attribute is supplied here as part of the URI structure. For example, a user with a partner id of 123 will have the URI endpoint /api/users/123.

There is currently no way to update an existing user’s partner_id in our system.

Tokens

This endpoint also returns a token object in it’s response. Tokens allow user’s from your application to login to Big Interview through our Single Sign On integration without the need to enter a password. That process utilizes tokens generated by this endpoint.

Token Expiration
All tokens expire 48-hours after they are created. They cannot be used as part of our SSO integration after they expire, however, a user’s token is automatically refreshed when making a call to this endpoint.

Params

Z



Track Progress
Big Interview currently offers two guided learning tracks to get users started utilizing all the content the service has to offer. In the app, we display this information as a progress bar linked to a panel presenting a step-by-step guide to completing the track:

App Tracks

The track object
The following describes the attributes related to a response containing track progress information.



List track progress
GET /api/users/{partner_id}/tracks
Through this endpoint, you can access the exact same information displayed on these panels and display it back to users inside your application.

Request



Response





Interviews
The ability to participate in mock interview sessions is one of the defining features of the Big Interview application.

The interview object
The following describes the attributes related to a response containing interview information.



List interviews

GET /api/users/{partner_id}/interviews
Through this endpoint, you can access information pertaining to these interviews for a specific user.

This endpoint returns every interview the user has associated with their account ordered by most recently updated to least recently updated.

Request



Response



Partner Integrations

Single Sign On
Our Single Sign On integration allows users of your application to login to Big Interview without having to enter a password. This is accomplished by generating a token using our Partner API and redirecting the user to a specific URL with that token.

Overview
The Single Sign On Integration is a simple, 2-step process, both being outlined below:



Generate an SSO Token
Redirect to Big Interview with the token
Step 1: Generating the SSO Token
Generating the token needed for Single Sign On is outlined in the our API docs above, but the following might be an example request and response for a user with a partner_id of abc123:



The user.token object contains the token attribute which should be used in Step 2 of the Single Sign On process. In the above example, this would be 19633c68.

Step 2: Redirecting to Big Interview
With the token from Step 1 in hand, your client should then redirect the user to your organizations SSO URL. That URL will take the following format:


Assuming XYZ Corporation has a Big Interview application at the xyz subdomain, and they would like to login the user using the token returned from Step 1, the SSO Redirect URL will take the following format:


After performing this redirect, the Single Sign On process is complete and your user will be logged in to the Big Interview web application.

SSO Secondary Redirects
By default, users signing in to Big Interview through the SSO integration will be redirected to the member dashboard, which is at the following URL:


To have this integration redirect the user to different section of the Big Interview application, you can supply a redirect_to parameter to the SSO login resource URL and we will point the user there after login instead.

Example
Say you want to direct the user to a yet to be completed item in one of Big Interview’s track guides and you have the following information:

You have the following SSO token for one of their users: 935d85189822bf9c.
You would like to direct that user to an uncompleted track located at /members/curriculum?chapter=6.
We can do that with the following URL parameters:



User Return URL
By default, your users will be redirected to the Big Interview landing page for your organization after they logout. If that is not where you would like them to end up, you can supply us with a return_url parameter during the SSO login. For instance, if you want the user to be redirected to https://google.com/ after they logout, you would construct your SSO login url like so:



Webhooks
Webhooks are a system of automated notifications indicating that an event has occurred which was linked to one of your users in our system. Rather than requiring you to pull information via our API, webhooks push information to your destination when important events occur.

Notifications are are delivered via HTTP POST requests to a destination endpoint on your server and are sent based on a list of events. Each webhook contains a notification type and the full API object that the notification is reporting on. This information can be used to update your system or to trigger business processes.

Registering webhooks
Registering a webhook can be done through your organization’s admin area, which you can reach by replacing {org} in the following url with the subdomain for your organization:



Handling webhooks
Assuming the following webhook registration details:

URL: https://app.mywebsite.com/webhooks/biginterview
Key: 935d85189822bf96c28c4fa79d3d8f31
Your endpoint should be able to handle the following request:



Retries
We will resend webhook notifications every 10 minutes for a total of 6 attempts over an one hour until both of the following are true:

The webhook completes within 30 seconds.
The webhook receives a 200 response.

Volume and Order
We strive to send webhook notifications as quickly as events occur in our system and in the exact order that they occurred. It is possible that, if your system does not handle our requests correctly and in a timely fashion, you may receive events out of order or in an order that does not match with your system.

The webhook object
The following describes the attributes related to a webhook. Please note that the actual webhook POST-ed to your server will be additionally namespaced under the webhook key.


List of Events
The following is a list of events our webhook notification service will send out.

Was this article helpful?
Cancel
Thank you!