API Documentation

Overview

Version 1.2
Last updated November 11, 2017

Integrating with the Firsthand API gives you real time insights into how your platform is performing, which advisees are making the most of the service, and which advisors are providing the best value.

To integrate, simply activate an API key, format a request, and parse the response.

For additional assistance, please contact support@vault.com.

Requests

A request to the Firsthand API has 2 parts

  1. A valid Firsthand API Key
  2. An endpoint

1. A valid Firsthand API Key

Visit your Settings page to manage your API keys. Current protocols limit your dashboard to only 1 active API key at a time, but you can generate a new one whenever you'd like.

To authenticate your requests, you will send this API Key with every request in an HTTP header named Firsthand-Api:

If you don't see a section titled API Key on your settings page, please contact your customer success representative or email us at support@vault.com to learn how to join our API platform.


2. An endpoint

All API requests must be pointed towards api.firsthand.co. The type of data returned will be determined entirely by the URI that follows, this is what we call the endpoint.

For example, to get all completed consultations, you would make a request to:

api.firsthand.co/consultations

In the above example, /consultations is the endpoint. For a complete list of all endpoints, see the sub bullets in the navigation section titled Endpoints.



Sending data in the HTTP body

Any operation wherein your application sends data in the body of your HTTP request (for example POST and PUT requests), this data should be transmitted in x-www-form-urlencoded format using key-value pairs. A sample HTTP request may look like this:

