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:

GET /consultations HTTP/1.1
Host: api.firsthand.co
Firsthand-Api: 11111111-2222-3333-4444-555555555555

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:

PUT /advisees/123456/update HTTP/1.1
Host: api.firsthand.dev
Firsthand-Api: 11111111-2222-3333-4444-555555555555
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

externalid=98765

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.

{
    "status": 200,              // The HTTP status code returned by the server
    "success": "success",       // A message indicating the request was processed
    "data": {                   // "data" will wrap the primary data package and metadata

        ...                     // The primary data package (consult individual endpoint documentation for specifics)

        "metadata": {           // An object with information relevant for logging purposes
            "clientid": ---,    // Your client id
            "uri": ---,         // Your request URI (endpoint + query parameters)
            "received": ---,    // The date our server received your request (a string in ISO 8601 format)
            "processed": ---    // The date our server finished processing your request (a string in ISO 8601 format)
        }
    }
}

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.

{
    "status": 403,              // The HTTP status code returned by the server
    "error": "Forbidden",       // A message indicating why the request failed
}

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.

{
    "status": 404,              // The HTTP status code returned by the server
    "error": "Not Found",       // A message indicating why the request failed
}

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.

{
    "status": 500,              // The HTTP status code returned by the server
    "error": "error",           // A message indicating why the request failed
}

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:

GET /advisors?count=50 HTTP/1.1
Host: api.firsthand.co
Firsthand-Api: 11111111-2222-3333-4444-555555555555

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:

{
    "status": 200,
    "success": "success",
    "data": {
        "metadata": {
            "clientid": "YOUR-CLIENT-ID",
            "uri": "\/advisors?count=50",
            "received": "2017-06-20T22:04:00.120557+0000",
            "processed": "2017-06-20T22:04:00.166388+0000"
        },
        "advisors": [
            {
                "advisorid": 987654321,
                "advisorExternalid": "jdoe1456",
                "firstName": "John",
                "lastName": "Doe",
                "signupDate": "2016-06-25T05:17:55+0000",
                "lastSigninDate": "2017-06-10T07:25:32+0000",
                "lastUpdatedDate": "2017-04-25T12:54:18+0000",
                "signoffDate": null,
                "blacklistedDate": null,
                "detailsURI": "\/advisors\/987654321\/details"
            },
            {
                "advisorid": 1234567890,
                "advisorExternalid": null,
                "firstName": "Jane",
                "lastName": "Deer",
                "signupDate": "2016-03-12T15:44:41+0000",
                "lastSigninDate": "2017-06-20T21:12:44+0000",
                "lastUpdatedDate": "2017-02-03T12:48:23+0000",
                "signoffDate": "2017-02-03T12:48:23+0000",
                "blacklistedDate": null,
                "detailsURI": "\/advisors\/1234567890\/details"
            }
        ]
    }
}

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:

GET /advisees?count=50 HTTP/1.1
Host: api.firsthand.co
Firsthand-Api: 11111111-2222-3333-4444-555555555555

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:

{
    "status": 200,
    "success": "success",
    "data": {
        "metadata": {
            "clientid": "YOUR-CLIENT-ID",
            "uri": "\/advisees?count=50",
            "received": "2017-06-20T22:04:00.120557+0000",
            "processed": "2017-06-20T22:04:00.166388+0000"
        },
        "advisees": [
            {
                "adviseeid": 987654321,
                "adviseeExternalid": "jdoe1456",
                "firstName": "John",
                "lastName": "Doe",
                "signupDate": "2016-06-25T05:17:55+0000",
                "lastSigninDate": "2017-06-10T07:25:32+0000",
                "lastUpdatedDate": "2017-06-10T12:58:52+0000",
                "hasAccess": true
            },
            {
                "adviseeid": 1234567890,
                "adviseeExternalid": null,
                "firstName": "Jane",
                "lastName": "Deer",
                "signupDate": "2016-03-12T15:44:41+0000",
                "lastSigninDate": "2017-06-20T21:12:44+0000",
                "lastUpdatedDate": "2017-06-20T21:13:20+0000",
                "hasAccess": false
            }
        ]
    }
}

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:

GET /advisors/123456/details HTTP/1.1
Host: api.firsthand.co
Firsthand-Api: 11111111-2222-3333-4444-555555555555

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:

