Orgvue API specification
Download OpenAPI specification:Download
This page contains the Open API specification of the Orgvue API. It contains all the information needed to configure your integration.
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:
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 |
Responses
Response samples
- 200
- 4XX
- 5XX
[- {
- "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2",
- "name": "EXAMPLE_DATASET",
- "type": "POSITIONS",
- "isPermissionedView": false,
- "_links": {
- "dataset:retrieve": {
- "method": "GET",
- "type": "application/json; charset=UTF-8"
}, - "dataset:export": {
- "method": "POST",
- "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:
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 |
Request Body schema: application/json; charset=UTF-8required
name required | string The name of the dataset |
type required | string The type of the dataset. Note type |
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
- Payload
{- "name": "Positions",
- "type": "POSITIONS",
- "autoId": "position_id",
- "labelId": "position_title",
- "tags": [
- "hr"
], - "treeId": "position_id",
- "treeParentId": "position_managerid",
- "properties": [
- {
- "0": {
- "key": "firstName",
- "name": "First Name",
- "type": "text"
}, - "1": {
- "key": "position_id",
- "name": "Position ID",
- "type": "text"
}, - "2": {
- "key": "position_title",
- "name": "Position Title",
- "type": "text"
}, - "3": {
- "key": "salary",
- "name": "Salary",
- "type": "number"
}
}
]
}
Response samples
- 200
- 4XX
- 5XX
{- "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": [
- "hr"
], - "treeId": "position_id",
- "treeParentId": "position_managerid",
- "properties": [
- {
- "key": "firstName",
- "name": "First Name",
- "type": "text"
}, - {
- "key": "position_id",
- "name": "Position ID",
- "type": "text"
}, - {
- "key": "position_title",
- "name": "Position Title",
- "type": "text"
}, - {
- "key": "salary",
- "name": "Salary",
- "type": "number"
}
]
}
Update dataset
Early access preview: 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:
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 |
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 |
Request Body schema: application/json; charset=UTF-8required
name | string The name of the dataset |
type | string The type of the dataset. Note type |
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
- Payload
{- "name": "Positions",
- "type": "POSITIONS",
- "autoId": "position_id",
- "labelId": "position_title",
- "tags": [
- "hr"
], - "treeId": "string",
- "treeParentId": "string",
- "properties": [
- [
- {
- "key": "firstName",
- "name": "First Name",
- "type": "text"
}, - {
- "key": "position_id",
- "name": "Position ID",
- "type": "text"
}, - {
- "key": "position_title",
- "name": "Position Title",
- "type": "text"
}, - {
- "key": "salary",
- "name": "Salary",
- "type": "number"
}
]
]
}
Response samples
- 200
- 4XX
- 5XX
{- "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": [
- "hr"
], - "treeId": "position_id",
- "treeParentId": "position_managerid",
- "properties": [
- {
- "key": "firstName",
- "name": "First Name",
- "type": "text"
}, - {
- "key": "position_id",
- "name": "Position ID",
- "type": "text"
}, - {
- "key": "position_title",
- "name": "Position Title",
- "type": "text"
}, - {
- "key": "salary",
- "name": "Salary",
- "type": "number"
}
]
}
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:
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 |
Responses
Response samples
- 200
- 4XX
- 5XX
{- "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": [
- "hr"
], - "treeId": "position_id",
- "treeParentId": "position_managerid",
- "properties": [
- {
- "key": "firstName",
- "name": "First Name",
- "type": "text"
}, - {
- "key": "position_id",
- "name": "Position ID",
- "type": "text"
}, - {
- "key": "position_title",
- "name": "Position Title",
- "type": "text"
}, - {
- "key": "salary",
- "name": "Salary",
- "type": "number"
}
], - "items": {
- "lastTransactionId": "00000172-5FD0-4411-4140-B5A82D1111CD",
- "modifiedAt": "2020-05-29T09:43:03.953Z"
}, - "drafts": [
- {
- "draftId": "36A1E02D-DC20-61C5-A11F-DD85440C652C",
- "name": "string",
- "_links": {
- "draft:retrieve": {
- "method": "GET",
- "type": "application/json; charset=UTF-8"
}
}
}
], - "linkingRelationships": [
- {
- "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2",
- "name": "People to Positions Dataset",
- "type": "LINKS",
- "source": {
- "name": "string",
- "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2",
- "type": "PEOPLE",
- "_links": {
- "dataset:retrieve": {
- "method": "GET",
- "type": "application/json; charset=UTF-8"
}
}
}, - "target": {
- "name": "string",
- "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2",
- "type": "POSITIONS",
- "_links": {
- "dataset:retrieve": {
- "method": "GET",
- "type": "application/json; charset=UTF-8"
}
}
}, - "_links": {
- "export": {
- "url": "string",
- "method": "string",
- "contentType": "string",
- "jsonBody": {
- "dataset": {
- "linkingRelationships": [
- {
- "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2"
}
]
}, - "dataset:retrieve": {
- "method": "GET",
- "type": "application/json; charset=UTF-8"
}, - "required": null
}
}
}
}
], - "_links": {
- "self": {
- "method": "GET",
- "type": "application/json; charset=UTF-8"
}, - "dataset:export:jsonRows": {
- "method": "POST",
- "type": "application/json; charset=UTF-8"
}, - "dataset:export:jsonColumns": {
- "method": "POST",
- "type": "application/json; charset=UTF-8"
}, - "dataset:export:jsonObjects": {
- "method": "POST",
- "type": "application/json; charset=UTF-8"
}, - "dataset:export:csv": {
- "method": "POST",
- "type": "application/json; charset=UTF-8"
}, - "dataset:export:tsv": {
- "method": "POST",
- "type": "application/json; charset=UTF-8"
}
}
}
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:
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 |
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 |
resultEncoding | string Enum: "gzip" "identity" Example: resultEncoding=gzip Determines whether the data written to the result location will be compressed using gzip. Defaults to |
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 |
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 |
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 |
Request Body schema: application/json; charset=UTF-8optional
object (datasetLinking) Provide relevant dataset configuration information. A Links | |
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 | |
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 | |
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
- Payload
{- "dataset": {
- "linkingRelationships": [
- {
- "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2"
}
]
}, - "callback": {
- "method": "GET",
}, - "executeOnDemand": [
- "onDemandProperty1",
- "onDemandProperty2"
], - "query": {
- "output": {
- "filter": {
- "department": "Engineering",
- "salary": {
- "$gte": 50000
}, - "employeeGrade": {
- "$lt": 5
}, - "role": {
- "$nin": [
- "Manager",
- "Senior Engineer",
- "Team Lead"
]
}
}, - "projection": {
- "id": 1,
- "age": 0,
- "salary": 1,
- "employeeGrade": 2,
- "role": 3
}, - "projectionMode": "add"
}
}
}
Response samples
- 202
- 4XX
- 5XX
{- "_links": {
- "self": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "jobTicket"
}, - "result": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "downloadLink"
}
}, - "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": [
- {
- "code": "50001",
- "name": "InternalServerError",
- "message": "There was an internal error. If the issue persists you should contact support@orgvue.com.",
- "errorContentType": "application/xml",
- "errorContent": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Error><Code>NoSuchKey</Code><Message>The resource you requested does not exist</Message><Resource>/mybucket/myfoto.jpg</Resource><RequestId>4442587FB7D0A2F9</RequestId></Error>"
}
]
}
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:
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 |
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 |
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 |
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 |
Responses
Response samples
- 200
- 4XX
- 5XX
{- "headers": [
- {
- "key": "id",
- "name": "Id",
- "type": "text"
}, - {
- "key": "name",
- "name": "Name",
- "type": "text"
}, - {
- "key": "parent_id",
- "name": "Parent Id",
- "type": "text"
}, - {
- "key": "_change",
- "name": "Change",
- "type": "text"
}
], - "rows": [
- [
- "a",
- "Ana",
- null
], - [
- "b",
- "Bob",
- "a"
], - [
- "c",
- "Caz",
- "a"
]
]
}
Sync export excluding calculations
A synchronous endpoint that retrieves data from Orgvue.
Authorizations:
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 |
Responses
Response samples
- 200
- 4XX
- 5XX
[- {
- "employee_id": 1,
- "location": "USA",
- "city": "New York",
- "_id": "970725D4-436A-EDEB-E736-5EA5139F618A",
- "_access": "Item.delete",
- "_modifiedAt": "2011-10-05T14:48:00.000Z"
}, - {
- "employee_id": 2,
- "location": "UK",
- "city": "London",
- "_id": "970725D4-436A-EDEB-E736-5EA5139F618A",
- "_access": "Item.delete",
- "_modifiedAt": "2011-10-05T14:48:00.000Z"
}
]
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:
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 |
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
- Payload
{- "filter": {
- "department": "Engineering",
- "salary": {
- "$gte": 50000
}, - "employeeGrade": {
- "$lt": 5
}, - "role": {
- "$nin": [
- "Manager",
- "Senior Engineer",
- "Team Lead"
]
}
}, - "projection": {
- "employee_id": 1,
- "location": 1,
- "city": 1
}
}
Response samples
- 200
- 4XX
- 5XX
[- {
- "employee_id": 1,
- "location": "USA",
- "city": "New York",
- "_id": "970725D4-436A-EDEB-E736-5EA5139F618A",
- "_access": "Item.delete",
- "_modifiedAt": "2011-10-05T14:48:00.000Z"
}, - {
- "employee_id": 2,
- "location": "UK",
- "city": "London",
- "_id": "970725D4-436A-EDEB-E736-5EA5139F618A",
- "_access": "Item.delete",
- "_modifiedAt": "2011-10-05T14:48:00.000Z"
}
]
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:
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 |
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 |
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 |
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 |
autoId | boolean Example: autoId=true Relies on the automatic identifier in your dataset (the property configured as the "autoId"), instead of the internal Orgvue |
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 |
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. |
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 |
Request Body schema: application/json; charset=UTF-8
_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 |
Responses
Request samples
- Payload
[- {
- "_action": "createOrUpdate",
- "position_id": 10,
- "position_title": "CEO"
}, - {
- "_action": "createOrUpdate",
- "position_id": 12,
- "position_title": "Admin Assistant"
}, - {
- "_action": "delete",
- "position_id": 15
}
]
Response samples
- 200
- 4XX
- 5XX
[- {
- "_status": "success",
- "_id": "5C9EF1F8-0048-4CE9-91E7-789B857EE73C",
- "_action": "createOrUpdate"
}, - {
- "_status": "success",
- "_id": "7918D0B4-24AC-8A3E-E21C-1302FAE4937E",
- "_action": "createOrUpdate"
}, - {
- "_status": "success",
- "_id": "ECFB8805-002D-441C-92AE-39FFE9D88A20",
- "_action": "delete"
}
]
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 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:
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 |
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 |
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 |
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 |
autoId | boolean Example: autoId=true Relies on the automatic identifier in your dataset (the property configured as the "autoId"), instead of the internal Orgvue |
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 |
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. |
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 |
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 |
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 | |
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
- Payload
{- "callback": {
- "method": "GET",
}
}
Response samples
- 202
- 4XX
- 5XX
{- "_links": {
- "self": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "jobTicket"
}, - "result": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "downloadLink"
}
}, - "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": [
- {
- "code": "50001",
- "name": "InternalServerError",
- "message": "There was an internal error. If the issue persists you should contact support@orgvue.com.",
- "errorContentType": "application/xml",
- "errorContent": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Error><Code>NoSuchKey</Code><Message>The resource you requested does not exist</Message><Resource>/mybucket/myfoto.jpg</Resource><RequestId>4442587FB7D0A2F9</RequestId></Error>"
}
]
}
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:
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 |
resultEncoding | string Enum: "gzip" "identity" Example: resultEncoding=gzip Determines whether the data written to the result location will be compressed using gzip. Defaults to |
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 |
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 |
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 |
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 |
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".
|
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 |
Responses
Request samples
- Payload
{- "layers": [
- {
- "draftId": "36A1E02D-DC20-61C5-A11F-DD85440C652C",
- "layerKey": "default"
}
], - "foldScheme": "distinct",
- "callback": {
- "method": "GET",
},
}
Response samples
- 202
- 4XX
- 5XX
{- "_links": {
- "self": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "jobTicket"
}, - "result": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "downloadLink"
}
}, - "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": [
- {
- "code": "50001",
- "name": "InternalServerError",
- "message": "There was an internal error. If the issue persists you should contact support@orgvue.com.",
- "errorContentType": "application/xml",
- "errorContent": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Error><Code>NoSuchKey</Code><Message>The resource you requested does not exist</Message><Resource>/mybucket/myfoto.jpg</Resource><RequestId>4442587FB7D0A2F9</RequestId></Error>"
}
]
}
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:
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 |
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 |
Request Body schema: application/json; charset=UTF-8optional
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 | |
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 |
Responses
Request samples
- Payload
{- "executeOnDemand": [
- "onDemandProperty1",
- "onDemandProperty2"
], - "dataset": {
- "linkingRelationships": [
- {
- "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2"
}
]
}, - "callback": {
- "method": "GET",
},
}
Response samples
- 202
- 4XX
- 5XX
{- "_links": {
- "self": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "jobTicket"
}, - "result": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "downloadLink"
}
}, - "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": [
- {
- "code": "50001",
- "name": "InternalServerError",
- "message": "There was an internal error. If the issue persists you should contact support@orgvue.com.",
- "errorContentType": "application/xml",
- "errorContent": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Error><Code>NoSuchKey</Code><Message>The resource you requested does not exist</Message><Resource>/mybucket/myfoto.jpg</Resource><RequestId>4442587FB7D0A2F9</RequestId></Error>"
}
]
}
Create links dataset
Creates a new links dataset resource.
Authorizations:
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 |
Request Body schema: application/json; charset=UTF-8required
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
- Payload
{- "name": "PEOPLE to ROLES Links Dataset",
- "fromDatasetId": "99CD8A1B-61A2-4768-87FA-3D10420FC535",
- "toDatasetId": "2B44BAD6-6680-4A19-A00C-0366832E2BD6",
- "additionalProperties": [
- {
- "0": {
- "key": "firstName",
- "name": "First Name",
- "type": "text"
}, - "1": {
- "key": "position_id",
- "name": "Position ID",
- "type": "text"
}, - "2": {
- "key": "position_title",
- "name": "Position Title",
- "type": "text"
}, - "3": {
- "key": "salary",
- "name": "Salary",
- "type": "number"
}
}
], - "tags": [
- "admin",
- "people",
- "roles"
]
}
Response samples
- 200
- 4XX
- 5XX
{- "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": [
- "admin",
- "people",
- "roles"
], - "properties": [
- {
- "key": "from_id",
- "name": "from_id",
- "type": "string",
- "isRequired": true
}, - {
- "key": "to_id",
- "name": "to_id",
- "type": "string",
- "isRequired": true
}, - {
- "key": "link_id",
- "name": "link_id",
- "type": "string",
- "isRequired": true
}, - {
- "key": "allocation",
- "name": "allocation",
- "type": "number",
- "isRequired": true
}
]
}
Update links dataset
Early access preview: 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:
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 |
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 |
Request Body schema: application/json; charset=UTF-8required
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
- Payload
{- "name": "PEOPLE to ROLES Links Dataset",
- "additionalProperties": [
- [
- {
- "key": "firstName",
- "name": "First Name",
- "type": "text"
}, - {
- "key": "position_id",
- "name": "Position ID",
- "type": "text"
}, - {
- "key": "position_title",
- "name": "Position Title",
- "type": "text"
}, - {
- "key": "salary",
- "name": "Salary",
- "type": "number"
}
]
], - "tags": [
- "people",
- "roles"
]
}
Response samples
- 200
- 4XX
- 5XX
{- "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": [
- "admin",
- "people",
- "roles"
], - "properties": [
- {
- "key": "from_id",
- "name": "from_id",
- "type": "string",
- "isRequired": true
}, - {
- "key": "to_id",
- "name": "to_id",
- "type": "string",
- "isRequired": true
}, - {
- "key": "link_id",
- "name": "link_id",
- "type": "string",
- "isRequired": true
}, - {
- "key": "allocation",
- "name": "allocation",
- "type": "number",
- "isRequired": true
}
]
}
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:
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 |
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 |
Request Body schema: application/json; charset=UTF-8
sourceDatasetId required | string The id of the source dataset that contains the |
targetDatasetAutoId required | string The property which holds the |
allocationId | string The property which holds the |
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 | |
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
- Payload
{- "sourceDatasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2",
- "targetDatasetAutoId": "positionsId",
- "allocationId": "fte",
- "callback": {
- "method": "GET",
}
}
Response samples
- 202
- 4XX
- 5XX
{- "_links": {
- "self": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "jobTicket"
}, - "result": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "downloadLink"
}
}, - "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": [
- {
- "code": "50001",
- "name": "InternalServerError",
- "message": "There was an internal error. If the issue persists you should contact support@orgvue.com.",
- "errorContentType": "application/xml",
- "errorContent": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Error><Code>NoSuchKey</Code><Message>The resource you requested does not exist</Message><Resource>/mybucket/myfoto.jpg</Resource><RequestId>4442587FB7D0A2F9</RequestId></Error>"
}
]
}
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:
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 |
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 |
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 |
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 |
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. |
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 |
Request Body schema: application/json; charset=UTF-8required
_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 |
Responses
Request samples
- Payload
[- {
- "_action": "create",
- "from_id": "p_01234",
- "to_id": "pos_a123",
- "allocation": 1
}, - {
- "_action": "update",
- "from_id": "p_01269",
- "to_id": "pos_a120",
- "allocation": 0.5
}, - {
- "_action": "createOrReplace",
- "from_id": "p_01270",
- "to_id": "pos_a191"
}
]
Response samples
- 200
- 4XX
- 5XX
[- {
- "_status": "success",
- "_id": "5C9EF1F8-0048-4CE9-91E7-789B857EE73C",
- "_action": "create",
- "link_id": "[\"p_01234\",\"pos_a123\"]"
}, - {
- "_status": "success",
- "_id": "7918D0B4-24AC-8A3E-E21C-1302FAE4937E",
- "_action": "update",
- "link_id": "[\"p_01269\",\"pos_a120\"]"
}, - {
- "_status": "success",
- "_id": "ECFB8805-002D-441C-92AE-39FFE9D88A20",
- "_action": "delete",
- "link_id": "[\"p_01270\",\"pos_a191\"]"
}
]
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:
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 |
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 |
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 |
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 |
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. |
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 |
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 |
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 | |
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
- Payload
{- "callback": {
- "method": "GET",
}
}
Response samples
- 202
- 4XX
- 5XX
{- "_links": {
- "self": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "jobTicket"
}, - "result": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "downloadLink"
}
}, - "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": [
- {
- "code": "50001",
- "name": "InternalServerError",
- "message": "There was an internal error. If the issue persists you should contact support@orgvue.com.",
- "errorContentType": "application/xml",
- "errorContent": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Error><Code>NoSuchKey</Code><Message>The resource you requested does not exist</Message><Resource>/mybucket/myfoto.jpg</Resource><RequestId>4442587FB7D0A2F9</RequestId></Error>"
}
]
}
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:
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 |
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 |
projection | object <{ [propertyKey]: 1 }> (itemsProjection) Property filtering using a projection object |
Responses
Request samples
- Payload
{- "filter": {
- "name": "John Smith"
}, - "projection": {
- "draftId": 1,
- "name": 1,
- "description": 1
}
}
Response samples
- 200
- 4XX
- 5XX
{- "draftId": "36A1E02D-DC20-61C5-A11F-DD85440C652C",
- "name": "Finance Scenario Model",
- "description": "A scenario of our future Finance organisation structure.",
- "createdBy": "user@example.com",
- "modifiedAt": "2020-05-29T09:43:03.953Z",
- "tags": [
- "Finance"
], - "_links": {
- "self": {
- "method": "GET",
- "type": "application/json; charset=UTF-8"
}, - "draft:actions": {
- "jsonBody": {
- "layers": [
- {
- "draftId": "36A1E02D-DC20-61C5-A11F-DD85440C652C",
- "layerKey": "default"
}
]
}, - "method": "POST",
- "type": "application/json; charset=UTF-8"
}
}
}
Draft metadata
Authorizations:
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 |
Responses
Response samples
- 200
- 4XX
- 5XX
{- "draftId": "36A1E02D-DC20-61C5-A11F-DD85440C652C",
- "name": "Finance Scenario Model",
- "description": "A scenario of our future Finance organisation structure.",
- "createdBy": "user@example.com",
- "modifiedAt": "2020-05-29T09:43:03.953Z",
- "tags": [
- "Finance"
], - "_links": {
- "self": {
- "method": "GET",
- "type": "application/json; charset=UTF-8"
}, - "draft:actions": {
- "jsonBody": {
- "layers": [
- {
- "draftId": "36A1E02D-DC20-61C5-A11F-DD85440C652C",
- "layerKey": "default"
}
]
}, - "method": "POST",
- "type": "application/json; charset=UTF-8"
}
}
}
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:
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 |
resultEncoding | string Enum: "gzip" "identity" Example: resultEncoding=gzip Determines whether the data written to the result location will be compressed using gzip. Defaults to |
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 |
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".
|
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 |
Responses
Request samples
- Payload
{- "layers": [
- {
- "draftId": "36A1E02D-DC20-61C5-A11F-DD85440C652C",
- "layerKey": "default"
}
], - "foldScheme": "distinct",
- "callback": {
- "method": "GET",
},
}
Response samples
- 202
- 4XX
- 5XX
{- "_links": {
- "self": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "jobTicket"
}, - "result": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "downloadLink"
}
}, - "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": [
- {
- "code": "50001",
- "name": "InternalServerError",
- "message": "There was an internal error. If the issue persists you should contact support@orgvue.com.",
- "errorContentType": "application/xml",
- "errorContent": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Error><Code>NoSuchKey</Code><Message>The resource you requested does not exist</Message><Resource>/mybucket/myfoto.jpg</Resource><RequestId>4442587FB7D0A2F9</RequestId></Error>"
}
]
}
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:
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 |
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
- Payload
{- "layers": [
- {
- "draftId": "331413BF-591C-031E-BAC4-D1C39AA28958",
- "layerKey": "default"
}, - {
- "draftId": "7918D0B4-24AC-8A3E-E21C-1302FAE4937E",
- "layerKey": "default"
}, - {
- "draftId": "ECFB8805-002D-441C-92AE-39FFE9D88A20",
- "layerKey": "default"
}
], - "filter": {
- "location": {
- "$in": [
- "UK",
- "USA"
]
}, - "approval_status": "Approved"
}
}
Response samples
- 200
- 4XX
- 5XX
[- {
- "status": "success",
- "draftId": "331413BF-591C-031E-BAC4-D1C39AA28958",
- "layerKey": "default"
}, - {
- "status": "success",
- "draftId": "7918D0B4-24AC-8A3E-E21C-1302FAE4937E",
- "layerKey": "default"
}, - {
- "status": "success",
- "draftId": "ECFB8805-002D-441C-92AE-39FFE9D88A20",
- "layerKey": "default"
}
]
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:
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 |
Request Body schema: application/json; charset=UTF-8required
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
- Payload
{- "targetType": "json",
- "targetEncoding": "identity"
}
Response samples
- 200
- 4XX
- 5XX
{
}
List webhooks
Early access preview: Retrieve webhook subscriptions registered in Orgvue
Authorizations:
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 |
Responses
Response samples
- 200
- 4XX
- 5XX
[- {
- "webhookId": "string",
- "modifiedAt": "2019-08-24T14:15:22Z",
- "url": "https://",
- "method": "GET",
- "eventType": "string",
- "status": "string"
}
]
Register new webhook
Early access preview: Register a new webhook subscription
Authorizations:
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 |
Request Body schema: application/json; charset=UTF-8
url required | string <url> URL where event information will be sent. |
method required | string Value: "GET" HTTP method to be used when sending event. |
eventType required | string type of the event to which you want to subscribe. Check Webhooks page for available values |
Responses
Request samples
- Payload
{- "url": "https://",
- "method": "GET",
- "eventType": "string"
}
Response samples
- 200
- 4XX
- 5XX
{- "webhookId": "string",
- "modifiedAt": "2019-08-24T14:15:22Z",
- "url": "https://",
- "method": "GET",
- "eventType": "string",
- "status": "string"
}
Update webhook
Early access preview: Update an existing webhook subscription
Authorizations:
path Parameters
tenantId required | string^[A-Z][A-Z0-9_]{0,29}$ Example: TENANT_ID Tenant identifier |
webhookId required | string <uuid> Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B Webhook 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 |
Request Body schema: application/json; charset=UTF-8
status | string status of subscription. Can be |
Responses
Request samples
- Payload
{- "status": "string"
}
Response samples
- 200
- 4XX
- 5XX
{- "webhookId": "string",
- "modifiedAt": "2019-08-24T14:15:22Z",
- "url": "https://",
- "method": "GET",
- "eventType": "string",
- "status": "string"
}
Delete webhook
Early access preview: Delete an existing webhook subscription
Authorizations:
path Parameters
tenantId required | string^[A-Z][A-Z0-9_]{0,29}$ Example: TENANT_ID Tenant identifier |
webhookId required | string <uuid> Example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B Webhook 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 |
Responses
Response samples
- 4XX
- 5XX
{- "errors": [
- {
- "code": "404013",
- "name": "WebhookNotFound",
- "message": "The webhook specified by the given webhook id was not found on the server. Please check that it exactly matches the value for your desired webhook."
}
]
}
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 |
{- "_links": {
- "self": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "jobTicket"
}, - "result": {
- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "downloadLink"
}
}, - "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": [
- {
- "code": "50001",
- "name": "InternalServerError",
- "message": "There was an internal error. If the issue persists you should contact support@orgvue.com.",
- "errorContentType": "application/xml",
- "errorContent": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Error><Code>NoSuchKey</Code><Message>The resource you requested does not exist</Message><Resource>/mybucket/myfoto.jpg</Resource><RequestId>4442587FB7D0A2F9</RequestId></Error>"
}
]
}
The self link to the jobTicket entity produced by the export API
url | string <url> |
contentType | string Value: "application/json; charset=UTF-8" |
type | string Value: "jobTicket" |
{- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "jobTicket"
}
The link to the dataset export location produced by the export API
url | string <url> |
contentType | string Enum: "application/json; charset=UTF-8" "text/csv; charset=UTF-8" "text/tab-separated-values; charset=UTF-8" |
type | string Enum: "downloadLink" "uploadLink" |
{- "url": "https://",
- "contentType": "application/json; charset=UTF-8",
- "type": "downloadLink"
}
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
|
{- "errors": [
- {
- "code": "400020",
- "name": "FieldMustNotBeMultivalued",
- "message": "You cannot specify this field multiple times.",
- "pathParameter": "{tenantId}",
- "queryParameter": "includeBOM",
- "jsonBody": "$.dataset.drafts[0].draftId",
- "resourcePath": "MY_TENANT/datasets/99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B"
}
]
}
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
|
{- "errors": [
- {
- "code": "50001",
- "name": "InternalServerError",
- "message": "There was an internal error. If the issue persists you should contact support@orgvue.com.",
- "errorContentType": "application/xml",
- "errorContent": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Error><Code>NoSuchKey</Code><Message>The resource you requested does not exist</Message><Resource>/mybucket/myfoto.jpg</Resource><RequestId>4442587FB7D0A2F9</RequestId></Error>"
}
]
}