Skip to main content
API docs by Redocly

Orgvue API specification

Download OpenAPI specification:Download

Introduction

This page contains the Open API specification of the Orgvue API. It contains all the information needed to configure your integration.

Dataset Operations

Dataset level operations

List datasets

Returns a list of JSON objects representing the datasets that are present in your tenant. Each dataset object contains additional HATEOAS link relations provided to navigate to available next actions.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Responses

Response samples

Content type
application/json; charset=UTF-8
[
  • {
    }
]

Create dataset

Creates a new dataset resource with a set of defined properties. Item data is uploaded via subsequent requests.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
required
name
required
string

The name of the dataset

type
required
string

The type of the dataset. Note type "LINKS" is not available for this endpoint.

autoId
required
string

The property key configured as autoId for this dataset

labelId
required
string

The property key configured as labelId for this dataset

tags
Array of strings

Array of shared tags for the dataset

treeId
string

The default hierarchy key property

treeParentId
string

The default hierarchy parent key property

required
Array of objects

Array of property objects

Responses

Request samples

Content type
application/json; charset=UTF-8
{
  • "name": "Positions",
  • "type": "POSITIONS",
  • "autoId": "position_id",
  • "labelId": "position_title",
  • "tags": [
    ],
  • "treeId": "position_id",
  • "treeParentId": "position_managerid",
  • "properties": [
    ]
}

Response samples

Content type
application/json; charset=UTF-8
{
  • "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2",
  • "cacheKey": "abc5DeFgh3IjK5L76/ABCdeEFGHIJklMNo+pqRstuvwxYZENuHvV863y5BtEhGTuqnP2cLZhys9EQ==",
  • "createdAt": "2022-03-20T17:53:23.282Z",
  • "createdBy": "user@example.com",
  • "modifiedAt": "2022-03-20T17:53:23.282Z",
  • "modifiedBy": "user@example.com",
  • "name": "Positions",
  • "type": "POSITIONS",
  • "autoId": "position_id",
  • "labelId": "position_title",
  • "tags": [
    ],
  • "treeId": "position_id",
  • "treeParentId": "position_managerid",
  • "properties": [
    ]
}

Update dataset

Updates a dataset resource. The configuration in the request payload is merged onto the existing dataset configuration.

The value null may be used for keys that are not required in order to remove them. For example, treeId and treeParentId may be set to null in order to convert a hierarchical dataset into a flat dataset.

Properties are merged based on the key value. If an existing key is matched the property is updated, otherwise a new property is created. If it is necessary to delete properties, the deleteOmittedProperties query parameter must be used. If set to true, any existing properties not matched in the provided payload by key will be removed.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

datasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Dataset unique identifier

query Parameters
deleteOmittedProperties
boolean
Default: false

Only use this parameter if you wish to delete any properties that don't appear in the properties array of your payload. If an array of properties is supplied and this query parameter is set to true, any existing properties that are not matched by key will be deleted. By default no properties are deleted.

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
required
name
string

The name of the dataset

type
string

The type of the dataset. Note type "LINKS" is not available for this endpoint.

autoId
string

The property key configured as autoId for this dataset

labelId
string

The property key configured as labelId for this dataset

tags
Array of strings or null

Array of shared tags for the dataset

treeId
string or null

The default hierarchy key property

treeParentId
string or null

The default hierarchy parent key property

Array of objects (updatePropertiesListItem)

Array of partial property objects.

Responses

Request samples

Content type
application/json; charset=UTF-8
{
  • "name": "Positions",
  • "type": "POSITIONS",
  • "autoId": "position_id",
  • "labelId": "position_title",
  • "tags": [
    ],
  • "treeId": "string",
  • "treeParentId": "string",
  • "properties": [
    ]
}

Response samples

Content type
application/json; charset=UTF-8
{
  • "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2",
  • "cacheKey": "abc5DeFgh3IjK5L76/ABCdeEFGHIJklMNo+pqRstuvwxYZENuHvV863y5BtEhGTuqnP2cLZhys9EQ==",
  • "createdAt": "2022-03-20T17:53:23.282Z",
  • "createdBy": "user@example.com",
  • "modifiedAt": "2022-03-20T17:53:23.282Z",
  • "modifiedBy": "user@example.com",
  • "name": "Positions",
  • "type": "POSITIONS",
  • "autoId": "position_id",
  • "labelId": "position_title",
  • "tags": [
    ],
  • "treeId": "position_id",
  • "treeParentId": "position_managerid",
  • "properties": [
    ]
}

Dataset metadata

Returns a representation of the dataset resource

Drafts

Each dataset object may contain a list of drafts. A draft contains a set of changes that may be applied on top of a dataset. It may be used to model different scenarios without modifying the underlying dataset items themselves. Once satisfied with the changes you may wish to apply them to the dataset to make them permanent changes. We provide additional HATEOAS link relations to navigate to available next actions.

Linking dataset relationships

Each dataset object may contain a list of linking dataset relationships. If a dataset is part of more than one links relationships, the list will contain more than one objects. A source dataset will contain "link", and "target", a linking dataset will contain "source" and "target", while a target dataset will contain "source" and "link". We provide additional HATEOAS link relations to navigate to available next actions.

Linking dataset export

Once you have received the response from this endpoint we have prepared all the data necessary for all possible linking calculations in this tenant. Track the linking relationship you care to calculate and follow the HATEOAS relation under $.linkingRelationships[index]._links.export. Use this content to perform your next request to our export endpoint.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

datasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Dataset unique identifier

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Responses

Response samples

