API Docs v1

Authentication

Using OneDeck's API requires an API Key.
To create an API Key, you must have an active account. On plans with roles, only a Super Admin can create keys.

Go to Settings > Security > API keys and create a new key. The key is shown only once, so copy it right away. A key can be revoked there at any time.

OneDeck's API uses token-based authentication: send the key in the auth-token header of every request.

Example:
auth-token : API_KEY
All API requests must be authenticated and made through HTTPS.

A missing header returns 401 "Auth Token Not Available", an unknown or revoked key returns 401 "Auth Token Not Valid", and a key of a cancelled account returns 403 "Account cancelled".

Requests are rate limited. When the limit is exceeded, the API returns 429 — wait and retry the request.

URL Access

API endpoint format
https://{accountName}.onedeck.com/api/v1{endpoint}
accountName is your account's subdomain, e.g. acme for acme.onedeck.com.

Workspaces

Get Workspaces

Endpoint
GET/workspaces
Request Header
Content-Type : application/json
auth-token : {apikey} required
Response Data
[
   {
      "workspaceId": "1ff5d564-2ea6-4053-8c20-fac2ef32f059",
      "name": "Sales",
      "icon": "Checklist"
   }
]

Create Workspace

Endpoint
POST/workspaces
Request Header
Content-Type : application/json
auth-token : {apikey} required
Request Data
{
   "name": "Sales", required
   "icon": "Checklist"
}
name is up to 35 characters. icon is optional, one of: Checklist, Suitcase, Timer, Description, Monitoring, Chart, Dashboard, Billing, Eye, Play, Apps, Calendar, Attachment, Delete, Amount, Milestone, Email, Info.
Response Data
Status 201. A workspace with the same name returns 409.
{
   "workspaceId": "1ff5d564-2ea6-4053-8c20-fac2ef32f059",
   "name": "Sales",
   "icon": "Checklist"
}

Update Workspace

Endpoint
PATCH/workspaces/{workspaceId}
Request Header
Content-Type : application/json
auth-token : {apikey} required
Request Data
Send any of the keys; only the keys you send are changed.
{
   "name": "Sales 2026",
   "icon": "Chart"
}
Response Data
{
   "workspaceId": "1ff5d564-2ea6-4053-8c20-fac2ef32f059",
   "name": "Sales 2026",
   "icon": "Chart"
}

Boards

Get Boards

Endpoint
GET/boards
Request Header
Content-Type : application/json
auth-token : {apikey} required
Response Data
[
   {
      "id": "1ff5d564-2ea6-4053-8c20-fac2ef32f059",
      "name": "Foo",
      "workspaceId": "1ff5d564-2ea6-4053-8c20-fac2ef32f060",
      "workspace": "Sales"
   }
]

Create Board

Endpoint
POST/boards
Request Header
Content-Type : application/json
auth-token : {apikey} required
Request Data
{
   "workspaceId": "1ff5d564-2ea6-4053-8c20-fac2ef32f060", required
   "name": "Leads" required
}
The board is created with a default table view and permissions for every role. name is up to 35 characters.
Response Data
Status 201. A board with the same name in the workspace returns 409.
{
   "boardId": "1ff5d564-2ea6-4053-8c20-fac2ef32f059",
   "name": "Leads",
   "workspaceId": "1ff5d564-2ea6-4053-8c20-fac2ef32f060"
}

Update Board

Endpoint
PATCH/boards/{boardId}
Request Header
Content-Type : application/json
auth-token : {apikey} required
Request Data
Rename the board, move it to another workspace, or both.
{
   "name": "Leads 2026",
   "workspaceId": "1ff5d564-2ea6-4053-8c20-fac2ef32f061"
}
Response Data
{
   "boardId": "1ff5d564-2ea6-4053-8c20-fac2ef32f059",
   "name": "Leads 2026",
   "workspaceId": "1ff5d564-2ea6-4053-8c20-fac2ef32f061"
}

Fields

Get Fields

Endpoint
GET/boards/{boardId}/fields
Request Header
Content-Type : application/json
auth-token : {apikey} required
Response Data
[
   {
      "id": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
      "name": "Status",
      "type": 3,
      "boardId": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
      "settings": {
         "options": [
            {
               "id": 1,
               "color": "orangeWeb",
               "label": "No answer",
               "value": 1
            }
         ]
      }
   }
]

Create Field

Endpoint
POST/boards/{boardId}/fields
Request Header
Content-Type : application/json
auth-token : {apikey} required
Request Data
{
   "name": "Status", required
   "type": "STATUS", required
   "options": ["New", "In progress", "Done"],
   "description": "Lead status",
   "isRequired": false,
   "isValueUnique": false
}
type is one of: TEXT, TEXT_EDITOR, NUMBER, AMOUNT, PERCENT, STATUS, SELECT, MULTI_SELECT, DATE, DATE_RANGE, EMAIL, PHONE, ASSIGNEE, LOCATION, BOARD_CONNECTED.