{
    "status": 200,
    "success": "success",
    "data": {
        "metadata": {
            "clientid": "YOUR-CLIENT-ID",
            "uri": "advisor\/123456\/details",
            "received": "2017-06-20T22:04:00.120557+0000",
            "processed": "2017-06-20T22:04:00.166388+0000"
        },
        "details": {
            "advisorid": 123456,
            "firstName": "Fredrik",
            "lastName": "Maro",
            "education": [
                {
                    "advisorid": 123456,
                    "school": "MadeUpSchool University",
                    "degree": "Bachelor's of Science",
                    "concentration": "Computer Science",
                    "graduationYear": 2011,
                    "logo": null,
                    "hasLogo": null,
                    "isLinkedInData": null
                }
            ],
            "employment": [
                {
                    "advisorid": 123456,
                    "company": "Some Company Name LLC.",
                    "title": "Software Engineer",
                    "industry": "Entertainment",
                    "function": "Information Technology",
                    "location": "Chicago, IL. USA",
                    "description": null,
                    "startDate": "2012-06-01T00:00:00+0000",
                    "endDate": "2016-11-02T15:00:00+0000",
                    "logo": null,
                    "hasLogo": null,
                    "isLinkedInData": null
                },
                {
                    "advisorid": 123456,
                    "company": "Another Company Inc.",
                    "title": "Project Manager",
                    "industry": "Human Resources",
                    "function": "Information Technology",
                    "location": "New York, NY. USA",
                    "description": null,
                    "startDate": "2017-01-01T00:00:00+0000",
                    "endDate": null,
                    "logo": null,
                    "hasLogo": null,
                    "isLinkedInData": null
                }
            ],
            "affinityGroup": [
                {
                    "id": 200605,
                    "categoryid": 4,
                    "category": "Greek Organizations",
                    "label": "Delta Phi",
                    "isRestricted": true
                }
            ]
        }
    }
}

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:

GET /advisors/details?id=168,481023,291 HTTP/1.1
Host: api.firsthand.co
Firsthand-Api: 11111111-2222-3333-4444-555555555555

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:

{
    "status": 200,
    "success": "success",
    "data": {
        "metadata": {
            "clientid": "YOUR-CLIENT-ID",
            "uri": "advisor\/123456\/details",
            "received": "2017-06-20T22:04:00.120557+0000",
            "processed": "2017-06-20T22:04:00.166388+0000"
        },
        "details": {
            "advisorid": 123456,
            "firstName": "Fredrik",
            "lastName": "Maro",
            "education": [
                {
                    "advisorid": 123456,
                    "school": "MadeUpSchool University",
                    "degree": "Bachelor's of Science",
                    "concentration": "Computer Science",
                    "graduationYear": 2011,
                    "logo": null,
                    "hasLogo": null,
                    "isLinkedInData": null
                }
            ],
            "employment": [
                {
                    "advisorid": 123456,
                    "company": "Some Company Name LLC.",
                    "title": "Software Engineer",
                    "industry": "Entertainment",
                    "function": "Information Technology",
                    "location": "Chicago, IL. USA",
                    "description": null,
                    "startDate": "2012-06-01T00:00:00+0000",
                    "endDate": "2016-11-02T15:00:00+0000",
                    "logo": null,
                    "hasLogo": null,
                    "isLinkedInData": null
                },
                {
                    "advisorid": 123456,
                    "company": "Another Company Inc.",
                    "title": "Project Manager",
                    "industry": "Human Resources",
                    "function": "Information Technology",
                    "location": "New York, NY. USA",
                    "description": null,
                    "startDate": "2017-01-01T00:00:00+0000",
                    "endDate": null,
                    "logo": null,
                    "hasLogo": null,
                    "isLinkedInData": null
                }
            ],
            "affinityGroup": [
                {
                    "id": 200605,
                    "categoryid": 4,
                    "category": "Greek Organizations",
                    "label": "Delta Phi",
                    "isRestricted": true
                }
            ]
        }
    }
}

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:

PUT /advisors/123456/update HTTP/1.1
Host: api.firsthand.co
Firsthand-Api: 11111111-2222-3333-4444-555555555555
Content-type: application/x-www-form-urlencoded
Content-length: 29

externalid=NEW-EXTERNAL-ID123

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:

{
    "status": 200,
    "success": "success",
    "data": {
        "metadata": {
            "clientid": "YOUR-CLIENT-ID",
            "uri": "advisors\/[advisorid]\/update",
            "received": "2017-06-20T22:04:00.120557+0000",
            "processed": "2017-06-20T22:04:00.166388+0000"
        }
    }
}

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:

PUT /advisees/123456/update HTTP/1.1
Host: api.firsthand.co
Firsthand-Api: 11111111-2222-3333-4444-555555555555
Content-type: application/x-www-form-urlencoded
Content-length: 29

externalid=NEW-EXTERNAL-ID123

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:

