Documentation of the Twona API v2.

Index

• Organization Management
  • Short Description
  • Authentication
  • Login
  • Workflows
• User Management
  • User management
  • Group management
• Requests and Versions
  • Requests Data
  • Versions Data
• File Management
  • Files
• Filtering and Ordering
  • Search queries

Short Description

The Twona API allows you manage many aspects of your Organization, from user and group management, data related to requests and file management.

Authentication

Authentication is done with an API token that is sent in the header of each HTTP request under Access-token. The token is assigned per user and inherits all permissions of the user. A token can be obtained directly on Twona under Settings>APITokens.

If a token is invalid, Twona will issue a 401 Unauthorized response.

Terminology

Organization

Organization: An Organization is used to aggregate all aspects of your account. The name of the Organization will typically the name of your company :-)

organization object

Get a Token data (testing the API)

You can test the connectivity with Twona by requesting a session call which will return the user and organization data.

Request

Resource

Inputs

Empty

Response

Content

A user object and a organization object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/session \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

{
                            "user": {
                                "date_created": "2019-02-19T09:09:23+00:00",
                                "email": "user@mail.com",
                                "id": "iDCHaRs",
                                "name": "User example name",
                                "position": "User position"
                            },
                            "organization": {
                                "id": 123122137,
                                "name": "Test organization"
                            }
                        }

Working with files

• Terminology

• Get a file (GET)

• Download a file (GET)

• Add metadata to File (PUT)

• Get all organization’s files (GET)

• Uploading files

  • Request upload a file (POST)
  • Uploading content (PATCH)
  • Check upload (HEAD)

Terminology

Files

File: One file object is a file uploaded to the system by a user with more information about it. This file object is temporal until it’s used in some process or some attribute is updated. The file object has a structure described in the particular request.

file object

Get a file

Obtain details of a specific file.

Request

Resource

Response

Content

A file object.

Codes

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/files/{FILE_ID} \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

{
                            "date":"2019-0702T12:24:59+0200",
                            "extension":"png",
                            "id":"e40ed4433ba4",
                            "filesize":"2.96MB",
                            "name":"imagen.png",
                            "size":3108445
                        }

Download a file

Download a specific file.

Request

Resource

Headers

Response

Codes

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/files/{FILE_ID} \
                          -H 'access-token: {ACCESS_TOKEN}'
                          -H 'Content-Type: application/offset+octet-stream' \

Add metadata to File

Add custom metadata to a specific file. When metadata is added to a file, the file becomes a persistent file and is no longer a temporal file. If the file was temporal, a new reference to the persistent file is returned.

Request

Resource

Inputs

Response

Content

A file object.

Code

Examples

Request

curl \
                          https://{BASE_URL}/api/v2/files \
                          -H 'access-token: {ACCESS_TOKEN}' \
                          -d '{"metadata":{"key":"value","key2":"value2"}}'

Response

If the file id is a temporal file, the response will redirect to the new file. If the file id is a persisted file, the response will be a file Object

Get all files

Return all the files from the organization.

Request

Resource

Inputs

Filtering list

You can filter the result set by establishing filters based on the metadata fields using the query method ‘q=field:data’.

Response

Content

A collection of file object

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/files \
                          -H 'access-token: {ACCESS_TOKEN}'

# Filtering: All files with a field called owner start with "diego"

                        curl -G \
                          https://{BASE_URL}/api/v2/files \
                          -H 'access-token: {ACCESS_TOKEN}'
                          --data-urlencode 'q=owner:diego*'

Response

[
                            {
                                "active": true,
                                 "date": "2019-10-30T10:02:43+00:00",
                                 "extension": "pdf",
                                 "filesize": "18.65kB",
                                 "id": 267719,
                                 "mimetype": "application/pdf",
                                 "name": "ref.pdf",
                                 "size": 19100,
                                 "metadata": {
                                     "updated": 20191108,
                                     "owner": "diego",
                                     "tag": "test"
                                 }
                            },
                            {
                                "active": true,
                                 "date": "2019-10-30T10:02:43+00:00",
                                 "extension": "pdf",
                                 "filesize": "18.65kB",
                                 "id": 267719,
                                 "mimetype": "application/pdf",
                                 "name": "ref.pdf",
                                 "size": 19100,
                                 "metadata": {
                                     "updated": 20191011,
                                     "owner": "diego",
                                     "tag": "test2"
                                 }
                            }
                        ]

Uploading files