Content type
application/json; charset=UTF-8
{
  • "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2",
  • "cacheKey": "abc5DeFgh3IjK5L76/ABCdeEFGHIJklMNo+pqRstuvwxYZENuHvV863y5BtEhGTuqnP2cLZhys9EQ==",
  • "createdAt": "2022-03-20T17:53:23.282Z",
  • "createdBy": "user@example.com",
  • "modifiedAt": "2022-03-20T17:53:23.282Z",
  • "modifiedBy": "user@example.com",
  • "name": "Positions",
  • "type": "POSITIONS",
  • "autoId": "position_id",
  • "labelId": "position_title",
  • "tags": [
    ],
  • "treeId": "position_id",
  • "treeParentId": "position_managerid",
  • "properties": [
    ],
  • "items": {
    },
  • "drafts": [
    ],
  • "linkingRelationships": [
    ],
  • "_links": {}
}

Async export including calculations

Creates a job in the background and produces a jobTicket resource which in turn contains a URL to poll for the requested job data. Other endpoints will lead you to the correct usage of this endpoint via HATEOAS links.

Calculations

✅ Pre-Filter
✅ Post-Filter
⚙ Linking Calculations (Configurable in Request Body)
⚙ On-Demand (Configurable in Request Body)

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

datasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Dataset unique identifier

exportFormat
string
Enum: "jsonRows" "jsonColumns" "jsonObjects" "csv" "tsv"
Example: jsonRows

The data format to use in the response. If no export format is provided the default jsonRows will be used.

query Parameters
encoding
string
Enum: "gzip" "identity"
Example: encoding=gzip

Determines whether the data written to the result location will be compressed using gzip. Defaults to identity (meaning no compression). This will be deprecated in favour of resultEncoding.

resultEncoding
string
Enum: "gzip" "identity"
Example: resultEncoding=gzip

Determines whether the data written to the result location will be compressed using gzip. Defaults to identity (meaning no compression).

includeBOM
boolean
Default: true

Determines if a Byte Order Mark (BOM) is added to the beginning of the response payload. This query parameter is only implemented for requests with an exportFormat value of CSV or TSV. Defaults to true.

lineEndings
string
Default: "windows"
Enum: "unix" "windows"

Determines the line endings (row separators) for data export. This query parameter is only implemented for requests with an exportFormat value of CSV or TSV. Defaults to windows.

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
optional
object (datasetLinking)

Provide relevant dataset configuration information. A Links datasetId may be supplied in the linkingRelationships to allow calculations to be executed with the context of a specific linked dataset.

object (resultLocation)

Provide this object to divert your result data to a storage location of your choice. It must be a secure resource compatible with the presigned URL mechanism for an object for which you own the lifecycle, which our API can use to upload data via an http "PUT" request.

object

Provide this object to divert your result data to a storage location of your choice. It must be a secure resource compatible with the presigned URL mechanism for an object for which you own the lifecycle, which our API can use to upload data via an http "PUT" request. This will be deprecated in favour of resultLocation.

object (callbackPayload)

The callback mechanism allows you to configure a request to be made by the Orgvue API when processing your asynchronous request is complete. The callback request is sent when the jobTicket is 'completed' or 'failed'.

executeOnDemand
Array of strings non-empty unique

On-demand properties to calculate as part of the export. These will need to be configured ahead of time, and passed to the API in the correct order for your on-demand calculation to be meaningful.

object

Query object to apply filter on exported data

Responses

Request samples

Content type
application/json; charset=UTF-8
{
  • "dataset": {
    },
  • "resultLocation": {},
  • "exportLocation": {},
  • "callback": {},
  • "executeOnDemand": [
    ],
  • "query": {
    }
}

Response samples

Content type
application/json; charset=UTF-8
{
  • "_links": {
    },
  • "jobStatus": "created",
  • "_createdAt": "2022-03-20T17:53:23.282Z",
  • "_createdBy": "user@example.com",
  • "_modifiedAt": "2022-03-20T17:53:26.321Z",
  • "X-Amzn-Trace-Id": "Root=1-62bcb5d3-3b211f8616879dea3bde593f",
  • "errors": [
    ]
}

Sync export including calculations

Alternative to the POST version of the endpoint, for integrations that can only rely on synchronous GET requests. Use of this endpoint is not recommended as it might lead to timeouts if the data calculations exceed a certain size.

Calculations

✅ Pre-Filter
✅ Post-Filter
❌ Linking Calculations
❌ On-Demand

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

datasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Dataset unique identifier

exportFormat
string
Enum: "jsonRows" "jsonColumns" "jsonObjects" "csv" "tsv"
Example: jsonRows

The data format to use in the response. If no export format is provided the default jsonRows will be used.

query Parameters
includeBOM
boolean
Default: true

Determines if a Byte Order Mark (BOM) is added to the beginning of the response payload. This query parameter is only implemented for requests with an exportFormat value of CSV or TSV. Defaults to true.

lineEndings
string
Default: "windows"
Enum: "unix" "windows"

Determines the line endings (row separators) for data export. This query parameter is only implemented for requests with an exportFormat value of CSV or TSV. Defaults to windows.

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Responses

Response samples

Content type
Example
{
  • "headers": [
    ],
  • "rows": [
    ]
}

Sync export excluding calculations

A synchronous endpoint that retrieves data from Orgvue.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

datasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Dataset unique identifier

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Responses

Response samples

Content type
application/json; charset=UTF-8
[
  • {
    },
  • {
    }
]

Sync export with filters excluding calculations

A synchronous endpoint that retrieves and filters data from Orgvue. Internal properties are only returned when requested via a projection.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

datasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Dataset unique identifier

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
filter
object <MongoDB query> (mongoFilter)

Row level filtering using MongoDB query

projection
object <{ [propertyKey]: 1 }> (itemsProjection)

Property filtering using a projection object

Responses

Request samples

Content type
application/json; charset=UTF-8
{
  • "filter": {
    },
  • "projection": {
    }
}