STATUS, SELECT and MULTI_SELECT require options (an array of labels). BOARD_CONNECTED requires linkedBoardId and accepts isLinkToMultiple. Other types accept defaultValue. The new field is added to every view of the board.
Response Data
Status 201. A field with the same name on the board returns 409.
{
   "fieldId": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
   "name": "Status",
   "type": "STATUS",
   "boardId": "1ff5d564-2ea6-4053-8c20-fac2ef32f059"
}

Update Field

Endpoint
PATCH/boards/{boardId}/fields/{fieldId}
Request Header
Content-Type : application/json
auth-token : {apikey} required
Request Data
Send any of: name, description, isRequired, isValueUnique, defaultValue, isLinkToMultiple, settings, defaultMeta. The field type cannot be changed — sending type returns 400.
{
   "name": "Lead status",
   "isRequired": true
}
Response Data
{
   "fieldId": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
   "name": "Lead status",
   "type": 3,
   "settings": { "options": [ ... ] },
   "boardId": "1ff5d564-2ea6-4053-8c20-fac2ef32f059"
}

Records

Get Record

Endpoint
GET/boards/{boardId}/records/{recordId}
Request Header
Content-Type : application/json
auth-token : {apikey} required
Response Data
Field values are keyed by the field name in lowercase. STATUS and SELECT return the option label, ASSIGNEE returns { name, id }, connected fields return a list of { name, id }, dates are epoch milliseconds.
{
  "id": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
  "name": "Foo",
  "userCreated": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
  "createDate": 1682403747944,
  "rowOrder": "0|i0000n:",
  "isCollapsed": false,
  "converted": false,
  "lastUserModified": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
  "commentsCount": 3,
  "attachmentsCount": 1,
  "lastModified": 1682403747944,
  "status": "No answer",
  "owner": {
    "name": "John James",
    "id": "1ff5d564-2ea6-4053-8c20-fac2ef32f029"
  },
  "attachments": [{
    "fileName": "fileName.png",
    "contentType": "image/png",
    "size": 45232,
    "downloadUrl": "https://onedeck.com/foo"
  }],
  "shareLink": "http://acme.onedeck.com/board/{boardId}/view/table/record/{recordId}"
}

Get Records

Endpoint
GET/boards/{boardId}/records?filters={Search Params}&top={number}&searchValue={text}
Request Header
Content-Type : application/json
auth-token : {apikey} required
Query Params
All optional. top limits the number of records, searchValue searches the records, filters is a URL-encoded JSON array. A filter id is a field id or "name" for the record name.
Search Params
[
   {
      "id": "name",
      "value": ["Foo","Bar"]
   },
   {
      "id": "1ff5d564-2ea6-4053-8c20-fac2ef32f030",
      "value": ["Foo"]
   }
]
Response Data
A list of records in the same shape as Get Record.
[
   {
      "id": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
      "name": "Foo",
      "userCreated": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
      "createDate": 1682403747944,
      "rowOrder": "0|i0000n:",
      "isCollapsed": false,
      "converted": false,
      "lastUserModified": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
      "commentsCount": 3,
      "attachmentsCount": 0,
      "lastModified": 1682403747944,
      "status": "No answer",
      "attachments": [],
      "shareLink": "http://acme.onedeck.com/board/{boardId}/view/table/record/{recordId}"
   }
]

Create Record

Endpoint
POST/boards/{boardId}/records
Request Header
Content-Type : application/json
auth-token : {apikey} required
Request Data
{
   "name": "Foo",
   "fields": [
      {
         "id": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
         "value": "Foo"
      },
      {
         "id": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
         "value": {
            "from":1783472640000,
            "to":1784678820000
         }
      }
   ]
}
Response Data
{
   "success": true,
   "newRecordId": "1ff5d564-2ea6-4053-8c20-fac2ef32f029"
}

Update Record

Endpoint
PUT/boards/{boardId}/records/{recordId}
Request Header
Content-Type : application/json
auth-token : {apikey} required
Request Data
An array of field updates. fieldId is a field id or "name" for the record name.
[
   {
      "fieldId": "name",
      "value": "Foo"
   },
   {
      "fieldId": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
      "value": "Foo"
   },
   {
      "fieldId": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
      "value": {
         "from":1783472640000,
         "to":1784678820000
      }
   }
]
Response Data
{
   "success": true
}

Documents

Get Document