Twona uses the TUS Open Protocol 1.0.0 to upload files. This protocol provides a mechanism for resumable file uploads via HTTP/1.1 (RFC 7230) and HTTP/2 (RFC 7540).

Files can be chunked in parts. The minimum upload part size is 5MB (except the last part). The maximum upload part size is 10MB.

Requesting an upload resource

Files can be uploaded via an upload resource. The first step is to request one.

Request

Resource

Inputs

Headers

Body

Empty.

Response

Outputs

Headers

Body

Empty.

Code

Examples

Request

curl -v \
                          -X POST \
                          https://{BASE_URL}/api/v2/files \
                          -H 'access-token: {ACCESS_TOKEN}' \
                          -H 'Upload-Length: 100'
                          -H 'Upload-Metadata: filename ZmlsZS5kb2M=,filetype YXBwbGljYXRpb24vbXN3b3Jk'

Response

< HTTP/1.1 201 Created
                        < Tus-Resumable: 1.0.0
                        < location: https://{BASE_URL}/api/v2/files/i6l028r76jsj
                        < Upload-Expires: Wed, 06 Nov 2019 14:24:45 GMT
                        ...

Uploading content

Once an upload URL resource is obtained, files can be uploaded. Files are uploaded using a PATCH request and they MUST use Content-Type: application/offset+octet-stream. If the file is larger than the maximum part size, you need to chunk the file in parts. The minimum part size is 5MB (except the last part). The maximum upload part size is 10MB.

Request

Resource

Inputs

Headers

Body

File content.

Response

Outputs

Headers

Body

Empty.

Code

Examples

Request

curl -v \
                          -X PATCH \
                          https://{BASE_URL}/api/v2/files/i6l028r76jsj \
                          -H 'access-token: {ACCESS_TOKEN}' \
                          -H 'Upload-Offset: 0' \
                          -H 'Content-Length: 30' \
                          -H 'Content-Type: application/offset+octet-stream' \
                          --data-binary @{/path/of/file}

Response

< HTTP/1.1 204 No content
                        < Tus-Resumable: 1.0.0
                        < Upload-Offset: 30
                        < Twona-File-Id: i6l028r76jsj
                        < Upload-Expires: Wed, 06 Nov 2019 14:24:45 GMT
                        ...

Check upload

Check the state of an upload.

Request

Resource

Inputs

Headers

None.

Body

Empty.

Response

Outputs

Headers

Body

Empty.

Code

Examples

Request

curl -v \
                          -X HEAD \
                          https://{BASE_URL}/api/v2/files/i6l028r76jsj \
                          -H 'access-token: {ACCESS_TOKEN}' \

Response

< HTTP/1.1 200 OK
                        < Upload-Length: 100
                        < Upload-Offset: 30
                        < Twona-File-Id: i6l028r76jsj

Working with groups

• Add group (POST)
• Get one group (GET)
• Get all groups (GET)
• Update one group (PUT)
• Deactivate one group (DELETE)
• Activate one group (POST)
• Get users in group (GET)
• Add one user to group (POST)
• Deactivate one user in group (DELETE)

Terminology

Groups

Group: Groups are a way to organise users based on specific permissions or automation sets (also called conditions). They are virtual construct and do not impose any hard constrains on the limitations of access of a user unless the corresponding conditions are set.

Each group has a unique id and name.

group object

Add group

Create a new group.

Request

Resource

Inputs

Response

Content

A group object.

Code

Examples

Request

curl -X POST \
                          https://{BASE_URL}/api/v2/groups \
                          -H 'access-token: {ACCESS_TOKEN}' \
                          -d '{"name": "new group's name"}'

Response

{
                            "active": true,
                            "date_created": "2019-07-01T11:47:04+00:00",
                            "date_updated": "2019-07-01T11:47:04+00:00",
                            "id": 160,
                            "name": "new group's name"
                        }

Get one group

Get the information of a specific group.

Request

Resource

Response

Content

A group object.

Codes

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/groups/{GROUP_ID} \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

{
                            "active": true,
                            "date_created": "2019-07-01T11:43:04+00:00",
                            "date_updated": "2019-07-01T11:43:04+00:00",
                            "id": 111,
                            "name": "Main group"
                        }

Get all groups

Return a collection of all active/inactive groups.

Request

Resource

Response

Content

