Getting started

Overview

myEQUITY Connect APIs utilize a RESTful architecture and have standardized request and response objects for ease of use.  All requests and responses are required to be sent and will be returned in JSON. An HTTP status code will indicate the success of the call, as detailed below. Any request that is unsuccessful will have detailed information to explain why the call failed, and if applicable, will include which fields or parameters are invalid. Successful responses for POST & PUT calls will include Activity IDs and further relevant information for tracking.

Being enrolled within the myEQUITY Connect Developer Portal allows you access to review the API documentation. To test these APIs, you will need to speak to an Equity representative to be provided your subscription details.

Sandbox and Production base URLs

A sandbox environment will be provided for testing.

Environment                    URL

Sandbox                             https://stageapi.myequityconnect.com/

Production                         https://api.myequityconnect.com/

 

HTTP Status Codes

Each API offered lists examples of what a success and bad request response object looks like. The examples below gives a brief explanation of what HTTP status codes may be encountered while using this product.

  • 200 OK - Successful response.

  • 400 Bad Request - Some part of the request was invalid. This can include missing or invalid parameters in a GETcall or missing or invalid data in a request object within a POST or PUT call.

  • 401 Unauthorized - A valid bearer token must be included with each call.

  • 404 Not Found - The API route does not exist.

  • 500 Internal Server Error - An error on the server side.

OAuth

While using any APIs within this product, a bearer token must be provided in order to be properly authorized. To get a token, navigate to the OAuth call within the API list and click the "Try It" button, which will open up a sidebar menu. Within the Body box, copy and paste the following line, replacing the brackets with your provided Client ID, Secret, and Resource:

grant_type=client_credentials&client_id=[INSERT ID HERE]&client_secret=[INSERT SECRET HERE]&resource=[INSERT RESOURCE HERE]

Once the "Send" button is clicked, copy the resulting access_token from the Response. This will be used in subsequent calls.

Please note that these tokens do expire after a certain amount of time. If the token becomes invalid, simply use these instructions to acquire a new token.

To make life easier, it's recommended to leave the OAuth call open with a token fetched in a separate tab or window, so copying and pasting into the subsequent calls is straightforward.

Subscription Key

It's important to note that every call made using this product, including the OAuth call, requires the subscription key to be passed in the Headers. For an example within this portal, navigate to the API list and select a call to test. Click the "Try It" button, which brings up a sidebar menu. Under the Headers section is a header with the Name text box of Ocp-Apim-Subscription-Key.

In the Value text box (right side), your subscription key should auto populate. If it does not, you will need to paste your key here.

Standardized Request & Response Objects

All POST & PUT requests are wrapped in a specific request wrapper object in order to standardize the calls. In addition, all API calls are returned in a response wrapper object consisting of an array of the type of responses (unless there was an error on the submission that resulted in anything other than a 200 OK HTTP Response). Each API contains both the schema (for POST & PUTcalls) and samples of the request & response.  The schema will list the data types expected, as well as detailing out allowed Enum values for convenience.

Using the Developer Portal

Once you are subscribed to the myEQUITY Connect product, this site allows you to test the APIs available.  For each call, navigate to the APIs page and click the call you would like to test. You can select which operation you're interested in testing from the menu on the left. From there, click the "Try It" button.

  • POST / PUT Calls

    First, ensure your subscription key has been populated in the headers as detailed above.

    In the Headers section, to add in the token acquired from the OAuth call, find the Name text box (left side) labeled Authorization. In the Value text box (right side), type Bearer, along with a space, and then paste in the token.

    Bearer [ACCESS_TOKEN LETTERS AND NUMBERS HERE]

    NOTE: You do not need to modify anything under the Authorization section of Try It as this is handled via the added Authorization header.

    You may choose to modify the Request object now or leave as is for testing. Click "Send" to test the call.

  • GET Calls

    GETcalls require parameters which will need to be entered for testing. Some parameters are optional. Required and optional parameters will be listed under 'Request Parameters', prior to clicking the "Try It" button. To remove an optional parameter from the call while testing, click the "Remove" link to the right of the parameter text boxes.

    Once the parameters have been entered, check that your subscription key has been added to the headers, and similarly update the Value text box (right side) with the bearer token from the OAuth call as detailed above.

    NOTE: You do not need to modify anything under the Authorization section of Try It as this is handled via the added Authorization header.

    Click "Send" to test the call.

Versioning

Our API calls implement versioning which will be indicated within the description of the individual API endpoint. If a call has multiple versions of a request object, the schemas and examples of both will be within the documentation. To send a version along with the request, use the query parameterapiVersion to set a specific version.  For example, to use version 1 of a request object, sendapiVersion=1. If no version is sent for a call that maintains multiple versions, the latest and most up to date version of the API will be used.

Multipart/form-data Calls

Some APIs offered require the Content-Type to be submitted as multipart/form-data, meaning both a JSON request object and a file attachment must be submitted. These calls must be tested using Postman. Any API that requires this type of submission will be clearly marked. A sample of the request object that can be copied and pasted when testing is included on this site. To submit via Postman, you will need to set up the Bearer Token under Authorization and the Ocp-Apim-Subscription-Key under Headers as detailed above. Under Body, you will need to select form-data and include one line for the request (the text part of the submission), and one or more for the file (the file part of the submission).

Restrictions on multipart calls:

  • Maximum of 5 file attachments

  • File types allowed: pdf, tiff, tif, png, jpg, jpeg

  • File names cannot have spaces

Support

Error response objects contain a property named correlationId.  When submitting support requests, please include this correlationId, as this allows us to track the request.

Maintenance Window

Please note that myEQUITY Connect utilizes a maintenance window from 3am-5am ET, during which the API calls may be unavailable and/or result in failures.  We recommend that submissions during this maintenance window be avoided for possible failures.