Endpoint
GET/documents/{documentId}
Request Header
Content-Type : application/json
auth-token : {apikey} required
Response Data
Returns a published document. An unknown id returns an empty array.
[
   {
      "documentId": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
      "author": "John James",
      "relatedRecordId": "1ff5d564-2ea6-4053-8c20-fac2ef32f030",
      "relatedRecordName": "Foo",
      "typeName": "Work Order",
      "serialNumber": "03-001763",
      "publishedDate": "2024-02-21T10:15:00.000Z",
      "recipientName": "Bar Ltd",
      "recipientId": "1ff5d564-2ea6-4053-8c20-fac2ef32f031",
      "projectName": "Website",
      "tax": 170,
      "discount": 0,
      "subtotal": 1000,
      "total": 1170,
      "currency": "USD",
      "downloadURL": "https://onedeck.com/foo.pdf",
      "sections": [
         {
            "id": "a1b2c3",
            "type": "TextEditor",
            "name": "Terms",
            "content": "Plain text of the section"
         }
      ]
   }
]

Get Documents

Endpoint
GET/documents?filters={Search Params}
Request Header
Content-Type : application/json
auth-token : {apikey} required
Search Params
Returns published documents. Date filters take [from, to] as date strings; either bound may be null.
[
   {
      "id": "type",
      "value": ["1ff5d564-2ea6-4053-8c20-fac2ef32f029"]
   },
   {
      "id": "relatedRecordId",
      "value": ["1ff5d564-2ea6-4053-8c20-fac2ef32f029"]
   },
   {
      "id": "recipientName",
      "value": ["Foo","Bar"]
   },
   {
      "id": "recipientId",
      "value": ["1ff5d564-2ea6-4053-8c20-fac2ef32f029","1ff5d564-2ea6-4053-8c20-fac2ef32f030"]
   },
   {
      "id": "issueDate",
      "value": ["2024-01-01","2024-12-31"]
   },
   {
      "id": "publishedDate",
      "value": ["2024-01-01","2024-12-31"]
   },
   {
      "id": "createDate",
      "value": ["2024-01-01","2024-12-31"]
   },
   {
      "id": "serialNumber",
      "value": ["01-123456", "03-123456"]
   },
   {
      "id": "amount",
      "value": ["5000.50","10000"]
   }
]
Response Data
A list of documents in the same shape as Get Document, without downloadURL.
[
   {
      "documentId": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
      "typeName": "Work Order",
      "serialNumber": "03-001763",
      "publishedDate": "2024-02-21T10:15:00.000Z",
      "recipientName": "Bar Ltd",
      "total": 1170,
      "currency": "USD"
   }
]

Update Document

Endpoint
PATCH/documents/{documentId}
Request Header
Content-Type : application/json
auth-token : {apikey} required
Request Data
Send any of the keys. state is one of open, closed, canceled; relatedRecordId may be null to unlink the record.
{
  "state": "closed",
  "relatedRecordId": "1ff5d564-2ea6-4053-8c20-fac2ef32f029"
}
Response Data
The updated document.
{
   "documentId": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
   "typeId": "1ff5d564-2ea6-4053-8c20-fac2ef32f032",
   "typeName": "Work Order",
   "status": "published",
   "state": "closed",
   "serialNumber": "03-001763",
   "relatedRecordId": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
   "signStatus": null,
   "data": { "sections": [ ... ] },
   "settings": { ... },
   "amounts": { ... }
}

Users

Get Users

Endpoint
GET/users
Request Header
Content-Type : application/json
auth-token : {apikey} required
Response Data
[
   {
      "id": "1ff5d564-2ea6-4053-8c20-fac2ef32f029",
      "name": "John James",
      "firstName": "John",
      "lastName": "James",
      "email": "[email protected]",
      "image": "/images/img.png",
      "status": "active",
      "role": "1ff5d564-2ea6-4053-8c20-fac2ef32f030",
      "createDate": "2024-02-21T10:15:00.000Z",
      "updatedAt": "2024-03-01T08:00:00.000Z",
      "twoFaEnabled": false
   }
]

Attachments

Upload

Endpoint
POST/boards/{boardId}/records/{recordId}/attachments
Request Header
Content-Type : MIME type required
Content-Length : {size in bytes} required
auth-token : {apikey} required
x-file-name : {fileName} required
Request Data
Raw binary data of the file.
The request body must contain only the file bytes (equivalent to curl --data-binary).
Do not send JSON or multipart/form-data.
Response Data
{
  "success": true,
  "attachment": {
    "recordId": "1f242e49-767e-42e0-b16f-3c0a117b4c8e",
    "fileName": "fileName.png",
    "type": "image/png",
    "sizeBytes": 402462
  }
}

Share Studio

Invite

Endpoint
POST/share-studio/{shareId}/invite
Request Header
Content-Type : application/json
auth-token : {apikey} required
Request Data
{
  "email": "[email protected]", required
  "firstName": "John",
  "lastName": "James",
  "recordId": "1f242e49-767e-42e0-b16f-3c0a117b4c8e"
}
Response Data
{
  "success": true,
  "inviteLink": "https://auth.onedeck.com/client-registration?token=foo...&location={accountName}"
}