A collection of group object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/groups \
                          -H 'access-token: {ACCESS_TOKEN}'

                        curl -X GET \
                            https://{BASE_URL}/api/v2/groups?deleted=true \
                            -H 'access-token: {ACCESS_TOKEN}'

Response

[
                            {
                                "active": true,
                                "date_created": "2019-07-01T11:47:04+00:00",
                                "date_updated": "2019-07-01T11:47:04+00:00",
                                "id": 111,
                                "name": "Main group"
                            },
                            {
                                "active": true,
                                "date_created": "2019-07-01T11:47:04+00:00",
                                "date_updated": "2019-07-01T11:47:04+00:00",
                                "id": 160,
                                "name": "new group's name"
                            }
                        ]

Update one group

Update the data of a specific group.

Request

Resource

Inputs

Response

Content

The updated group object.

Code

Examples

Request

curl -X PUT \
                          https://{BASE_URL}/api/v2/groups/{GROUP_ID} \
                          -H 'access-token: {ACCESS_TOKEN}'
                          -d '{ "name": "New name",
                                "active": false }'

Response

{
                            "active": false,
                            "date_created": "2019-07-01T11:47:04+00:00",
                            "date_updated": "2019-07-01T11:47:04+00:00",
                            "id": 160,
                            "name": "New name"
                        }

Deactivate one group

Deactivate a specific group. The users in this group will still be active but all conditions associated with the group will stop executing. Users cannot be added to a deactivated group.

Request

Resource

Response

Content

Empty

Code

Examples

Request

curl -X DELETE \
                          https://{BASE_URL}/api/v2/groups/{GROUP_ID} \
                          -H 'access-token: {ACCESS_TOKEN}'

Activate one group

Activate a specific group. Users can be added to an active group.

Request

Resource

Inputs

Response

Content

A group object.

Code

Examples

Request

curl -X POST \
                          https://{BASE_URL}/api/v2/groups \
                          -H 'access-token: {ACCESS_TOKEN}' \
                          -d '{"id": 160}'

Response

{
                            "active": true,
                            "date_created": "2019-07-01T12:47:10+00:00",
                            "date_updated": "2019-07-02T08:22:49+00:00",
                            "id": 158,
                            "name": "test July updated new"
                        }

Get users in group

Return the collection of users in a specific group.

Request

Resource

Response

Content

A collection of user object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/groups/{GROUP_ID}/users \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

[
                            {
                              "date_created": "2019-07-01T10:04:33+00:00",
                              "email": "mail1@twonas.com",
                              "id": "vfCswDrcRsaCP",
                              "name": "Mail 1 Name",
                              "position": null
                            },
                            {
                              "date_created": "2018-07-18T16:16:50+00:00",
                              "email": "mail2@twonas.com",
                              "id": "sjXaodaEwzdf",
                              "name": "Mail2 Name",
                              "position": null
                            }
                        ]

Add one user to group

Add one user in a specific group.

Request

Resource

Inputs

Response

Content

A user object.

Code

Examples

Request

curl -X POST \
                          https://{BASE_URL}/api/v2/groups/{GROUP_ID}/users \
                          -H 'access-token: {ACCESS_TOKEN}' \
                          -d '{"id": "iDCHaRs"}'

Response

{
                            "date_created": "2019-06-20T10:37:21+00:00",
                            "email": "user@mail.com",
                            "id": "iDCHaRs",
                            "name": "User name",
                            "position": "User position"
                        }

Deactivate one user in group

Dactivate one user in a specific group. The user will no longer be part of set of active users in a group.

Request

Resource

Response

Content

Empty

Code

Examples

Request

curl -X DELETE \
                          https://{BASE_URL}/api/v2/groups/{GROUP_ID}/users/{USER_ID} \
                          -H 'access-token: {ACCESS_TOKEN}'

Auto-key for Login

Auto-key is a method based on a “magic link” that allows to log a user without password. This is the prefered method for integrating within a third party application so that user control is made through the API and transparent for the users.

You need additional permissions for this feature. If you you obtain an error when making this API calls, please contact our customer support.

Request a magic link

Request a link to log in a specific user.

Twona will return an Autokey to which you can append the access URL with an href query and encoding for url urlencode the section you want the user to access.

An example in PHP:

$urlToApp = $autologin."?href=".urlencode("https://app.twonas.com/app/p/apollo/upload?reference=".$referenceId."&target=".$targetId);

Request

Resource

Inputs

Response

Response headers

Body content

Empty.

Code

Examples

Request