Response samples

Content type
application/json; charset=UTF-8
[
  • {
    },
  • {
    }
]

Sync import

A synchronous endpoint that enables data ingress into Orgvue. The payload consists of a sequence of CRUD items operations, one each for an object of the dataset. Ingress behaviour can be controlled by the query parameters provided. Setting an attribute to null has the effect of clearing the value in Orgvue.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

datasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Dataset unique identifier

query Parameters
dateFormat
string
Enum: "YYYY-MM-DD" "DD/MM/YYYY" "MM/DD/YYYY"
Example: dateFormat=YYYY-MM-DD

The date format that items are presented in at the payload of your request. This query parameter can only be set once per request, and all items must be presented in the same format in the payload. Items presented in a different dateFormat, will be ingested as strings and not dates.

onPropertyAccessDenied
string
Enum: "skipProperty" "denyItemAccess"
Example: onPropertyAccessDenied=denyItemAccess

In the case where you do not have sufficient access rights to alter one or more properties, you can specify denyItemAccess to prevent all updates from taking place. Alternatively you can specify skipProperty to allow the update to take place only for properties you have been granted access to. Defaults to denyItemAccess.

onItemAccessDenied
string
Enum: "skipAction" "failTransaction"

In the case where you do not have sufficient access rights to alter one or more items, you can specify failTransaction to prevent all updates from taking place. Alternatively you can specify skipAction to allow the update to take place only for items you have been granted access to. Defaults to failTransaction.

onActionValidationFailure
string
Enum: "skipAction" "failTransaction"
Example: onActionValidationFailure=failTransaction

In the case where you have provided an invalid action for one or more items, you can specify failTransaction to prevent all updates from taking place. Alternatively you can specify skipAction to allow the update to take place only for updates with valid actions. Defaults to failTransaction.

autoId
boolean
Example: autoId=true

Relies on the automatic identifier in your dataset (the property configured as the "autoId"), instead of the internal Orgvue _id property. Setting this query parameter to true allows you to substitute the _id attribute in the payload for your custom property identifier.

idKey
string
Example: idKey=firstName

Consider the case where you can uniquely identify a node in your dataset by means of one or more property values in the node, instead of the Orgvue internal _id property value. Setting this query parameter to track the property or properties mentioned allows you to substitute the _id attribute in the payload for your custom property identifier(s). You can specify this query parameter multiple times.

mergeKey
string
Example: mergeKey=area

In the case of bulk updates you can use this query parameters to specify one or more properties that if present in an item, will include the item to the bulk update.

implicitDelete
boolean
Example: implicitDelete=true

Only use this query parameter when you want to replace all existing items in a dataset with the ones in this payload. Any items not in the payload of this request will be deleted in the dataset after the ingress completes. Assumes access to individual items in the dataset is granted ahead of time, for deletion purposes. If an operation is skipped the item corresponding to it will not be deleted.

clearToken
string
Example: clearToken=REMOVE_ME

A user can specify their own String values in import cells to represent clearing out a value. Null and emptyString are the default clear tokens. As such these are always applied clear tokens without the requirement to explicitly state as a query parameter

noopToken
string
Example: noopToken=IGNORE_ME

A user can specify their own String values in import cells that result in no change to the data.

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
Array
_action
required
string (action)
Enum: "create" "update" "replace" "delete" "createOrUpdate" "createOrReplace" "noop"

The action to perform on this item. Please note that not all actions are available at all times. Further, you might not have permission to perform some actions.

_id
string

The internal value used to uniquely identify an item in the dataset by Orgvue in the default mode.

_sortOrder
number

The internal row sort order of the item

property name*
additional property
string or boolean or number

Dataset property keys paired with values, to be updated as part of this request. The keys must match dataset properties exactly. If you have specified the autoId query parameter, you must provide a value for the property mapped to autoId. If you have specified one or more idKeys you must provide a value for each of the idKey properties. If you have specified one or more mergeKeys you must provide a value for each of the mergeKey properties.

Responses

Request samples