{
    "status": 200,
    "success": "success",
    "data": {
        "metadata": {
            "clientid": "YOUR-CLIENT-ID",
            "uri": "advisees\/[adviseeid]\/update",
            "received": "2017-06-20T22:04:00.120557+0000",
            "processed": "2017-06-20T22:04:00.166388+0000"
        }
    }
}

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: 27.07.2024T02:23:47+0000.
end	String	The end of a date range to filter by. Example: 27.07.2024T02:23:47+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:

GET /consultations?adviseeid=123456789&advisorid=987654321 HTTP/1.1
Host: api.firsthand.co
Firsthand-Api: 11111111-2222-3333-4444-555555555555

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:

{
    "status": 200,
    "success": "success",
    "data": {
        "metadata": {
            "clientid": "YOUR-CLIENT-ID",
            "uri": "\/consultations?adviseeid=123456789&advisorid=987654321",
            "received": "2017-06-20T22:04:00.120557+0000",
            "processed": "2017-06-20T22:04:00.166388+0000"
        },
        "consultations": [
            {
                "meetingid": 12345,
                "meetingTime": "2016-11-02T15:00:00+0000",
                "advisorid": 987654321,
                "advisorExternalid": "abc123",
                "adviseeExternalid": "8712",
                "adviseeid": 123456789,
                "consultationType": "Resume Critique"
            },
            {
                "meetingid": 12345,
                "meetingTime": "2016-11-02T15:00:00+0000",
                "advisorid": 987654321,
                "advisorExternalid": "abc123",
                "adviseeExternalid": "8712",
                "adviseeid": 123456789,
                "consultationType": "Resume Critique"
            }
        ]
    }
}

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:

GET /webinars?creationDateStart=last_week HTTP/1.1
Host: api.firsthand.co
Firsthand-Api: 11111111-2222-3333-4444-555555555555

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:

{
    "status": 200,
    "success": "success",
    "data": {
        "metadata": {
            "clientid": "YOUR-CLIENT-ID",
            "uri": "\/webinars",
            "received": "2017-06-20T22:04:00.120557+0000",
            "processed": "2017-06-20T22:04:00.166388+0000"
        },
        "webinars": [
            {
                "webinarid": 950,
                "url": "https:\/\/vault.com\/webinars\/950",
                "title": "Venture Capital for Ex-Convicts",
                "description": "You can make a killing in startups.",
                "creationDate": "2018-05-12T17:00:00+0000",
                "consultationType": "Career Conversation",
                "jobFunction": "Entrepreneurship",
                "presenterName": "Charles",
                "presenterTitle": "Director of Manson Family",
                "imageUrl": "https:\/\/d2xws5ah91xfd9.cloudfront.net\/content\/webinars\/touts\/950\/l.jpg"
            },
            {
                "webinarid": 829,
                "url": "https:\/\/vault.com\/webinars\/829",
                "title": "Baking: How to get your resume noticed",
                "description": "In this webinar, chef Betty Crocker explains why it may serve you better to break out the cake BEFORE you get the offer.",
                "creationDate": "2017-10-13T17:00:00+0000",
                "consultationType": "Job Search",
                "jobFunction": "General",
                "presenterName": "Betty",
                "presenterTitle": "Head Chef at General Mills",
                "imageUrl": "https:\/\/d2xws5ah91xfd9.cloudfront.net\/content\/webinars\/touts\/829\/l.jpg"
            }
        ]
    }
}

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

API Documentation

Overview

Version 1.2 Last updated November 11, 2017

Requests

1. A valid Firsthand API Key

2. An endpoint

Sending data in the HTTP body

Responses

Successful Response

Failed Response - Forbidden

Failed Response - Not Found

Failed Response - Internal Server Error

Advisors

Request Body:

GET /advisors

/advisors

Response Body:

Advisees

Request Body:

GET /advisees

/advisees

Response Body:

AdvisorDetails

Request Body:

GET /advisors/[advisorid]/details

/advisors/[advisorid]/details

Response Body:

AdvisorDetailsBulk

Request Body:

GET /advisors/details

/advisors/details

Response Body:

UpdateAdvisorProfile

Request Body:

PUT /advisors/[advisorid]/update

/advisors/[advisorid]/update

Response Body:

UpdateAdviseeProfile

Request Body:

PUT /advisees/[adviseeid]/update

/advisees/[adviseeid]/update

Response Body:

Consultations

Request Body:

GET /consultations

/consultations

Response Body:

Webinars

Request Body:

GET /webinars

/webinars

Response Body:

Version 1.2
Last updated November 11, 2017