curl -X POST \
                          https://{BASE_URL}/api/v2/login/auto-key \
                          -H 'access-token: {ACCESS_TOKEN}' \
                          -d '{"email":"user@twonas.com"}'

Response

< HTTP/1.1 204 No Content
                        < Location: https://{URL_BASE}/login/auto-key/{HASH}/{CHECKSUM}

Working with Requests

• Terminology
• Get one Request (GET))
• Get files from a Request (GET)
• Get all requests (GET)
• Get all Status (GET)

Terminology

Request

Request: A Request is used to group, track and aggregate the process of creating assets (or artworks). A request will follow the steps defined in a workflow and will link together Versions, Attachments, Messages, Approvals and anything else related to a specific project.

request object

Status

Status: The Status represents the current state of the request within the assigned workflow.

status object

Get a Request

Get the information of a specific request.

Request

Resource

Inputs

Empty.

Response

Content

A request object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/requests/{REQUEST_ID} \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

{
                            "id": 80001,
                            "labels": [
                                {
                                    "id": 33001,
                                    "group": {
                                        "color": "#E85637",
                                        "id": 49,
                                        "name": "Group 1"
                                    },
                                    "name": "Label 1"
                                },
                                {
                                    "id": 33022,
                                    "group": {
                                        "color": "#63B7AD",
                                        "id": 59,
                                        "name": "Group 2"
                                    },
                                    "name": "Label 2"
                                }
                            ],
                            "labels_text": "Label 1, Label 2",
                            "info": "Hi,<br><p>Please find attached pdf file annotated.</p><br><p>Thank you</p><p>Best regards</p><p>Charles</p>",
                            "date_created": "2021-02-09T17:27:36+00:00",
                            "date_updated": "2021-02-10T09:09:23+00:00",
                            "priority": 80746.00001,
                            "status": {
                                "color": "#63B7AD",
                                "id": 798,
                                "name": "Finished"
                            },
                            "user_owner": {
                                "date_created": "2019-02-19T09:09:23+00:00",
                                "email": "user@mail.com",
                                "id": "iDCHaRs",
                                "name": "User example name",
                                "position": "User position"
                            },
                        
                        }

Get files (attachments)

Return a list of all active files (attachments) in a request.

Request

Resource

Inputs

Empty

Response

Content

A collection of files object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/requests/{REQUEST_ID}/files \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

[
                            {
                                "active": true,
                                "date": "2021-02-09T17:27:36+00:00",
                                "extension": "pdf",
                                "filesize": "274.59kB",
                                "id": 1844020,
                                "mimetype": "application/pdf",
                                "name": "file1.pdf",
                                "size": 281183,
                                "metadata": []
                            },
                            {
                                "active": true,
                                "date": "2021-02-09T17:27:36+00:00",
                                "extension": "pdf",
                                "filesize": "154.56kB",
                                "id": 1844020,
                                "mimetype": "application/pdf",
                                "name": "file2.pdf",
                                "size": 154560,
                                "metadata": []
                            }
                        ]

Get all Requests

Return the list of all requests in the organization.

Request

Resource

Inputs

Filtering list

