REST API

The TIVITY API supports processing of instances and documents outside the platform. List ID can be a class ID or query ID. REST API

Base URL (placeholder) Use the following placeholder in all examples:

https://{host}/api/v1

---

Instances

Summary

Method name	HTTP method	URL
Create	POST	/instance/{workspaceId}/{appId}/{listId}
ReadAll	GET	/instance/{workspaceId}/{appId}/{listId}
ReadOne	GET	/instance/{workspaceId}/{appId}/{listId}/{instanceId}
Update	PUT	/instance/{workspaceId}/{appId}/{listId}/{instanceId}
Delete	POST	/instance/{workspaceId}/{appId}/{listId}/{instanceId}

---

Create

POST https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId} REST API

Creates a new instance in the specified list.

Headers

• Authorization: Bearer token REST API

Request Body (example) REST API

{
  "instance": {
    "fields": {
      "{FieldKey1}": "{FieldValue1}",
      "{FieldKey2}": "{FieldValue2}",
      "{FieldKey3}": "{FieldValue3}"
    }
  }
}

---

ReadAll

GET https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId} REST API

Reads all instances of the specified list.

Headers

• Authorization: Bearer token REST API

Response (example) REST API

{
  "cursor": 1,
  "lastPage": false,
  "pageInfo": "PD94bWwgdmVyc2...RGF0YT4=",
  "instances": [
    {
      "id": "/instance/{workspaceId}/{appId}/{listId}/{instanceId}",
      "fields": {
        "{FieldKey1}": "{FieldValue1}"
      }
    }
  ]
}

---

ReadOne

GET https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId}/{instanceId} REST API

Reads one instance of the specified list.

Headers

• Authorization: Bearer token REST API

Response (example)

{
  "instance": {
    "id": "/instance/{workspaceId}/{appId}/{listId}/{instanceId}",
    "fields": {
      "{FieldKey1}": "{FieldValue1}",
      "{FieldKey2}": "{FieldValue2}",
      "{FieldKey3}": "{FieldValue3}"
    }
  }
}

---

Update

PUT https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId}/{instanceId}

Updates an existing instance of the specified list.

Headers

• Authorization: Bearer token

Response (example)

Comma-separated fields list, returns all if left empty.

{
  "instance": {
    "id": "/instance/{workspaceId}/{appId}/{listId}/{instanceId}",
    "fields": {
      "{FieldKey1}": "{FieldValue1}",
      "{FieldKey2}": "{FieldValue2}",
      "{FieldKey3}": "{FieldValue3}"
    }
  }
}

Optionally documents from the DocumentStore (see Upload call) can be inserted. But this works only for document classes with the 'Upload' action.

{ 
   "instance": { 
      "fields": { 
         "{FieldKey1}": “{FieldValue1}”,
         "{FieldKey2}": “{FieldValue2}”, 
         "{FieldKey3}": “{FieldValue3}”,
          "File": { 
              "Id": "8172f7aa...", 
              "Name": "test-123-9.pdf",              
              "MimeType": "application/pdf"
          } 
      } 
   } 
}

---

Delete

POST https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId}/{instanceId}

Deletes an existing instance of the specified list. REST API

---

Documents

Download

GET https://{host}/api/v1/document/{workspaceId}/{appId}/{listId}/{instanceId} REST API

Downloads a document of an instance. REST API

Headers

• Authorization: Bearer token REST API

Request Body (example) REST API

{
  "type": "Preview"
}

Possible values for type: Document, Thumbnail, Preview. REST API

---

Upload

POST https://{host}/api/v1/document REST API

Uploads a temporary document for later use. The returned document ID can be used for document files. REST API

Headers

• Authorization: Bearer token REST API

Request Body

• File as a byte stream. REST API

Response (example) REST API

{
  "documentId": "c626d133-047c-494a-a0d7-775b1b40db7a"
}

---

Workflow Execution

The API supports executing workflows on a class/list or on a specific instance. Workflows can be started and continued by passing back the state from an Input response.

Note: the OpenAPI specification uses {teamId} in the path, but this documentation refers to the same identifier as Workspace ID. Workflow-OpenAPI

---

Endpoints

Execute Class Workflow

POST https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId}/workflow/{workflowId} Workflow-OpenAPI

Executes a class workflow of the specified list. Workflow-OpenAPI

---

Execute Instance Workflow

POST https://{host}/api/v1/instance/{workspaceId}/{appId}/{listId}/{instanceId}/workflow/{workflowId} Workflow-OpenAPI

Executes an instance workflow for the specified instance. Workflow-OpenAPI

---

Request Body

The request body is a WorkflowRequest. Workflow-OpenAPI

state (optional) Only set when continuing a workflow execution. The value must be taken from the state returned in a previous Input response. Workflow-OpenAPI

parameters (optional) Parameters to be sent to the workflow execution. Parameters may be sent without the execution explicitly requesting them. Workflow-OpenAPI

Example (start a workflow)

{
  "parameters": {
    "StartParameter": "This is a test"
  }
}

Example (continue a workflow)

{
  "state": "{state-from-previous-input-response}",
  "parameters": {
    "Parameter1": "Value1"
  }
}

---

Response Body

The response body is a WorkflowResponse. Workflow-OpenAPI

kind (required) One of: Value, Input, Error. Workflow-OpenAPI

state (only when kind = Input) The state that must be passed into the next request to continue the workflow. Workflow-OpenAPI

value (only when kind = Value) The success result of the workflow execution. Workflow-OpenAPI

input.parameters (only when kind = Input) List of requested parameters (each contains a key). Workflow-OpenAPI

error (only when kind = Error) Failure result as a string. Workflow-OpenAPI

---

Workflow Response Examples

Value (success)

{
  "kind": "Value",
  "value": {
    "result": "OK"
  }
}

value contains the return value of a value and can be any of the supported types:

{
  "kind": "Value",
  "value": 1234
}

---

Input (pending – more parameters required)

{
  "kind": "Input",
  "state": "{state-to-continue}",
  "input": {
    "parameters": [
      { "key": "DocumentParameter" }
    ]
  }
}

---

Error (failure)

{
  "kind": "Error",
  "error": "Errors occurred when mapping workflow parameter values."
}

---

Supported Parameter and Value Types

Workflow parameters and values support the following types:

Boolean, Byte, DateTime, Double, Document, Float, Guid, Integer, List, Long, Object, Numeric, Short, String, Table.

---

Status Codes and Validation Rules

• 400 – Returned when request parameters are invalid.

• 401 – Returned when the workspace, app, class/list, instance, or workflow cannot be accessed.

• 404 – Returned when the workspace, app, class/list, instance, or workflow cannot be found.

Additional workflow execution rules:

• When the workflow requests additional parameters, an Input response is returned.

• When workflow parameters are unsupported or invalid, an Error response is returned.

• When an unsupported value is returned by the workflow, an Error response is returned.

• When any execution error occurs during workflow processing, an Error response is returned.