Skip to main content

Setting Up your API connection

You'll need to have a few things in place to be able to use the API.

Request API access is set up for your Tenant​

Before you can access your Tenant via our API it must be enabled for use

To request API access for your tenant email support@orgvue.com

If you try to access Orgvue via the API without your Tenant being enabled you will receive the following error

{
  "errors": [
    {
      "name": "TenantUsagePlanNotConfigured",
      "code": "40345",
      "message": "The API Usage Plan for this tenant is not configured. Please contact support to resolve this issue."
    }
  ]
}

Enable token access for your Orgvue account​

We use tokens to control authentication and access to the API. These are unique credentials assigned to individual users. You can enable token access for your Orgvue account by following these steps:

  1. Head to the .

  2. Navigate to the Users List:

  3. Select your user account and click on the Edit button.

  4. Make sure TokenAccess is enabled for your account:

  5. Remember to save your changes.

TokenAccess is a standard property for the Users List in all new Tenants, but may need to be added by an admin for existing Tenants. Note that the TokenAccess key is case-sensitive, so must be created as shown.

Produce a token for your network address​

To create an API token:

Token Management Image

  1. Go to the .
  2. Provide the start and end dates for your new token.
  3. Set the Subnets field, which controls the range of IP addresses from which the generated token can be used, to your current IP address to restrict use of the token to your current network location. Dynamic IP ranges may be entered as a comma separated list of Classless Inter Domain Routing(CIDR) ranges
  4. Your current IP address will be displayed for information
  5. Create your token, and make sure to copy it as you will not be able to view it again.
info

IP access restrictions​

When accessing data stored in Orgvue, your account, tenant or token may be subject to restrictions around the originating source IP address.

If your attempt to access data is forbidden by an IP restriction access policy, you will receive an error message:

Making requests​

All requests in Orgvue API must be made using the https protocol (http requests are not supported by Orgvue).

Authorization​

Orgvue expects the API token to be included in all requests to the server, encoded within “Authorization” header:

Authorization: Bearer apiToken

Query Parameters​

In the event you need to pass a query parameter multiple times when it is documented as such, the Orgvue API does not support list values.

The correct way is to specify the following: ?idKey=firstName&idKey=lastName&idKey=DOB (not ?idKey=firstName, lastName, DOB).

Understanding the path parameter specification​

When describing our endpoints, we use the {curlyBraces} notation to denote path parameters.

For example, given the endpoint /api/v1/{tenantId}/datasets/{datasetId}/export/jsonRows, we will refer to {tenantId} and {datasetId} as the tenantId and datasetId path parameters.

info

The braces themselves should not be included.

For example, if your tenantId is MY_TENANT and your datasetId is 123E4567-E89B-12D3-A456-426614174000, then your API call should be to: /api/v1/MY_TENANT/datasets/123E4567-E89B-12D3-A456-426614174000/export/jsonRows.

Determine your base url​

The base URL for your server should be the same server you used to create your token. Confirm the base url for your intended server using the table below:

ServerBase Url
EU Westhttps://orgvue.eu-west-1.concentra.io
US Easthttps://orgvue.us-east-1.concentra.io
AP SouthEasthttps://orgvue.ap-southeast-2.concentra.io
EU West - Staginghttps://orgvue-staging.eu-west-1.concentra.io
US East - Staginghttps://orgvue-staging.us-east-1.concentra.io
AP SouthEast - Staginghttps://orgvue-staging.ap-southeast-2.concentra.io

Select a tenant for tenantId​

Check the ID of the tenant you want to work with either:

As an example, if your tenant ID is MY_TENANT, a request should look something like this: /api/v1/MY_TENANT/datasets/{datasetId}/export/jsonRows

Select a dataset for datasetId​

Navigate to the . Click the name of the dataset you wish to work with to open its metadata. The datasetId can be found at the bottom of the page, under the heading "Dataset ID". Make a note of this value.

For more information, please read our user guide.

As an example, if your datasetId is 123E4567-E89B-12D3-A456-426614174000 then your request URL should look something like this: /api/v1/{tenantId}/datasets/123E4567-E89B-12D3-A456-426614174000/export/jsonRows

A full list of all datasets present in your tenant along with each datasets Id can be obtained via the List Dataset Endpoint