To filter the list of requests, you can add a conditional query q as field:query (#search-queries).

Allowed filters:

To order the list of requests, you can add a short query short_by as field1,field2 (#search-queries).

Order fields:

Response

Content

A collection of request objects.

Code

Examples

Request

# Get requests from the workflow 31 order by id desc
                        curl -X GET \
                          https://{BASE_URL}/api/v2/requests \
                          -H 'access-token: {ACCESS_TOKEN}' \
                          --data-urlencode 'q=workflow:31' \
                          --data-urlencode 'sort_by=-id'

Response

[
                           {
                              "id":80745,
                              "labels":[
                                 {
                                    "id":169,
                                    "group":{
                                       "color":"#E85637",
                                       "id":49,
                                       "name":"Manufacturer"
                                    },
                                    "name":"Label 169"
                                 },
                                 {
                                    "id":212,
                                    "group":{
                                       "color":"#63B7AD",
                                       "id":59,
                                       "name":"Dose"
                                    },
                                    "name":"Label 212"
                                 }
                              ],
                              "labels_text":"Label 169, Label 212",
                              "info":"",
                              "date_created":"2021-02-09T17:27:36+00:00",
                              "date_updated":"2021-02-10T09:09:23+00:00",
                              "priority":80746.00001,
                              "status":{
                                 "color":"#63B7AD",
                                 "id":571,
                                 "name":"Finished"
                              },
                              "user_owner": {
                                  "date_created": "2019-02-19T09:09:23+00:00",
                                  "email": "user@mail.com",
                                  "id": "iDCHaRs",
                                  "name": "User example name",
                                  "position": "User position"
                              },
                           },
                           {
                              "id":80732,
                              "labels":[
                                 {
                                    "id":928,
                                    "group":{
                                       "color":"#E85637",
                                       "id":94,
                                       "name":"Manufacturer"
                                    },
                                    "name":"Label 928"
                                 },
                                 {
                                    "id":78,
                                    "group":{
                                       "color":"#EAC739",
                                       "id":98,
                                       "name":"Presentation"
                                    },
                                    "name":"Label 78"
                                }
                              ],
                              "labels_text":"Label 928, Label 78",
                              "info":"",
                              "date_created":"2021-02-09T14:17:29+00:00",
                              "date_updated":"2021-02-10T11:12:37+00:00",
                              "priority":80746.000005,
                              "status":{
                                 "color":"#E1AB32",
                                 "id":542,
                                 "name":"Checking"
                              },
                              "user_owner": {
                                  "date_created": "2019-02-19T09:09:23+00:00",
                                  "email": "user@mail.com",
                                  "id": "iDCHaRs",
                                  "name": "User example name",
                                  "position": "User position"
                              }
                           }
                        ]

Get all status

Return the list of all request status in the organization.

Request

Resource

Inputs

Response

Content

A collection of status object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/requests/status \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

[
                            {
                                "color": "#97CBC0",
                                "id": 371,
                                "name": "Received"
                            },
                            {
                               "color":"#E1AB32",
                               "id":542,
                               "name":"Checking"
                            },
                            {
                               "color":"#63B7AD",
                               "id":571,
                               "name":"Finished"
                            }
                        ]

Search and Sort Queries

In some cases you can filter and sort the results of a returned list using query strings. Results can also be returned with page.

Syntax

A filter/sort query is composed of three parts: the query q to filter (search) the result set, the sort short_by to arrange the order, and the page page to navigate the pages of results. You can add more than one filter/short term. Spaces are not allowd in the final query string.

q=field1:term1+field2:term2+field3:term3&sort_by=field1,-field2&page=2 // + -> is a condition

IMPORTANT: the string needs to be encoded before it is added to the url.

Filter field

You can establish filter (search) queries using: q=[conditions]. Individual consitions consist of the form field=term and can be concatenated by using AND, AND NOT and OR statements as follows:

Modifiers

You can use modifiers to expand the filter (search) criteria as follows:

IMPORTANT: query field is mandatory.

Sort field

You can sort the result set by using: sort_by=[field1,field2]

By default the order is ASC. You can use - to specify the order DESC before the field as in the example below.

q=...&sort_by=field1,-field2...

Page field

Results can be returned by pages using page=[int] as follows:

q=...&sort_by=...&page=2

Search Examples

A table like:

Example 1

Where the email is equal to diego@twonas.com.

Example 2

Where the email field ends with twonas.com.

Example 3

Where the email field ends with twonas.com and starts with diego.

Example 4

Where the email field ends with twonas.com and starts with diego, or the email field starts with seva.

Example 5

Where the email field starts with seva and not ends with twonas.com.

Example 6

Where the email field starts with seva and not ends with twonas.com, or the email field starts with diego.

Working with users

• Terminology
• Invite a new user (POST)
• Get all invitations (GET)
• Cancel an invitation (DELETE)
• Get all users (GET)
• Get one user (GET)
• Update one user (PUT)
• Deactivate one user (DELETE)
• Activate one user (POST)
• Add users bulk (POST)

Terminology

Invitation

Invitation: an invitation is the process of providing access to a new user via his own email to a specific organization.

invitation object

User

User: one user is a single point of access associated to a unique email address. Each user has its own identifier, email and name among other data. The user object has a structure described in the particular request.

user object

Invite a new user

This call will send an invitation to the user’s email address provided in the parameter’s set. Once the link in the email has been clicked, the user will be added to the provided user’s group.

Request

Resource

Inputs

Response

Content

Empty

Code

Examples

Request

curl -X POST \
                          https://{BASE_URL}/api/v2/users/invitations \
                          -H 'access-token: {ACCESS_TOKEN}'
                          -d '{ "name": "User's name",
                                "email": "example@twonas.com",
                                "groups": [12,14],
                                "message": "Wellcome!" }'

Get all invitations

Return the list of all pending or expired invitations.

Request

Resource

Inputs

Empty

Response

Content

A collection of invitation object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/users/invitations \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

[
                            {
                                "date": "2019-06-28T10:27:21+0200",
                                "email": "test1@twonas.com",
                                "hash": "98dadeas37faa5",
                                "name": "test1 name",
                                "organization_id": 1,
                                "status_code": 2,
                                "status_text": "Expired",
                                "users_group_id": 12
                            },
                            {
                                "date": "2019-06-18T09:48:33+0200",
                                "email": "test2@twonas.com",
                                "hash": "f7c92315b32e",
                                "name": "test2 name",
                                "organization_id": 1,
                                "status_code": 2,
                                "status_text": "Expired",
                                "users_group_id": 12
                            }
                        ]

Cancel an invitation

Cancel a “Pending” invitation. Expired or accepted invitations cannot be canceled.

Request

Resource

Inputs

Empty

Response

Content

Empty

Code

Examples

Request

curl -X DELETE \
                          https://{BASE_URL}/api/v2/users/invitations/example@twonas.com \
                          -H 'access-token: {ACCESS_TOKEN}'

Get all users

Return the list of all active/inactive users in the organization.

Request

Resource

Inputs

Filtering list

To filter the list of users, you can add a conditional query q as field:query (details).

Allowed filters:

Response

Content

A collection of user object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/users \
                          -H 'access-token: {ACCESS_TOKEN}'

                        curl -X GET \
                            https://{BASE_URL}/api/v2/users?deleted=true \
                            -H 'access-token: {ACCESS_TOKEN}'

Filtering: All users with email starting with “diego”

curl -G \
                          https://{BASE_URL}/api/v2/users \
                          -H 'access-token: {ACCESS_TOKEN}'
                          --data-urlencode 'q=email:diego*'

Response

[
                            {
                              "date_created": "2019-07-01T10:04:33+00:00",
                              "email": "mail1@twonas.com",
                              "id": "vfCssaCP",
                              "name": "Mail 1 Name",
                              "position": null
                            },
                            {
                              "date_created": "2018-07-18T16:16:50+00:00",
                              "email": "mail2@twonas.com",
                              "id": "sjXaozdf",
                              "name": "Mail2 Name",
                              "position": null
                            }
                        ]

Get one user

Return the details of a specific user (by its unique user id)

Request

Resource

Inputs

Empty

Response

Content

A user object.

Codes

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/users/{USER_ID} \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

{
                            "date_created": "2019-06-20T10:37:21+00:00",
                            "email": "user@mail.com",
                            "id": "iDCHaRs",
                            "name": "New user's name",
                            "position": "User position"
                        }

Update one user

Update the personal data of a specific user (by its unique user id)

Request

Resource

Inputs

Response

Content

The updated user object.

Code

Example

Request

curl -X PUT \
                          https://{BASE_URL}/api/v2/users/{USER_ID} \
                          -H 'access-token: {ACCESS_TOKEN}'
                          -d '{ "name": "New user's name",
                                "telephone": "+34000000000",
                                "position": "User position" }'

