Introduction

The Catchlight API provides read/write access to interact with core features of the platform, enabling you to build custom integrations with your preferred applications. The API is exclusively available to Catchlight customers and integration partners.

You can integrate using your preferred programming language and HTTP client. All Catchlight APIs are built using REST conventions, and all requests and responses are made using standard JSON.

If you have any questions, please contact support@catchlight.ai.

Authentication

Every request to the Catchlight API needs to be identified and authorized. Requests are scoped to financial advisory firms rather than individual users.

Catchlight uses OAuth 2.0 for authentication protocol. When authenticating against the Catchlight API, your organization will identify itself using a client ID and secret. The client ID is a public value. The secret, however, should be stored securely and should be known only to your organization.

After your organization has identified itself using a client ID and secret, we will issue an access and a refresh token. The access token should be included in the HTTP header when making requests to the Catchlight API. The access token will expire after 1 hour. When an access token expires, your organization can either retrieve a new one using the refresh token or reauthenticate.

  1. Request a Client ID/Secret

    Client ID/secret pairs are generated by the Catchlight team and are sent out via email. For your client ID/secret, please reach out to support@catchlight.ai.

  2. Acquire an Access Token 

    # $client_id = ID obtained from step 1
# $client_secret = secret obtained from step 1
curl -X POST 'https://api-custqa.fidelity.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
-H 'Content-Type: application/x-www-form-urlencoded' -d 'client_id=$client_id' -d 'client_secret=$client_secret'

    Note that the domain for the access token is dependent on which environment you're planning on making requests against. The domains are:

    • Customer QA - api-custqa.fidelity.com
    • Production - api-live.fidelity.com

    Client IDs and secrets are also tied to environments.

    The returned JSON will have the following shape: 

    {
  'refresh_token_expires_in' : '0',
  'token_type' : 'BearerToken',
  'issued_at' : {Unix timestamp with millisecond precision}, \\ e.g. 1675459427505
  'client_id' : {the client ID used to create the token},
  'access_token' : {base64 string}, \\ e.g. D8lwPNnG6ApvsCJkniXRdvMRcq1Y
  'expires_in' : '3599',
  'refresh_count' : '0',
  'status' : 'approved'
}

  3. Use the Access Token from the Response for all Subsequent Requests

    Requests should be made using the 'Authorization Bearer' strategy: 

    curl -H 'Authorization: Bearer $access_token' https://api-custqa.catchlight.ai/v1/users

  4. Refreshing a Token

    The access tokens will last for 60 minutes. Once it expires, we recommend you fetch a new token using the steps defined above.

Versioning

The current API version is 2.0.0. This major version (“v2”) is included in all request URL’s.

Please Note: The information provided is representative of functionality that may be made available. Availability and functionality within each API may differ and is dependent on various factors including Client or third-party eligibility, completion of necessary operational requirements, Client or third-party authorizations, etc. Availability, content and functionality may change at any time, without notice.

APIs are provided “as is” and “as available”. Use of APIs is at user's sole risk. Catchlight, its affiliates and third-party suppliers expressly disclaim all warranties of any kind, whether express or implied, as to the APIs, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose and noninfringement. Catchlight, its affiliates and third-party suppliers make no warranty to user that (i) the APIs will meet user's requirements, (ii) the APIs will be uninterrupted, timely, secure or error-free, (iii) the APIs will be accurate, complete or reliable, or (iv) any errors in the APIs will be corrected.

Technical Details