Content type
application/json; charset=UTF-8
[
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json; charset=UTF-8
[
  • {
    },
  • {
    },
  • {
    }
]

Async import

An asynchronous endpoint that enables data ingress into Orgvue.

Creates a jobTicket resource which in turn contains a URL to poll for the requested job data. Ingress behaviour can be controlled by the query parameters provided.

You can use this endpoint with the resources produced by the "Create a secure file" endpoint. Before making a request to this endpoint, upload your data to the intended import location in either JSON or CSV format. JSON payloads should have the same structure as the example provided for the PUT items endpoint. Data provided in CSV format should follow the rules outlined in the "Import Items from a CSV" section of the Usage Examples.

Note the following recommended max files sizes when used with Async import:

File Type Uncompressed Zipped
JSON 200MB 300MB
CSV 450MB 400MB

If your payload exceeds these recomendations we advise splitting larger updates into batches.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

datasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Dataset unique identifier

query Parameters
dateFormat
string
Enum: "YYYY-MM-DD" "DD/MM/YYYY" "MM/DD/YYYY"
Example: dateFormat=YYYY-MM-DD

The date format that items are presented in at the payload of your request. This query parameter can only be set once per request, and all items must be presented in the same format in the payload. Items presented in a different dateFormat, will be ingested as strings and not dates.

onPropertyAccessDenied
string
Enum: "skipProperty" "denyItemAccess"
Example: onPropertyAccessDenied=denyItemAccess

In the case where you do not have sufficient access rights to alter one or more properties, you can specify denyItemAccess to prevent all updates from taking place. Alternatively you can specify skipProperty to allow the update to take place only for properties you have been granted access to. Defaults to denyItemAccess.

onItemAccessDenied
string
Enum: "skipAction" "failTransaction"

In the case where you do not have sufficient access rights to alter one or more items, you can specify failTransaction to prevent all updates from taking place. Alternatively you can specify skipAction to allow the update to take place only for items you have been granted access to. Defaults to failTransaction.

onActionValidationFailure
string
Enum: "skipAction" "failTransaction"
Example: onActionValidationFailure=failTransaction

In the case where you have provided an invalid action for one or more items, you can specify failTransaction to prevent all updates from taking place. Alternatively you can specify skipAction to allow the update to take place only for updates with valid actions. Defaults to failTransaction.

autoId
boolean
Example: autoId=true

Relies on the automatic identifier in your dataset (the property configured as the "autoId"), instead of the internal Orgvue _id property. Setting this query parameter to true allows you to substitute the _id attribute in the payload for your custom property identifier.

idKey
string
Example: idKey=firstName

Consider the case where you can uniquely identify a node in your dataset by means of one or more property values in the node, instead of the Orgvue internal _id property value. Setting this query parameter to track the property or properties mentioned allows you to substitute the _id attribute in the payload for your custom property identifier(s). You can specify this query parameter multiple times.

mergeKey
string
Example: mergeKey=area

In the case of bulk updates you can use this query parameters to specify one or more properties that if present in an item, will include the item to the bulk update.

implicitDelete
boolean
Example: implicitDelete=true

Only use this query parameter when you want to replace all existing items in a dataset with the ones in this payload. Any items not in the payload of this request will be deleted in the dataset after the ingress completes. Assumes access to individual items in the dataset is granted ahead of time, for deletion purposes. If an operation is skipped the item corresponding to it will not be deleted.

clearToken
string
Example: clearToken=REMOVE_ME

A user can specify their own String values in import cells to represent clearing out a value. Null and emptyString are the default clear tokens. As such these are always applied clear tokens without the requirement to explicitly state as a query parameter

noopToken
string
Example: noopToken=IGNORE_ME

A user can specify their own String values in import cells that result in no change to the data.

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
required
object

Resource location that our API will ingest data from. Must be a secure URL location to an infrastructure object the lifecycle of which you own, where our API can have access to perform a http "GET" request to.

object (resultLocation)

Provide this object to divert your result data to a storage location of your choice. It must be a secure resource compatible with the presigned URL mechanism for an object for which you own the lifecycle, which our API can use to upload data via an http "PUT" request.

object (callbackPayload)

The callback mechanism allows you to configure a request to be made by the Orgvue API when processing your asynchronous request is complete. The callback request is sent when the jobTicket is 'completed' or 'failed'.

Responses

Request samples

Content type
application/json; charset=UTF-8
{}

Response samples

Content type
application/json; charset=UTF-8
{
  • "_links": {
    },
  • "jobStatus": "created",
  • "_createdAt": "2022-03-20T17:53:23.282Z",
  • "_createdBy": "user@example.com",
  • "_modifiedAt": "2022-03-20T17:53:26.321Z",
  • "X-Amzn-Trace-Id": "Root=1-62bcb5d3-3b211f8616879dea3bde593f",
  • "errors": [
    ]
}

Apply draft data to a dataset

An asynchronous endpoint that returns a jobTicket resource, which in turn contains a URL to poll for the result of the draft application.

The updates represented by the combined drafts will be applied to the dataset as if sent to the items import endpoint.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

datasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Dataset unique identifier

query Parameters
encoding
string
Enum: "gzip" "identity"
Example: encoding=gzip

Determines whether the data written to the result location will be compressed using gzip. Defaults to identity (meaning no compression). This will be deprecated in favour of resultEncoding.

resultEncoding
string
Enum: "gzip" "identity"
Example: resultEncoding=gzip

Determines whether the data written to the result location will be compressed using gzip. Defaults to identity (meaning no compression).

onPropertyAccessDenied
string
Enum: "skipProperty" "denyItemAccess"
Example: onPropertyAccessDenied=denyItemAccess

In the case where you do not have sufficient access rights to alter one or more properties, you can specify denyItemAccess to prevent all updates from taking place. Alternatively you can specify skipProperty to allow the update to take place only for properties you have been granted access to. Defaults to denyItemAccess.

onItemAccessDenied
string
Enum: "skipAction" "failTransaction"

In the case where you do not have sufficient access rights to alter one or more items, you can specify failTransaction to prevent all updates from taking place. Alternatively you can specify skipAction to allow the update to take place only for items you have been granted access to. Defaults to failTransaction.

onActionValidationFailure
string
Enum: "skipAction" "failTransaction"
Example: onActionValidationFailure=failTransaction

In the case where you have provided an invalid action for one or more items, you can specify failTransaction to prevent all updates from taking place. Alternatively you can specify skipAction to allow the update to take place only for updates with valid actions. Defaults to failTransaction.

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
required
Array of objects (draftLayersArray)

An array of draft layer objects in the order in which they should be applied.

foldScheme
string
Enum: "distinct" "lossless" "ordered"

The type of folding required when multiple draft layers are provided. Defaults to "distinct".

distinct Any node autoID appearing in more than one draft layer results in a conflict in the output dataset. Any conflict will result in failure of merge for duplicated nodes.

lossless Attempts to merge layer records that share the same node autoID. If attributes conflict, merging fails for those nodes.

ordered Performs layered merging of records with the same node autoID, respecting the order of layers provided in the array. Later layers can overwrite earlier ones for overlapping attributes.

object (callbackPayload)

The callback mechanism allows you to configure a request to be made by the Orgvue API when processing your asynchronous request is complete. The callback request is sent when the jobTicket is 'completed' or 'failed'.

object (resultLocation)

Provide this object to divert your result data to a storage location of your choice. It must be a secure resource compatible with the presigned URL mechanism for an object for which you own the lifecycle, which our API can use to upload data via an http "PUT" request.

Responses

Request samples

Content type
application/json; charset=UTF-8
{}

Response samples

Content type
application/json; charset=UTF-8
{
  • "_links": {
    },
  • "jobStatus": "created",
  • "_createdAt": "2022-03-20T17:53:23.282Z",
  • "_createdBy": "user@example.com",
  • "_modifiedAt": "2022-03-20T17:53:26.321Z",
  • "X-Amzn-Trace-Id": "Root=1-62bcb5d3-3b211f8616879dea3bde593f",
  • "errors": [
    ]
}

Evaluate on-demand calculations

An asynchronous endpoint that returns a jobTicket resource, which in turn contains a URL to poll for the result of the job.

To use this endpoint your dataset needs to be configured ahead of time to contain on-demand calculations. Using this endpoint re-calculates all values for the on-demand properties in your dataset, and then applies the changes to the dataset.

Note: This endpoint performs an update on your dataset. As such, it is a governance issue on your side to ensure there are no other updates sent to the dataset at the same time. As with all updates to your datasets: the last update wins.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

datasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Dataset unique identifier

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
optional
executeOnDemand
required
Array of strings non-empty unique

Array of unique on-demand properties to calculate and update in the dataset. These properties must be configured ahead of time. They must be passed to the API in the correct order for your on-demand calculation to be meaningful.

object (datasetLinking)

Provide relevant dataset configuration information. A Links datasetId may be supplied in the linkingRelationships to allow calculations to be executed with the context of a specific linked dataset.

object (callbackPayload)

The callback mechanism allows you to configure a request to be made by the Orgvue API when processing your asynchronous request is complete. The callback request is sent when the jobTicket is 'completed' or 'failed'.

object (resultLocation)

Provide this object to divert your result data to a storage location of your choice. It must be a secure resource compatible with the presigned URL mechanism for an object for which you own the lifecycle, which our API can use to upload data via an http "PUT" request.

Responses

Request samples

Content type
application/json; charset=UTF-8
{}

Response samples

Content type
application/json; charset=UTF-8
{
  • "_links": {
    },
  • "jobStatus": "created",
  • "_createdAt": "2022-03-20T17:53:23.282Z",
  • "_createdBy": "user@example.com",
  • "_modifiedAt": "2022-03-20T17:53:26.321Z",
  • "X-Amzn-Trace-Id": "Root=1-62bcb5d3-3b211f8616879dea3bde593f",
  • "errors": [
    ]
}

Create links dataset

Creates a new links dataset resource.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
required
name
required
string

The name of the links dataset.

fromDatasetId
required
string <uuid>

The unique identifier of the dataset you are linking from.

toDatasetId
required
string <uuid>

The unique identifier of the dataset you are linking to.

Array of objects

Array of property objects

tags
Array of strings

Array of shared tags for the links dataset.

Responses

Request samples

Content type
application/json; charset=UTF-8
{
  • "name": "PEOPLE to ROLES Links Dataset",
  • "fromDatasetId": "99CD8A1B-61A2-4768-87FA-3D10420FC535",
  • "toDatasetId": "2B44BAD6-6680-4A19-A00C-0366832E2BD6",
  • "additionalProperties": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json; charset=UTF-8
{
  • "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2",
  • "name": "PEOPLE to ROLES Links Dataset",
  • "type": "LINKS",
  • "createdBy": "user@example.com",
  • "cacheKey": "abc5DeFgh3IjK5L76/ABCdeEFGHIJklMNo+pqRstuvwxYZENuHvV863y5BtEhGTuqnP2cLZhys9EQ==",
  • "autoId": "link_id",
  • "tags": [
    ],
  • "properties": [
    ]
}

Update links dataset

Updates a links dataset resource. The configuration in the request payload is merged onto the existing links dataset configuration.

The value null may be used for keys that are not required in order to remove them. For example, tags may be set to null in order to completely remove tags from the links dataset.

Additional properties are merged based on the key value. If an existing key is matched the property is updated, otherwise a new property is created. If it is necessary to delete properties, the deleteOmittedProperties query parameter must be used. If set to true, any existing properties not matched in the provided payload by key will be removed. Note that this does not apply to the core properties from_id, to_id, allocation and link_id, which may not be modified.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

linksDatasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Links dataset unique identifier

query Parameters
deleteOmittedProperties
boolean
Default: false

Only use this parameter if you wish to delete any properties that don't appear in the additionalProperties array of your payload. If an array of properties is supplied and this query parameter is set to true, any existing additional properties that are not matched by key will be deleted. By default no properties are deleted. Note that this does not apply to the core properties from_id, to_id, allocation and link_id, which may not be modified.

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
required
name
string

The name of the links dataset.

Array of objects (updatePropertiesListItem)

Array of partial property objects.

tags
Array of strings or null

Array of shared tags for the links dataset.

Responses

Request samples

Content type
application/json; charset=UTF-8
{
  • "name": "PEOPLE to ROLES Links Dataset",
  • "additionalProperties": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json; charset=UTF-8
{
  • "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2",
  • "name": "PEOPLE to ROLES Links Dataset",
  • "type": "LINKS",
  • "createdBy": "user@example.com",
  • "cacheKey": "abc5DeFgh3IjK5L76/ABCdeEFGHIJklMNo+pqRstuvwxYZENuHvV863y5BtEhGTuqnP2cLZhys9EQ==",
  • "autoId": "link_id",
  • "tags": [
    ],
  • "properties": [
    ]
}

Populate links dataset

If you have a single dataset which contains the from_id, to_id and allocation property of a links dataset you have already created, you can use this endpoint to automate the uploading of nodes to that links dataset.

Note: this endpoint will create or replace all nodes in the links dataset; any items in the links dataset but not in either of the source or target datasets will be deleted.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

linksDatasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Links dataset unique identifier

query Parameters
resultEncoding
string
Enum: "gzip" "identity"
Example: resultEncoding=gzip

Determines whether the data written to the result location will be compressed using gzip. Defaults to identity (meaning no compression).

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
sourceDatasetId
required
string

The id of the source dataset that contains the from_id and to_id properties of the links dataset

targetDatasetAutoId
required
string

The property which holds the autoId of the target dataset

allocationId
string

The property which holds the allocation property of the links dataset

object (resultLocation)

Provide this object to divert your result data to a storage location of your choice. It must be a secure resource compatible with the presigned URL mechanism for an object for which you own the lifecycle, which our API can use to upload data via an http "PUT" request.

object (callbackPayload)

The callback mechanism allows you to configure a request to be made by the Orgvue API when processing your asynchronous request is complete. The callback request is sent when the jobTicket is 'completed' or 'failed'.

Responses

Request samples

Content type
application/json; charset=UTF-8
{}

Response samples

Content type
application/json; charset=UTF-8
{
  • "_links": {
    },
  • "jobStatus": "created",
  • "_createdAt": "2022-03-20T17:53:23.282Z",
  • "_createdBy": "user@example.com",
  • "_modifiedAt": "2022-03-20T17:53:26.321Z",
  • "X-Amzn-Trace-Id": "Root=1-62bcb5d3-3b211f8616879dea3bde593f",
  • "errors": [
    ]
}

Sync import

A synchronous endpoint for modifying data in linking datasets (with type "LINKS"). The payload consists of a sequence of CRUD items operations, one each for an object of the dataset. Records are uniquely identified via the combination of the from_id and to_id properties. These values will be used to generate the unique autoId value for a specific link.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

linksDatasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Links dataset unique identifier

query Parameters
dateFormat
string
Enum: "YYYY-MM-DD" "DD/MM/YYYY" "MM/DD/YYYY"
Example: dateFormat=YYYY-MM-DD

The date format that items are presented in at the payload of your request. This query parameter can only be set once per request, and all items must be presented in the same format in the payload. Items presented in a different dateFormat, will be ingested as strings and not dates.

onPropertyAccessDenied
string
Enum: "skipProperty" "denyItemAccess"
Example: onPropertyAccessDenied=denyItemAccess

In the case where you do not have sufficient access rights to alter one or more properties, you can specify denyItemAccess to prevent all updates from taking place. Alternatively you can specify skipProperty to allow the update to take place only for properties you have been granted access to. Defaults to denyItemAccess.

onItemAccessDenied
string
Enum: "skipAction" "failTransaction"

In the case where you do not have sufficient access rights to alter one or more items, you can specify failTransaction to prevent all updates from taking place. Alternatively you can specify skipAction to allow the update to take place only for items you have been granted access to. Defaults to failTransaction.

onActionValidationFailure
string
Enum: "skipAction" "failTransaction"
Example: onActionValidationFailure=failTransaction

In the case where you have provided an invalid action for one or more items, you can specify failTransaction to prevent all updates from taking place. Alternatively you can specify skipAction to allow the update to take place only for updates with valid actions. Defaults to failTransaction.

implicitDelete
boolean
Example: implicitDelete=true

Only use this query parameter when you want to replace all existing items in a dataset with the ones in this payload. Any items not in the payload of this request will be deleted in the dataset after the ingress completes. Assumes access to individual items in the dataset is granted ahead of time, for deletion purposes. If an operation is skipped the item corresponding to it will not be deleted.

clearToken
string
Example: clearToken=REMOVE_ME

A user can specify their own String values in import cells to represent clearing out a value. Null and emptyString are the default clear tokens. As such these are always applied clear tokens without the requirement to explicitly state as a query parameter

noopToken
string
Example: noopToken=IGNORE_ME

A user can specify their own String values in import cells that result in no change to the data.

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
required
Array
_action
required
string (action)
Enum: "create" "update" "replace" "delete" "createOrUpdate" "createOrReplace" "noop"

The action to perform on this item. Please note that not all actions are available at all times. Further, you might not have permission to perform some actions.

from_id
required
string or boolean or number or null

The value of the autoId property of the node in the linked dataset you wish to create a link 'from'. You can review which dataset is configured as the 'from' dataset in Orgvue Settings.

to_id
required
string or boolean or number or null

The value of the autoId property of the node in the linked dataset you wish to create a link 'to'. You can review which dataset is configured as the 'to' dataset in Orgvue Settings.

property name*
additional property
string or boolean or number

Dataset property keys paired with values, to be updated as part of this request. The keys must match dataset properties exactly. Note that the value for the autoId property will be generated from the required from_id and to_id values. If explicitly supplied it will be ignored.

Responses

Request samples

Content type
application/json; charset=UTF-8
[
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json; charset=UTF-8
[
  • {
    },
  • {
    },
  • {
    }
]

Async import

An asynchronous endpoint that enables data ingress into Orgvue.

Creates a jobTicket resource which in turn contains a URL to poll for the requested job data. Ingress behaviour can be controlled by the query parameters provided.

You can use this endpoint with the resources produced by the temporary resources endpoint. Before making a request to this endpoint you should upload data to the intended import location in the same format as the payload for the PUT links items endpoint.

Note that we advise splitting larger updates into batches of no more than 25,000 actions for up to 100 properties. If more properties are being updated the number of actions in a batch should be reduced proportionally.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

linksDatasetId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Links dataset unique identifier

query Parameters
dateFormat
string
Enum: "YYYY-MM-DD" "DD/MM/YYYY" "MM/DD/YYYY"
Example: dateFormat=YYYY-MM-DD

The date format that items are presented in at the payload of your request. This query parameter can only be set once per request, and all items must be presented in the same format in the payload. Items presented in a different dateFormat, will be ingested as strings and not dates.

onPropertyAccessDenied
string
Enum: "skipProperty" "denyItemAccess"
Example: onPropertyAccessDenied=denyItemAccess

In the case where you do not have sufficient access rights to alter one or more properties, you can specify denyItemAccess to prevent all updates from taking place. Alternatively you can specify skipProperty to allow the update to take place only for properties you have been granted access to. Defaults to denyItemAccess.

onItemAccessDenied
string
Enum: "skipAction" "failTransaction"

In the case where you do not have sufficient access rights to alter one or more items, you can specify failTransaction to prevent all updates from taking place. Alternatively you can specify skipAction to allow the update to take place only for items you have been granted access to. Defaults to failTransaction.

onActionValidationFailure
string
Enum: "skipAction" "failTransaction"
Example: onActionValidationFailure=failTransaction

In the case where you have provided an invalid action for one or more items, you can specify failTransaction to prevent all updates from taking place. Alternatively you can specify skipAction to allow the update to take place only for updates with valid actions. Defaults to failTransaction.

implicitDelete
boolean
Example: implicitDelete=true

Only use this query parameter when you want to replace all existing items in a dataset with the ones in this payload. Any items not in the payload of this request will be deleted in the dataset after the ingress completes. Assumes access to individual items in the dataset is granted ahead of time, for deletion purposes. If an operation is skipped the item corresponding to it will not be deleted.

clearToken
string
Example: clearToken=REMOVE_ME

A user can specify their own String values in import cells to represent clearing out a value. Null and emptyString are the default clear tokens. As such these are always applied clear tokens without the requirement to explicitly state as a query parameter

noopToken
string
Example: noopToken=IGNORE_ME

A user can specify their own String values in import cells that result in no change to the data.

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
required
object

Resource location that our API will ingest data from. Must be a secure URL location to an infrastructure object the lifecycle of which you own, where our API can have access to perform a http "GET" request to.

object (resultLocation)

Provide this object to divert your result data to a storage location of your choice. It must be a secure resource compatible with the presigned URL mechanism for an object for which you own the lifecycle, which our API can use to upload data via an http "PUT" request.

object (callbackPayload)

The callback mechanism allows you to configure a request to be made by the Orgvue API when processing your asynchronous request is complete. The callback request is sent when the jobTicket is 'completed' or 'failed'.

Responses

Request samples

Content type
application/json; charset=UTF-8
{}

Response samples

Content type
application/json; charset=UTF-8
{
  • "_links": {
    },
  • "jobStatus": "created",
  • "_createdAt": "2022-03-20T17:53:23.282Z",
  • "_createdBy": "user@example.com",
  • "_modifiedAt": "2022-03-20T17:53:26.321Z",
  • "X-Amzn-Trace-Id": "Root=1-62bcb5d3-3b211f8616879dea3bde593f",
  • "errors": [
    ]
}

Draft Operations

Draft level operations

List drafts

A synchronous endpoint that retrieves drafts for a tenant from Orgvue with specified filters and/ or projections.

Note: You can only filter by a draft's name, description or createdBy.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
filter
object <MongoDB query>

Row level filtering using MongoDB query. Note: for this endpoint you can only filter by a draft's name, description or createdBy.

projection
object <{ [propertyKey]: 1 }> (itemsProjection)

Property filtering using a projection object

Responses

Request samples

Content type
application/json; charset=UTF-8
{
  • "filter": {
    },
  • "projection": {
    }
}

Response samples

Content type
application/json; charset=UTF-8"
{
  • "draftId": "36A1E02D-DC20-61C5-A11F-DD85440C652C",
  • "name": "Finance Scenario Model",
  • "description": "A scenario of our future Finance organization structure.",
  • "createdBy": "user@example.com",
  • "modifiedAt": "2020-05-29T09:43:03.953Z",
  • "tags": [
    ],
  • "_links": {
    }
}

Draft metadata

Returns a representation of the draft resource.

We provide additional HATEOAS _links to navigate to available next actions.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

draftId
required
string <uuid>
Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B

Draft unique identifier

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Responses

Response samples

Content type
application/json; charset=UTF-8
{
  • "draftId": "36A1E02D-DC20-61C5-A11F-DD85440C652C",
  • "name": "Finance Scenario Model",
  • "description": "A scenario of our future Finance organization structure.",
  • "createdBy": "user@example.com",
  • "modifiedAt": "2020-05-29T09:43:03.953Z",
  • "tags": [
    ],
  • "_links": {
    }
}

Async export excluding calculations

An asynchronous endpoint that returns a jobTicket resource, which in turn contains a URL to poll for the requested data. An array of item actions represented by the requested draft layers will be written to the result location once the process is complete. These actions may be sent to the items import endpoint to apply the draft changes to the dataset.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

query Parameters
encoding
string
Enum: "gzip" "identity"
Example: encoding=gzip

Determines whether the data written to the result location will be compressed using gzip. Defaults to identity (meaning no compression). This will be deprecated in favour of resultEncoding.

resultEncoding
string
Enum: "gzip" "identity"
Example: resultEncoding=gzip

Determines whether the data written to the result location will be compressed using gzip. Defaults to identity (meaning no compression).

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
required
Array of objects (draftLayersArray)

An array of draft layer objects in the order in which they should be applied.

foldScheme
string
Enum: "distinct" "lossless" "ordered"

The type of folding required when multiple draft layers are provided. Defaults to "distinct".

distinct Any node autoID appearing in more than one draft layer results in a conflict in the output dataset. Any conflict will result in failure of merge for duplicated nodes.

lossless Attempts to merge layer records that share the same node autoID. If attributes conflict, merging fails for those nodes.

ordered Performs layered merging of records with the same node autoID, respecting the order of layers provided in the array. Later layers can overwrite earlier ones for overlapping attributes.

object (callbackPayload)

The callback mechanism allows you to configure a request to be made by the Orgvue API when processing your asynchronous request is complete. The callback request is sent when the jobTicket is 'completed' or 'failed'.

object (resultLocation)

Provide this object to divert your result data to a storage location of your choice. It must be a secure resource compatible with the presigned URL mechanism for an object for which you own the lifecycle, which our API can use to upload data via an http "PUT" request.

Responses

Request samples

Content type
application/json; charset=UTF-8
{}

Response samples

Content type
application/json; charset=UTF-8
{
  • "_links": {
    },
  • "jobStatus": "created",
  • "_createdAt": "2022-03-20T17:53:23.282Z",
  • "_createdBy": "user@example.com",
  • "_modifiedAt": "2022-03-20T17:53:26.321Z",
  • "X-Amzn-Trace-Id": "Root=1-62bcb5d3-3b211f8616879dea3bde593f",
  • "errors": [
    ]
}

Clear draft actions

Remove all or specific edits, changes, or additions that you have made to the dataset in draft.

To remove specific edits include the filter object and properties you want to filter by.

Otherwise, all edits will be removed and the dataset will be restored to its original state. This would effectively erase all of your work on the draft.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
required
Array of objects

An array of draft layer objects in the order in which they will be cleared.

object

An object containing mongoDB queries that filter the actions you want cleared from the draft layers specified in 'layers'.

Responses

Request samples

Content type
application/json; charset=UTF-8
{
  • "layers": [
    ],
  • "filter": {
    }
}

Response samples

Content type
application/json; charset=UTF-8
[
  • {
    },
  • {
    },
  • {
    }
]

File Operations

File level operations

Create a secure file

Generates a temporary secure file location and provides GET and PUT URLs to read from and write to the location. Data written to the location is securely encrypted at rest, and will be automatically deleted after a set period. The GET and PUT URLs also have fixed lifespans so that access is completely restricted once a reasonable usage period has concluded.

This secure location can be used in tandem with import and export processes.

For import, you would upload your required updates via the PUT URL and then send us the GET URL to process the update.

For export, you would send us the PUT URL and use the GET URL to access your requested data once processing is complete.

See the respective endpoints for further details.

Authorizations:
bearerAuth
path Parameters
tenantId
required
string^[A-Z][A-Z0-9_]{0,29}$
Example: TENANT_ID

Tenant identifier

header Parameters
Accept-Encoding
string
Enum: "gzip" "identity"

Add this request header to compress the response you receive. For asynchronous endpoints using this header compresses the response containing the jobTicket and not the result of the calculation.

Request Body schema: application/json; charset=UTF-8
required
targetType
required
string
Enum: "json" "csv" "tsv"

Determines format of the data written to the file

targetEncoding
required
string
Enum: "gzip" "identity"

Determines whether the data written to the file is compressed by gzip

Responses

Request samples

Content type
application/json; charset=UTF-8
{
  • "targetType": "json",
  • "targetEncoding": "identity"
}

Response samples

Content type
application/json; charset=UTF-8
{}

jobTicket

The asynchronous result entity produced by the export API, containing next link actions

required
object

HATEOAS next available actions links

jobStatus
required
string
Enum: "created" "running" "failed" "completed"

The status of the job tracked by this jobTicket

_createdAt
required
string

ISO8601 creation timestamp of this job

_createdBy
required
string <email>

Email address of the account that created this job

_modifiedAt
string

ISO8601 latest update timestamp of this job

X-Amzn-Trace-Id
required
string

Unique tracking identifier for this request

Array of objects

Only present if the job has completed in the "failed" status

{
  • "_links": {
    },
  • "jobStatus": "created",
  • "_createdAt": "2022-03-20T17:53:23.282Z",
  • "_createdBy": "user@example.com",
  • "_modifiedAt": "2022-03-20T17:53:26.321Z",
  • "X-Amzn-Trace-Id": "Root=1-62bcb5d3-3b211f8616879dea3bde593f",
  • "errors": [
    ]
}

Client Error

Receiving one or more of these objects in a response indicates that the server cannot process the request due to a client side error. You can use the information in the error object to correct and retry your request.

Array of objects
Array
code
required
string

The unique code of the error

name
required
string

The unique name of the error

message
string

A human readable message that helps you correct your request. Exact content may change. It should not be used to determine subsequent actions.

pathParameter
string

Points to the path parameter of the entity you need to correct

queryParameter
string

Points to the query parameter of the entity you need to correct

jsonBody
string

Points to the JSON path of the entity you need to correct

resourcePath
string

Points to the resource path of the entity you need to correct

{
  • "errors": [
    ]
}

Internal Server Error

Receiving one or more of these objects in a response indicates that the server cannot process the request due to an internal server error. You may or may not be able to retry your request.

If the request specified that customer owned infrastructure be used, the server might encounter asynchronous errors. Optional error attributes will contain the downstream error received by the server from the customer owned resource. The request can be retried after issues with the resource have been addressed.

Array of objects
Array
code
required
string

The unique code of the error

name
required
string

The unique name of the error

message
string

A human readable message that helps you correct your request. Exact content may change. It should not be used to determine subsequent actions.

errorContentType
string

Only available when specifying customer owned infrastructure. The Content-Type response header value of an error we received from your infrastructure provider

errorContent
string

Only available when specifying customer owned infrastructure. String representation of the error payload that we received from your infrastructure provider when we attempted a http PUT to the location

{
  • "errors": [
    ]
}