Public API Reference

NileDesk provides a comprehensive set of public APIs that allow external systems to insert, update, delete, fetch, and process data across Process Flows, Boards, Datasets, and Data Forms.

These APIs are commonly used for integrations with CRMs, ERPs, portals, automation platforms (Zapier, n8n), and custom applications.

Authentication

All API requests must include the following HTTP headers. Requests missing either header will be rejected with an authentication error.

Header	Description
`X-Org-Id`	Your Organization ID, the same one you use to log in to NileDesk.
`X-Api-Key`	Your personal API key, available under Change Password in your profile.

Example Request Headers


X-Org-Id: your_organization_id
X-Api-Key: your_api_key
Content-Type: application/json

Base URL

https://app.niledesk.com/api/public/{EndpointName}

API Categories

Insert Data – Create new live or draft items and records
Update Data – Modify one or multiple records
Delete Data – Remove records from datasets or forms
Fetch Data – Query records, counts, templates, and fields
Process Data – Move items through process flow steps
Attachments & Comments – Upload files and add comments

Create Items / Insert Data APIs

POST InitiateProcessItem – Create a live Process Flow item
POST InitiateBoardItem – Create a live Board item at a drop step
POST CreateProcessDraftItem – Create a draft Process Flow item
POST CreateBoardDraftItem – Create a draft Board item
POST AddRecord – Add a new row to Dataset or Data Form


POST https://app.niledesk.com/api/public/InitiateProcessItem
POST https://app.niledesk.com/api/public/InitiateBoardItem
POST https://app.niledesk.com/api/public/CreateProcessDraftItem
POST https://app.niledesk.com/api/public/CreateBoardDraftItem
POST https://app.niledesk.com/api/public/AddRecord

InitiateProcessItem – Request Body

Creates a live Process Flow item and starts it from the first step.

{
  "template_id": "template_id",
  "form_fields": {
    "field1": "value1",
    "field2": 22
  },
  "form_tables": {           // if any
    "p_collection_name_tbl1": [
      { "field1": "value1", "field2": 22 },
      { "field1": "value2", "field2": 33 }
    ]
  }
}

InitiateBoardItem – Request Body

Creates a live Board item and places it directly at the specified drop step (column). step_id is required.

{
  "template_id": "template_id",
  "step_id": "board_drop_step_id",
  "form_fields": {
    "field1": "value1",
    "field2": 22
  },
  "form_tables": {           // if any
    "p_collection_name_tbl1": [
      { "field1": "value1", "field2": 22 },
      { "field1": "value2", "field2": 33 }
    ]
  }
}

CreateProcessDraftItem – Request Body

Creates a saved draft for a Process Flow item without initiating it. The draft can be submitted later.

{
  "template_id": "template_id",
  "form_fields": {
    "field1": "value1",
    "field2": 22
  },
  "form_tables": {           // if any
    "p_collection_name_tbl1": [
      { "field1": "value1", "field2": 22 },
      { "field1": "value2", "field2": 33 }
    ]
  }
}

CreateBoardDraftItem – Request Body

Creates a saved draft for a Board item. This will always drop item to Draft Column.

{
  "template_id": "template_id",
  "form_fields": {
    "field1": "value1",
    "field2": 22
  },
  "form_tables": {           // if any
    "p_collection_name_tbl1": [
      { "field1": "value1", "field2": 22 },
      { "field1": "value2", "field2": 33 }
    ]
  }
}

AddRecord – Request Body

Inserts a new row into a Dataset or Data Form.

{
  "template_id": "template_id",
  "fields": {
    "field1": "value1",
    "field2": 22
  },
  "form_tables": {           // if any
    "p_collection_name_tbl1": [
      { "field1": "value1", "field2": 22 },
      { "field1": "value2", "field2": 33 }
    ]
  }
}

Parameters Explained

template_id – Target Process Flow, Board, Dataset, or Form
step_id – Required for Board endpoints (InitiateBoardItem). Specifies the target column/drop step.
form_fields – Key-value pairs for Process Flow and Board form fields. Supports string, number, and datetime. For datasnap, datalink pass the referenced key, for userlink, pass the user email.
fields – Used by AddRecord only. Same key-value structure as form_fields but applies to Dataset and Data Form records.
form_tables – Optional. Populate embedded form tables using their collection names. Only needed if the template contains table fields.

File Upload & Comments

Upload a file to NileDesk and then use its returned reference to insert comments or use in attachment fields.

Upload File


POST https://app.niledesk.com/api/public/UploadFile

Uploads one or more files and returns a ref_id. This ref_id can be used while creating items or adding comments. Authentication is provided via the standard X-Org-Id and X-Api-Key headers.

Add Comment

Add collaborative comments to a process flow/board tempalte item.


POST https://app.niledesk.com/api/public/AddComment

{
  "process_id": "process_item_id",
  "message": "Comment message",
  "attachment": "optional_file_ref_id"
}

Update Data APIs

Update process flow, board, or dataset record data.

POST UpdateOneRecord – Update a single record
POST UpdateManyRecords – Update multiple records using filters


POST https://app.niledesk.com/api/public/UpdateOneRecord
POST https://app.niledesk.com/api/public/UpdateManyRecords

Update Request Body

{
  "template_id": "template_id",
  "fields": {
    "field1": "value1",
    "field2": 22
  },
  "filters": {
    "logic": "and",
    "rules": [
      { "field1": "value", "operator": "eq" },
      { "field2": "value", "operator": "neq" }
    ]
  }
}

Delete Data APIs

Delete a record in a dataset or data form. Deletion is not applicable to process items.

