Your First Export Call

A step-by-step process of how to perform your first API request.

If you haven't already: produce an API Token and find out the tenant and dataset you need as described in the previous section.

info

Note that all request headers are case sensitive.

i.e. Use "Content-Type" not "content-type" when making requests.

Integrating with Orgvue for the first time

Making a GET request

1. Add the Authorization and Content-Type headers to your request
   • Insert the API Token into the Authorization header of your request: Bearer apiToken.
   • Add the Content-Type header to your request and assign it a value of application/json; charset=UTF-8
2. Obtain the request URL by inserting your desired tenantId and datasetId into the endpoint path as described in the API Reference section: .
3. Send your request to the export endpoint that produces the response format of your choice. There are several supported data formats in which the response data can be formatted in. The "jsonRows" parameter used in the example request URL can be replaced with any of the following:
   • jsonRows
   • jsonColumns
   • csv
   • tsv
4. Assuming your request is valid and the data size is small enough to respond synchronously you will receive a response with a 200 code and the requested data will be available within the response body. The response should look similar to this:

   {
     "headers": [
       {
         "key": "id",
         "name": "Id",
         "type": "text"
       },
       {
         "key": "name",
         "name": "Name",
         "type": "text"
       },
       {
         "key": "parent_id",
         "name": "Parent Id",
         "type": "text"
       }
     ],
     "rows": [
       [
         "a",
         "Ana",
         null
       ],
       [
         "b",
         "Bob",
         "a"
       ]
     ]
   }

Making a POST request

1. Add the Authorization and Content-Type headers to your request
   • Insert the API Token into the Authorization header of your request: Bearer apiToken.
   • Add the Content-Type header to your request and assign it a value of application/json; charset=UTF-8
2. Obtain the request URL by inserting your desired tenantId and datasetId into the endpoint path as described in the API Reference section : .
3. Send your request to the export endpoint that produces the response format of your choice. There are several supported data formats in which the response data can be formatted in. The "jsonRows" parameter used in the example request URL can be replaced with any of the following:
   • jsonRows
   • jsonColumns
   • csv
   • tsv
4. Assuming your request is valid and taking into account the asynchronous nature of the API: the application/json response you receive will contain the location of your data in the $._links.self.url attribute. The response should look something like this:

   {
     "_links": {
       "self": {
         "url": "https://example.s3.eu-west-1.amazonaws.com/TENANT_ID-b4328c42-6a01-4699-88d5-64705ef2aa15?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA376FRB2V6BQHVR5A%2F20220320%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220320T232921Z&X-Amz-Expires=900&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEID%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCWV1LXdlc3QtMSJHMEUCIQCr0V6T2ahQ0K846OfycRZ98lfUcFCbscFMNjODbHiKQAIgZC8w4ps7FGS3Fxp1TfAU2lBFV2FOdqyWyFy6sMI9aJEqsAII%2Bf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARACGgw4MjQ1MTExMDY3MzEiDP8rObI2MnV9CBV1ICqEApDDLTzrCTQfvriW5nz7W%2FliscXCVD0S8uT8c1FfLZUlAnQDmSI3uARf6X1W6Yrpf7IGdJhRIpjqn2wEqmfnwGPH5VCUaLnVI4Zjcp6txdIDqxNqBCMJpJ%2B1mHPLPJ9A42xtqQGxrejP7Vyn23q4tBQryJ0eMDz0zDgyE9TmxoOy3R20ZD1TlvC9uPsiqET2PVM0YxIqcVM75%2F%2BcR%2By1S15dcCb8gYAqgW55BuYhkCxDZqXyYdi2BydLx9IjRSddwnoatMMI03awSMLb5b%2FY4%2Bqe0uFrnBCpqEkuvcgExsXW%2BKs%2B3I%2B3pfKn9CYquB7R2qO4YNGzdkzSkDS3WY0Rj4tbsfivMObv3pEGOpoBnWU%2FTzfbLK67uXYZ9ysbvXZNg7sGG%2FFkilY8CJfgDWo2YswCYr%2BWHowRmJLB8T7rYXh7aMGThjeqPWs0yoZQzzO8rxOJqMAfewl2Mtv4shhLEEyfDJNLiZb8xwdifrtMy%2B9DGIMu5MOa0xS41G7h8%2BnI8TCYMpC5AM0KOsLYknuE4hpc%2BQR1kSthROZzUfszpcXZtyPVCpOfNQ%3D%3D&X-Amz-SignedHeaders=host&X-Amz-Signature=25cb364f3bd7100d0d17a02224b09a9124494639490793d43787226bdb4be6bb",
         "contentType": "application/json; charset=UTF-8",
         "type": "jobTicket"
       }
     },
     "jobStatus": "created",
     "_createdAt": "2022-03-20T17:53:23.282Z",
     "_createdBy": "joe.bloggs@orgvue.com",
     "X-Amzn-Trace-Id": "Root=1-62bcb5d3-3b211f8616879dea3bde593f"
   }
5. Poll the $._links.self.url location until the job status changes from "running" to "completed".
6. Perform a GET request to the location where your data have been stored, under $._links.result.url terms)

Any issues with the inputs you provide will end up in an error. Handling these errors is covered in a separate section.

info

We use the latest and greatest technologies to bring value to the users of our APIs. In a trade-off for desirable features, a current limitation of our chosen design is that a subset of our errors return a 401 HTTP Status code, where a different status might be expected according to strict REST client error definitions.

We are committed to correcting this at the earliest opportunity.

Example tools for working with our API

• curl
• Postman