Response

{
                            "date_created": "2019-06-20T10:37:21+00:00",
                            "email": "user@mail.com",
                            "id": "iDCHaRs",
                            "name": "New user's name",
                            "position": "User position"
                        }

Deactivate one user

Deactivate (make inactive) a specific a specific user (by its unique user id). Once a user is deactivated, he will no longer be able to log in.

Resource

Request

Inputs

Empty

Response

Content

Empty

Codes

Examples

Request

curl -X DELETE \
                          https://{BASE_URL}/api/v2/users/{USER_ID} \
                          -H 'access-token: {ACCESS_TOKEN}'

Activate one user

Activate (make active) a specific a specific user (by its unique user id). Once a user is activated, he will be able to log in.

Request

Resource

Inputs

Response

Content

The updated user object.

Codes

Examples

Request

curl -X POST \
                          https://{BASE_URL}/api/v2/users \
                          -H 'access-token: {ACCESS_TOKEN}'
                          -d '{ "id": "iDCHaRs" }'

Response

{
                            "date_created": "2019-06-20T10:37:21+00:00",
                            "email": "user@mail.com",
                            "id": "iDCHaRs",
                            "name": "user's name",
                            "position": "User position"
                        }

Add users in bulk

Add users in bulk by WITHOUT email confirmation. Users will be added (and made active) without confirmation of the email address. A maximum of 100 users can be added per request.

