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
- A valid Firsthand API Key
- 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:
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:
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:
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:
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:
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:
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:
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:
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:
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. | |||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||
education | NULL or Object | A list of education objects associated with this advisor. | |||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||
affinityGroup | NULL or Object | A list of affinity group objects associated with this advisor. | |||||||||||||||||||||||||||||||||
|
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. | |||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||
education | NULL or Object | A list of education objects associated with this advisor. | |||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||
affinityGroup | NULL or Object | A list of affinity group objects associated with this advisor. | |||||||||||||||||||||||||||||||||
|
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: 08.09.2024T12:35:38+0000. |
end | String | The end of a date range to filter by. Example: 08.09.2024T12:35:38+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:
|
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:
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.