In the above example, the user is modifying a specific User, identified by the ID "123456" in our system, and setting his or her "externalid" parameter (that is, the ID used within the user's system to be "98765".

For more information about x-www-form-urlencoded HTTP bodies, please read the W3C spec.

Responses

All responses will adhere to a specific data structure with the primary data package (the data specific to the endpoint being queried) contained inside. The anatomy of a response body is displayed below with annotations.

Successful Response

A successful response is one where we received your request with proper authentication headers (see requests section) processed any associated query parameters, and were able to formulate a response.


Failed Response - Forbidden

In the event that you receive a 403 error, please double check that you sent the correct header, Firsthand-Api, with an active API Key. For more, please refer to the requests section.


Failed Response - Not Found

In the event that you receive a 404 error, please double check that the endpoint you are attempting to access does exist and that any query parameters you are passing are defined in the documentation.


Failed Response - Internal Server Error

In the event that you receive a 500 error, please ensure that any query parameters you are passing are defined in the documentation and are of the correct type. If you continue to receive this error, please contact support@vault.com.

Advisors

This endpoint will give you a list of all advisors with corresponding data about when they signed up and for how long they were/are active - filtered by optionally passed parameters. All requests to this endpoint must pass appropriate headers as specified by the requests section.


Request Body:

GET /advisors

/advisors
Parameter Description Notes
page Integer A number to indicate which page of advisors you're requesting. (Starts from 0.)
count Integer The number of advisors to return per page. (Default: 100)
order String The desired ordering of the results. Acceptable values are:
  • new_signups
  • new_signins
  • new_updates
  • old_signups
  • old_signins
  • old_updates
The default ordering is new_signups
signupDateStart String An ISO 8601 datetime string – or one of the listed keywords – after or during which, to filter users based on their signup date. Acceptable keyword values are:
  • last_week: Filter to events occurring within the last 7 days.
  • last_month: Filter to events occurring since this date and time 1 month ago. If the current day of the month does not exist last month, will use the first day of the current month.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".
signupDateEnd String An ISO 8601 datetime string, after or during which, to filter users based on their signup date.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".
updatedDateStart String An ISO 8601 datetime string – or one of the listed keywords – after or during which, to filter users based on the date their profile was last updated. Acceptable keyword values are:
  • last_week: Filter to events occurring within the last 7 days.
  • last_month: Filter to events occurring since this date and time 1 month ago. If the current day of the month does not exist last month, will use the first day of the current month.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".
updatedDateEnd String An ISO 8601 datetime string, after or during which, to filter users based on the date their profile was last updated.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".
signinDateStart String An ISO 8601 datetime string – or one of the listed keywords – after or during which, to filter users based on the date they last signed in. Acceptable keyword values are:
  • last_week: Filter to events occurring within the last 7 days.
  • last_month: Filter to events occurring since this date and time 1 month ago. If the current day of the month does not exist last month, will use the first day of the current month.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".
signinDateEnd String An ISO 8601 datetime string, after or during which, to filter users based on the date they last signed in.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".

Example Request:


Response Body:

The primary data package is accessed via data.advisors and will contain an array of Advisors objects. Each Advisors object has 10 properties, they are outlined below:

Property Description Notes
advisorid Integer The platform's primary internal identifier for this advisor
advisorExternalid NULL or String If it exists, your organization's identifier for this advisor
firstName String This advisor's first name.
lastName String This advisor's last name.
signupDate String in ISO 8601 format When this advisor first became active on the platform.
lastSigninDate NULL or String in ISO 8601 format When this advisor last signed in to the platform
lastUpdatedDate NULL or String in ISO 8601 format When this advisor last made a change to their profile.
signoffDate NULL or String in ISO 8601 format If not null, indicates the date this advisor became inactive on the platform.
blacklistedDate NULL or String in ISO 8601 format If not null, indicates the date this advisor was removed from the platform.
NOTE: This differs from signoffDate in that it's generally considered a permanent removal whereas someone that has signed off from receiving consultations might one day return.
detailsURI String The URI (hook) to get this advisor's complete profile information

Example Response:

For more about the response payload surrounding the primary data package, read the responses section.

Advisees

This endpoint will give you a list of all advisees with corresponding data about when they signed up and for how long they were/are active - filtered by optionally passed parameters. All requests to this endpoint must pass appropriate headers as specified by the requests section.


Request Body:

GET /advisees

/advisees
Parameter Description Notes
page Integer A number to indicate which page of advisees you're requesting. (Starts from 0.)
count Integer The number of advisees to return per page. (Default: 100)
order String The desired ordering of the results. Acceptable values are:
  • new_signups
  • new_signins
  • new_updates
  • old_signups
  • old_signins
  • old_updates
The default ordering is new_signups
signupDateStart String An ISO 8601 datetime string – or one of the listed keywords – after or during which, to filter users based on their signup date. Acceptable keyword values are:
  • last_week: Filter to events occurring within the last 7 days.
  • last_month: Filter to events occurring since this date and time 1 month ago. If the current day of the month does not exist last month, will use the first day of the current month.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".
signupDateEnd String An ISO 8601 datetime string, after or during which, to filter users based on their signup date.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".
updatedDateStart String An ISO 8601 datetime string – or one of the listed keywords – after or during which, to filter users based on the date their profile was last updated. Acceptable keyword values are:
  • last_week: Filter to events occurring within the last 7 days.
  • last_month: Filter to events occurring since this date and time 1 month ago. If the current day of the month does not exist last month, will use the first day of the current month.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".
updatedDateEnd String An ISO 8601 datetime string, after or during which, to filter users based on the date their profile was last updated.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".
signinDateStart String An ISO 8601 datetime string – or one of the listed keywords – after or during which, to filter users based on the date they last signed in. Acceptable keyword values are:
  • last_week: Filter to events occurring within the last 7 days.
  • last_month: Filter to events occurring since this date and time 1 month ago. If the current day of the month does not exist last month, will use the first day of the current month.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".
signinDateEnd String An ISO 8601 datetime string, after or during which, to filter users based on the date they last signed in.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".

Example Request:


Response Body:

The primary data package is accessed via data.advisees and will contain an array of Advisees objects. Each Advisees object has 8 properties, they are outlined below:

Property Description Notes
adviseeid Integer The platform's primary internal identifier for this User (advisee).
adviseeExternalid NULL or String If it exists, your organization's identifier for this User (advisee).
firstName String This User (advisee)'s first name.
lastName String This User (advisee)'s last name.
signupDate String in ISO 8601 format When this User (advisee) first became active on the platform.
lastSigninDate NULL or String in ISO 8601 format When this User (advisee) last signed in to the platform.
lastUpdatedDate NULL or String in ISO 8601 format When this User (advisee) last updated their profile.
hasAccess Boolean Will return either 1 or 0, indicates that this User (advisee) has access or was removed from the platform, respectively.

Example Response:

For more about the response payload surrounding the primary data package, read the responses section.

AdvisorDetails

This endpoint will give you a complete advisor profile including work experience, educational information, and affinity groups given a single advisorid. - filtered by optionally passed parameters. All requests to this endpoint must pass appropriate headers as specified by the requests section.


Request Body:

GET /advisors/[advisorid]/details

/advisors/[advisorid]/details
Parameter Description Notes
advisorid Integer The platform's primary internal identifier for this advisor.
NOTE: This information is sent in the URI itself.

Example Request:


Response Body:

The primary data package is accessed via data.details and will contain an array of AdvisorDetails objects. Each AdvisorDetails object has 6 properties, they are outlined below:

Property Description Notes
advisorid Integer The platform's primary internal identifier for this advisor.
firstName String This advisor's first name.
lastName String This advisor's last name.
employment NULL or Object A list of employment objects associated with this advisor.
advisorid Integer The platform's primary internal identifier for this advisor.
company String The company of employment.
logo NULL or String A url to this company's logo.
title String The title held at the company.
industry String The industry the company operates in.
function String The function performed by the advisor.
location NULL or String Where the advisor worked.
description NULL or String A detailed description, if available, of the advisor's role.
startDate String in ISO 8601 format When the employment began.
endDate NULL or String in ISO 8601 format When the employment ended. If NULL, it indicates the employment is current.
isLinkedInData Boolean A flag indicating if this employment information was loaded from LinkedIn.
education NULL or Object A list of education objects associated with this advisor.
advisorid Integer The platform's primary internal identifier for this advisor.
school String The school the advisor attended.
logo NULL or String A url to this school's logo.
degree String The degree earned
concentration String The field of study of the degree.
graduationYear Integer The year the advisor graduated.
isLinkedInData Boolean A flag indicating if this education information was loaded from LinkedIn.
affinityGroup NULL or Object A list of affinity group objects associated with this advisor.
id Integer The platform's primary internal identifier for this group.
categoryid Integer The unique identifier for the category this group falls into.
category String The human-readable name of the category this group falls into.
label String The human-readable name of this group.
isRestricted Boolean Whether this group requires administrator approval before membership is active.

Example Response:

For more about the response payload surrounding the primary data package, read the responses section.

AdvisorDetailsBulk

This endpoint will give you an array of complete advisor profiles including work experience, educational information, and affinity groups when passed a comma-separated list of advisorids as a query parameter. - filtered by optionally passed parameters. All requests to this endpoint must pass appropriate headers as specified by the requests section.


Request Body:

GET /advisors/details

/advisors/details
Parameter Description Notes
id Integer A comma-separated list of unique IDs, representing the primary internal identifier for this advisor.

Example Request:


Response Body:

The primary data package is accessed via data.details and will contain an array of AdvisorDetailsBulk objects. Each AdvisorDetailsBulk object has 6 properties, they are outlined below:

Property Description Notes
advisorid Integer The platform's primary internal identifier for this advisor.
firstName String This advisor's first name.
lastName String This advisor's last name.
employment NULL or Object A list of employment objects associated with this advisor.
advisorid Integer The platform's primary internal identifier for this advisor.
company String The company of employment.
logo NULL or String A url to this company's logo.
title String The title held at the company.
industry String The industry the company operates in.
function String The function performed by the advisor.
location NULL or String Where the advisor worked.
description NULL or String A detailed description, if available, of the advisor's role.
startDate String in ISO 8601 format When the employment began.
endDate NULL or String in ISO 8601 format When the employment ended. If NULL, it indicates the employment is current.
isLinkedInData Boolean A flag indicating if this employment information was loaded from LinkedIn.
education NULL or Object A list of education objects associated with this advisor.
advisorid Integer The platform's primary internal identifier for this advisor.
school String The school the advisor attended.
logo NULL or String A url to this school's logo.
degree String The degree earned
concentration String The field of study of the degree.
graduationYear Integer The year the advisor graduated.
isLinkedInData Boolean A flag indicating if this education information was loaded from LinkedIn.
affinityGroup NULL or Object A list of affinity group objects associated with this advisor.
id Integer The platform's primary internal identifier for this group.
categoryid Integer The unique identifier for the category this group falls into.
category String The human-readable name of the category this group falls into.
label String The human-readable name of this group.
isRestricted Boolean Whether this group requires administrator approval before membership is active.

Example Response:

For more about the response payload surrounding the primary data package, read the responses section.

UpdateAdvisorProfile

This endpoint will allow you to update this advisor's external id - filtered by optionally passed parameters. All requests to this endpoint must pass appropriate headers as specified by the requests section.


Request Body:

PUT /advisors/[advisorid]/update

/advisors/[advisorid]/update
Parameter Description Notes
advisorid Integer The platform's primary internal identifier for this advisor.
NOTE: This information is sent in the URI itself.
externalid String The new external id you would like to associate with this advisor.

Example Request:


Response Body:

This hook does not have a primary data package to return. The status of whether the action completed successfully can be found in the metadata package sent with every response. For more about this metadata package, as well as more information on the generic response payload, please read the responses section.

Example Response:

UpdateAdviseeProfile

This endpoint will allow you to update this User ("advisee")'s external id - filtered by optionally passed parameters. All requests to this endpoint must pass appropriate headers as specified by the requests section.


Request Body:

PUT /advisees/[adviseeid]/update

/advisees/[adviseeid]/update
Parameter Description Notes
adviseeid Integer The platform's primary internal identifier for this User ("advisee").
NOTE: This information is sent in the URI itself.
externalid String The new external id you would like to associate with this User ("advisee").

Example Request:


Response Body:

This hook does not have a primary data package to return. The status of whether the action completed successfully can be found in the metadata package sent with every response. For more about this metadata package, as well as more information on the generic response payload, please read the responses section.

Example Response:

Consultations

This endpoint will give you a list of all completed consultations - filtered by optionally passed parameters. All requests to this endpoint must pass appropriate headers as specified by the requests section.


Request Body:

GET /consultations

/consultations
Parameter Description Notes
start String The start of a date range to filter by. Example: 16.06.2024T04:06:04+0000.
end String The end of a date range to filter by. Example: 16.06.2024T04:06:04+0000.
advisorid Integer The platform's internal advisor identification number. When included, the result set will be limited to consultations mentored by the associated advisor.
adviseeid Integer The platform's internal User identification number. When included, the result set will be limited to consultations mentored by the associated User.
advisorExternalid String Your organization's advisor identification number. When included, the result set will be limited to consultations mentored by the associated advisor.
adviseeExternalid String Your organization's User identification number. When included, the result set will be limited to consultations mentored by the associated User.
consultationType String If present, the result set will be limited consultations of the specified type. Acceptable values are:
  • Career Conversation
  • Resume Critique
  • Mock Interview

Example Request:


Response Body:

The primary data package is accessed via data.consultations and will contain an array of Consultations objects. Each Consultations object has 7 properties, they are outlined below:

Property Description Notes
meetingid Integer The primary identifier for this completed consultation (meeting)
meetingTime String Representing the date this consultation took place.
advisorid Integer The internal platform ID associated with the advisor that mentored for this consultation.
adviseeid Integer The internal platform ID associated with the User that requested this consultation.
advisorExternalid String Your organization's advisor identifier for the advisor that mentored for this consultation.
adviseeExternalid Integer Your organization's User identifier for the User that mentored for this consultation.
consultationType String Indicates the type of consultation that occurred.

Example Response:

For more about the response payload surrounding the primary data package, read the responses section.

Webinars

This endpoint will give you a list of all accessible webinars - filtered by optionally passed parameters. All requests to this endpoint must pass appropriate headers as specified by the requests section.


Request Body:

GET /webinars

/webinars
Parameter Description Notes
creationDateStart String The start of a webinar creation date range to filter by.
creationDateEnd String The end of a webinar creation date range to filter by.

Example Request:


Response Body:

The primary data package is accessed via data.webinars and will contain an array of Webinars objects. Each Webinars object has 10 properties, they are outlined below:

Property Description Notes
webinarid Integer The primary identifier for this webinar.
url String The permanent link to this webinar.
title String The title of this webinar.
description String The longer form text description of this webinar.
creationDate String An ISO 8601 datetime string – or one of the listed keywords – after or during which, to filter users based on the date this webinar occurred or was posted. Acceptable keyword values are:
  • last_week: Filter to events occurring within the last 7 days.
  • last_month: Filter to events occurring since this date and time 1 month ago. If the current day of the month does not exist last month, will use the first day of the current month.
Example ISO 8601 string: "2017-10-18T00:11:44+0000" for "October 18, 2017 at 12:11:44 AM, UTC".
consultationType String The general area of advice this webinar addresses. E.g. "Job Search", "Career Conversation", "Resume/CV Critique", etc.
jobFunction String The job specialty most serviced by this webinar. E.g. "Health & Medicine", "Product Management", "Information Technology", etc.
presenterName String The display name of the person presenting the webinar, if appropriate.
presenterTitle String A single-line description of the person presenting the webinar, if appropriate.
imageUrl String A static CDN URL representing a "large"-sized version of the webinar promotional image.

Example Response:

For more about the response payload surrounding the primary data package, read the responses section.