POST DeleteOneRecord
POST DeleteManyRecords


POST https://app.niledesk.com/api/public/DeleteOneRecord
POST https://app.niledesk.com/api/public/DeleteManyRecords

Delete Request Body

{
  "template_id": "template_id",
  "filters": {
    "logic": "and",
    "rules": [
      { "field1": "value", "operator": "eq" }
    ]
  }
}

Fetch Data APIs

POST FindOneRecord
POST FindManyRecord
POST CountRecords


POST https://app.niledesk.com/api/public/FindOneRecord
POST https://app.niledesk.com/api/public/FindManyRecord
POST https://app.niledesk.com/api/public/CountRecords

{
  "template_id": "template_id",
  "process_id": "process_item_id",
  "filters": {
    "logic": "and",
    "rules": [
      { "field1": "value", "operator": "eq" }
    ]
  },
  "limit": 100,                          // Optional. Max records to return. Only applies to FindManyRecord
  "sort": {
    "field": "_id",                      // Field name to sort by. Use system fields or any custom field
    "sort_by": "desc"                    // "asc" (oldest first) | "desc" (newest first)
  },
  "fields": ["_id", "_submitted_at", "_status"]  // Optional. Specific fields to return. Leave empty [] to return all fields

}

Filter Operators Reference

Filters are used in Fetch, Update, and Delete APIs to apply conditional logic on records. Each filter rule consists of a field, a comparison value, and an operator.

Operator Name	Code	Description
Equal To	`eq`	Matches records where the field value is exactly equal to the given value
Not Equal To	`neq`	Matches records where the field value is not equal to the given value
Contain	`ct`	Matches records where the field value contains the given text
Not Contain	`nct`	Matches records where the field value does not contain the given text
Start With	`sw`	Matches records where the field value starts with the given text
Ends With	`ew`	Matches records where the field value ends with the given text
Greater Than	`gt`	Matches records where the field value is greater than the given value
Greater Than or Equal	`gte`	Matches records where the field value is greater than or equal to the given value
Less Than	`lt`	Matches records where the field value is less than the given value
Less Than or Equal	`lte`	Matches records where the field value is less than or equal to the given value

Note: Multiple filter rules can be combined using and or or logic in the filters object.

Template & Metadata APIs

Get Templates with API Access

Returns all templates (Process Flows, Boards, Datasets, Forms) that are enabled for API access within the organization.


POST https://app.niledesk.com/api/public/GetTemplates

Request Body

{}

Get Fields of a Template

Returns all fields defined in a specific template. This is useful for dynamically mapping external data to NileDesk fields.


POST https://app.niledesk.com/api/public/GetFields

Request Body

{
  "template_id": "template_id"
}

Get Process / Board Item Timeline

Fetches the complete activity timeline of a Process Flow or Board item, including step transitions, approvals, and user actions.


POST https://app.niledesk.com/api/public/GetProcessTimeline

Request Body

{
  "process_id": "process_item_id"
}

Process Flow Actions

These APIs are used to move a Process Flow item through its lifecycle, such as submitting input, approving, rejecting, or returning it to a previous step.

POST ProcessItem – Send item forward from an input step
POST ApproveItem – Approve item at an approval step
POST RejectItem – Reject item at an approval step
POST ReturnItemToLastExecutedStep – Roll item back to last executed step


POST https://app.niledesk.com/api/public/ProcessItem
POST https://app.niledesk.com/api/public/ApproveItem
POST https://app.niledesk.com/api/public/RejectItem
POST https://app.niledesk.com/api/public/ReturnItemToLastExecutedStep

Process Request Body

{
  "process_id": "process_item_id",
  "step_id": "step_id",  //Step id from where the item should process
  "remarks": "optional remarks",
  "form_fields": {
    "field1": "value1",
    "field2": 22
  },
  "form_tables": {   // if any
    "p_collection_name_tbl1": [
      { "field1": "value1", "field2": 22 },
      { "field1": "value2", "field2": 33 }
    ]
  }
}

Board Item Transition / Switching

This API is used to move/transition (switch) a Board item from its current column to another step within the same Board template. This action is only applicable to Board-type templates.

Note: Ensure that the target column transition on your board is configured to allow movement to the next step, otherwise the item will not switch columns.

POST SwitchBoardStep – Move a board item to another board step


POST https://app.niledesk.com/api/public/SwitchBoardStep

Switch Board Request Body

{
  "process_id": "process_item_id",
  "board_drop_step": "target_step_id",
  "form_fields": {
    "field1": "value1",
    "field2": 22
  },
  "form_tables": {  // if any
    "p_collection_name_tbl1": [
      { "field1": "value1", "field2": 22 },
      { "field1": "value2", "field2": 33 }
    ],
    "p_collection_name_tbl2": [
      { "field1": "value1", "field2": 22 },
      { "field1": "value2", "field2": 33 }
    ]
  }
}

Docs & Tutorials

Public API Reference

Authentication

Example Request Headers

Base URL

API Categories

Create Items / Insert Data APIs

InitiateProcessItem – Request Body

InitiateBoardItem – Request Body

CreateProcessDraftItem – Request Body

CreateBoardDraftItem – Request Body

AddRecord – Request Body

Parameters Explained

File Upload & Comments

Upload File

Add Comment

Update Data APIs

Update Request Body

Delete Data APIs

Delete Request Body

Fetch Data APIs

Filter Operators Reference

Template & Metadata APIs

Get Templates with API Access

Request Body

Get Fields of a Template

Request Body

Get Process / Board Item Timeline

Request Body

Process Flow Actions

Process Request Body

Board Item Transition / Switching

Switch Board Request Body