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:

Server	Orgvue Settings Url
EU West	https://orgvue.eu-west-1.concentra.io/app/configui
US East	https://orgvue.us-east-1.concentra.io/app/configui
AP SouthEast	https://orgvue.ap-southeast-2.concentra.io/app/configui
EU West - Staging	https://orgvue-staging.eu-west-1.concentra.io/app/configui
US East - Staging	https://orgvue-staging.us-east-1.concentra.io/app/configui
AP SouthEast - Staging	https://orgvue-staging.ap-southeast-2.concentra.io/app/configui

1. Head to the Orgvue settings app for your server environment listed in the above table

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:

Server	Tokens Management Url
EU West	https://orgvue.eu-west-1.concentra.io/tokens
US East	https://orgvue.us-east-1.concentra.io/tokens
AP SouthEast	https://orgvue.ap-southeast-2.concentra.io/tokens
EU West - Staging	https://orgvue-staging.eu-west-1.concentra.io/tokens
US East - Staging	https://orgvue-staging.us-east-1.concentra.io/tokens
AP SouthEast - Staging	https://orgvue-staging.ap-southeast-2.concentra.io/tokens

1. Go to the token management page for your server environment listed in the above table
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:

Server	Base Url
EU West	https://orgvue.eu-west-1.concentra.io
US East	https://orgvue.us-east-1.concentra.io
AP SouthEast	https://orgvue.ap-southeast-2.concentra.io
EU West - Staging	https://orgvue-staging.eu-west-1.concentra.io
US East - Staging	https://orgvue-staging.us-east-1.concentra.io
AP SouthEast - Staging	https://orgvue-staging.ap-southeast-2.concentra.io

Select a tenant for tenantId

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

Server	Tenant Listing URL
EU West	https://orgvue.eu-west-1.concentra.io/tenants/tenants
US East	https://orgvue.us-east-1.concentra.io/tenants/tenants
AP SouthEast	https://orgvue.ap-southeast-2.concentra.io/tenants/tenants
EU West - Staging	https://orgvue-staging.eu-west-1.concentra.io/tenants/tenants
US East - Staging	https://orgvue-staging.us-east-1.concentra.io/tenants/tenants
AP SouthEast - Staging	https://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