Request

Resource

Inputs

Response

Content

A collection of user object with the successfully added users.

Codes

Examples

Request

curl -X POST \
                          https://{BASE_URL}/api/v2/users/bulk \
                          -H 'access-token: {ACCESS_TOKEN}'
                          -d '{ "emails": ["newUserMail@yourDomain.com","anotherUserMail@yourDomain.com",...],
                                "groups": [11,12,13,...]}'

Response

[
                          {
                            "date_created": "2019-06-20T10:37:21+00:00",
                            "email": "user@mail.com",
                            "id": "iDCHaRs",
                            "name": "user's name",
                            "position": "User position"
                          }
                        ]

Working with Versions

• Terminology
• Get one Version (GET))
• Get files from a Version (GET)
• Get all Versions (GET)
• Get all Status (GET)

Terminology

Version

Version: A version is a collection of files that are considered a set to which a specific state and version number (a human one and a computer one) is assigned. Versions are used to ensure the correct files are used. A version is identified by a unique ID and a user number.number model (ex. Version 1.2) and is defined by the set of labels assigned to it. A version must contain AT LEAST one file.

version object

Status

Status: A version can be set to a specific Status (ex. Approved). This determines the purpose of the Version and can be used to filter, limit access, etc.

status object

Get one Version

Return the details of a specific version.

Request

Resource

Inputs

Empty.

Response

Content

A version object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/versions/{VERSION_ID} \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

{
                            "id": 956783,
                            "labels": [
                                {
                                    "id": 928,
                                    "group": {
                                        "color": "#E85637",
                                        "id": 49,
                                        "name": "Manufacturer"
                                    },
                                    "name": "Label 928"
                                },
                                {
                                    "id": 78,
                                    "group": {
                                        "color": "#EAC739",
                                        "id": 89,
                                        "name": "Presentation"
                                    },
                                    "name": "Label 78"
                                }
                            ],
                            "labels_text": "Label 928, Label 78",
                            "version": "4.2",
                            "version_number": 4,
                            "subversion_number": 2,
                            "time_created": "2021-02-10T11:32:07+00:00",
                            "user_owner": {
                                "date_created": "2019-02-19T09:09:23+00:00",
                                "email": "user@mail.com",
                                "id": "iDCHaRs",
                                "name": "User example name",
                                "position": "User position"
                            },
                            "status": {
                                "color": "#E1AB32",
                                "id": 12,
                                "name": "In process"
                            }
                        }

Get files from a Version

Return the list of all files in a version.

Request

Resource

Inputs

Empty

Response

Content

A collection of files object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/versions/{VERSION_ID}/files \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

[
                            {
                                "active": true,
                                "date": "2021-02-09T17:27:36+00:00",
                                "extension": "pdf",
                                "filesize": "274.59kB",
                                "id": 1844020,
                                "mimetype": "application/pdf",
                                "name": "file1.pdf",
                                "size": 281183,
                                "metadata": []
                            },
                            {
                                "active": true,
                                "date": "2021-02-09T17:27:36+00:00",
                                "extension": "pdf",
                                "filesize": "154.56kB",
                                "id": 1844020,
                                "mimetype": "application/pdf",
                                "name": "file2.pdf",
                                "size": 154560,
                                "metadata": []
                            }
                        ]

Get all Versions

Return the list of all versions in the organization.

Version

Resource

Inputs

Filtering list

