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.

Ensure API access is set up for your Tenant​

All new tenants are automatically enabled for use with our API

However if you receive the following error when performing an api request

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

Email support@orgvue.com to enable your tenant

Authentication​

Orgvue uses OAuth 2.0 as the primary method for authenticating API requests:

Existing legacy API tokens may still be used currently but should be migrated to OAuth 2.0 as soon as possible

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:

ServerTenant Listing URL
EU Westhttps://orgvue.eu-west-1.concentra.io/tenants/tenants
US Easthttps://orgvue.us-east-1.concentra.io/tenants/tenants
AP SouthEasthttps://orgvue.ap-southeast-2.concentra.io/tenants/tenants
EU West - Staginghttps://orgvue-staging.eu-west-1.concentra.io/tenants/tenants
US East - Staginghttps://orgvue-staging.us-east-1.concentra.io/tenants/tenants
AP SouthEast - Staginghttps://orgvue-staging.ap-southeast-2.concentra.io/tenants/tenants
  • on the tenant listing page for your server environment listed in the above table, or
  • in the of your browser

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​

  1. Navigate to the Settings app for your tenant
  2. Click the name of the dataset you wish to work with to open its metadata.
  3. The datasetIdcan 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 .

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