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.