To filter the list of versions, you can add a conditional query q as field:query (#search-queries).

Allowed filters:

To order the list of versions, you can add a short query short_by as field1,field2 (#search-queries).

Order fields:

Response

Content

A collection of version objects.

Code

Examples

Request

# Get requests from the workflow 31 order by id desc
                        curl -X GET \
                          https://{BASE_URL}/api/v2/versions \
                          -H 'access-token: {ACCESS_TOKEN}' \
                          --data-urlencode 'q=status:12' \
                          --data-urlencode 'sort_by=-id'

Response

[
                            {
                                "id": 956783,
                                "labels": [
                                    {
                                        "id": 922,
                                        "group": {
                                            "color": "#E85637",
                                            "id": 49,
                                            "name": "Manufacturer"
                                        },
                                        "name": "Label 922"
                                    },
                                    {
                                        "id": 78,
                                        "group": {
                                            "color": "#EAC739",
                                            "id": 89,
                                            "name": "Presentation"
                                        },
                                        "name": "Label 78"
                                    }
                                ],
                                "labels_text": "Label 922, Label 78",
                                "version": "1.2",
                                "version_number": 1,
                                "subversion_number": 2,
                                "time_created": "2021-02-10T11:32:07+00:00",
                                "user_owner": {
                                    "date_created": "2019-02-19T09:09:23+00:00",
                                    "email": "user@mail.com",
                                    "id": "iDCHaRs",
                                    "name": "User example name",
                                    "position": "User position"
                                },
                                "status": {
                                    "color": "#E1AB32",
                                    "id": 12,
                                    "name": "In process"
                                }
                            },
                            {
                                "id": 956743,
                                "labels": [
                                    {
                                        "id": 923,
                                        "group": {
                                            "color": "#E85637",
                                            "id": 49,
                                            "name": "Manufacturer"
                                        },
                                        "name": "Label 923"
                                    },
                                    {
                                        "id": 76,
                                        "group": {
                                            "color": "#EAC739",
                                            "id": 89,
                                            "name": "Presentation"
                                        },
                                        "name": "Label 76"
                                    }
                                ],
                                "labels_text": "Label 923, Label 76",
                                "version": "4.2",
                                "version_number": 4,
                                "subversion_number": 2,
                                "time_created": "2021-02-09T11:32:07+00:00",
                                "user_owner": {
                                    "date_created": "2019-02-19T09:09:23+00:00",
                                    "email": "user@mail.com",
                                    "id": "iDCHaRs",
                                    "name": "User example name",
                                    "position": "User position"
                                },
                                "status": {
                                    "color": "#E1AB32",
                                    "id": 12,
                                    "name": "In process"
                                }
                            }
                        ]

Get all status

Return the list of all version status in the organization.

Request

Resource

Inputs

Empty

Response

Content

A collection of status object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/versions/status \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

[
                            {
                                "color": "#E1AB32",
                                "id": 12,
                                "name": "In process"
                            },
                            {
                                "color": "#E85637",
                                "id": 267,
                                "name": "Discarded Version"
                            },
                            {
                               "color":"#63B7AD",
                               "id":571,
                               "name":"Finished"
                            }
                        ]

Working with workflows

• Terminology
• Get all workflows (GET))
• Get workflow transitions (GET))

Terminology

Workflow

Workflow: A workflow defines the pathway of a request. It is a constellation of potential transitions between Request Statuses, thus a Request can only be placed in a “target” Status if there is a transition with the current Status as “origin” and the corresponding “target”. A workflow typically represents a specific process in your Organization and can be an object of permission restrictions.

workflow object

Transitions

Transition: A transition represents the potential to change the Status of a request from an “origin” Status to a “target” Status. Transitions a can be objects of permission restrictions

transition object

Get all workflows

Return the details of a specific request (by its unique request id)

Request

Resource

Inputs

Empty.

Response

Content

A collection of workflow object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/workflows \
                          -H 'access-token: {ACCESS_TOKEN}'

Response

[
                            {
                                "id": 333,
                                "name": "Standard",
                                "initial_status": {
                                    "color": "#CECECE",
                                    "id": 81,
                                    "name": "Draft"
                                }
                            },
                            {
                                "id": 334,
                                "name": "Design team",
                                "initial_status": {
                                    "color": "#cecece",
                                    "id": 991,
                                    "name": "Received"
                                }
                            }
                        ]

Get workflow transitions

Return the list of all active transitions of a workflow.

Request

Resource

Inputs

Empty

Filtering

Response

Content

A collection of transition object.

Code

Examples

Request

curl -X GET \
                          https://{BASE_URL}/api/v2/workflows/{WORKFLOW_ID}/transitions \
                          -H 'access-token: {ACCESS_TOKEN}' \
                          -d 'origin=81'

Response

[
                            {
                                "id": 162,
                                "origin": {
                                    "color": "#CECECE",
                                    "id": 81,
                                    "name": "Draft"
                                },
                                "target": {
                                    "color": "#EAC739",
                                    "id": 471,
                                    "name": "Processing"
                                }
                            },
                            {
                                "id": 762,
                                "origin": {
                                    "color": "#CECECE",
                                    "id": 81,
                                    "name": "Draft"
                                },
                                "target": {
                                    "color": "#97CBC0",
                                    "id": 173,
                                    "name": "Received"
                                }
                            }
                        ]