Vertask API
Use Vertask's RESTful API to post new tasks, retrieve and update existing tasks and integrate with your existing applications.
Prerequisites
Before you can access the API, enable API Access in your agent settings and generate an api key there. If you do not have access to this setting, you will need to contact your account admin. You need super user permission to enable and use API features.
The authentication username is the company id, and the password is your api key generated here.
Base address
The API address format is:
https://vertask.com/api/requests/{method}
Modify the {method} to access different functions available.
Basic authentication
Every API action checks the user's permissions before executing (showing tasks, posting comments etc), so you must send the basic authorization headers with each request.
Most http-client software (like curl, postman etc.) supports basic authentication out of the box without any additional coding. But just in case - here's how you construct the Authorization header:
- Username and password are combined into a colon-separated string
username:password - The resulting string literal is then encoded using Base64
- The authorization method and a space i.e.
Basicis then put before the encoded string. - For example, if the username (your company id) is
Z2Web6-s0XEafand the password (your api key) is1234-5678, then we would convert Z2Web6-s0XEaf:1234-5678 (becomes WjJXZWI2LXMwWEVhZjoxMjM0LTU2Nzg=) and the header is formed as follows:
Authorization: Basic WjJXZWI2LXMwWEVhZjoxMjM0LTU2Nzg=
Passing parameters
All incoming method-parameters should be passed via GET or POST.
When requesting data, use GET and the appropriate paramaters. For example, https://vertask.com/api/requests/authorization/{id}?var1=1&var2=2
When updating or making changes to data, you can POST the parameters as form-data to target the fields you want to update.
Cookies support
We highly recommend using a client that accepts cookies (sent by the server with the response). We cache a lot of secondary non-sensitive data in the "session" so using cookies can and will speed up the API response and ease the load on the server.
General methods
Authorization
GET https://vertask.com/api/requests/authorization
Use this method to simply test if you pass correct basic authentication headers. The method returns the "user" object (as a JSON string) that represents the authenticated user. Please find the available properties below.
Returns:
{
"code": 200,
"desc": "Agent found",
"response": {
"id": 18,
"date_joined": "2022-06-25 18:37:32",
"status": 1,
"fname": "Paul",
"lname": "Nurse",
"email": "[email protected]",
"user_phone": null,
"job_title": null,
"last_login": "2022-12-09 23:30:02"
}
}
Rate Limiting
Many of the resource-intensive methods in the Help Desk API have rate-limits and throttle abusive clients. Most of the calls are limited to 60 times per minute. If a client sends more requests, the server responds with 429 status code. Wait a few seconds and try again.
{
"code": 429 ,
"desc": "Rate Limit Exceeded" ,
"response": []
}
Agent methods
Get-Agents
GET https://vertask.com/api/requests/get-agents
Use this method to get a list of all agents.
Returns:
{
"code": 200,
"desc": "Agents found",
"response": {
"rows": 21,
"agents": [
{
"id": 30,
"fname": "Paul",
"lname": "Nurse",
"email": "[email protected]",
"last_modified": "2022-12-09 23:30:02"
},
{
...
...
}
]
}
}
Get-Agent
GET https://vertask.com/api/requests/get-agent/30
Use this method to get details on one agent. This method returns a json object with the details of the agent provided
Returns:
{
"code": 200,
"desc": "Agent found",
"response": {
"id": 30,
"date_joined": "2022-06-25 18:37:32",
"status": 1,
"fname": "Paul",
"lname": "Nurse",
"email": "[email protected]",
"user_phone": null,
"job_title": null,
"last_login": "2022-12-09 23:30:02"
}
}
Get-Agent-Groups
GET https://vertask.com/api/requests/get-agent-groups
Use this method to get a list of all agent groups.
Returns:
{
"code": 200,
"desc": "Groups found",
"response": {
"rows": 10,
"groups": [
{
"id": 6,
"status": 1,
"group": "IT Members",
"email": "[email protected]",
"creator": 5,
"date_created": "2022-12-09 23:30:02"
},
{
...
...
}
]
}
}
Get-Agent-Group
GET https://vertask.com/api/requests/get-agent-group/6
Use this method to get details on an agent group. This method returns a json object with the details of the group provided.
Returns:
{
"code": 200,
"desc": "Group found",
"response": {
"id": 6,
"date_created": "2019-07-03 01:08:43",
"status": 1,
"name": "IT Members",
"desc": "IT team members",
"location": Cleveland, OH,
"creator": 10,
"phone": null,
"email": "[email protected]"
}
}
Get-Agent-Group-Members
GET https://vertask.com/api/requests/get-agent-group-members/6
Use this method to get a list of all agents in a group. This method returns a json object with the users in the group provided.
Returns:
{
"code": 200,
"desc": "Members found",
"response": {
"rows": 3,
"agents": [
{
"id": 6,
"status": 1,
"fname": "Paul",
"lname": "Nurse",
"email": "[email protected]",
"date_joined": "2022-12-09 23:30:02"
},
{
...
...
}
]
}
}
Asset methods
Get-Assets
GET https://vertask.com/api/requests/get-assets
Use this method to get a list of all assets. When no search term is provided, results are returned alphabetically by name.
To search assets, pass a search term as a URL segment. The search performs a full-text match against asset name, model, serial key, and notes. Results are ordered by relevance when a search term is provided.
GET https://vertask.com/api/requests/get-assets/fileserver
Returns:
{
"code": 200,
"desc": "Assets found",
"response": {
"rows": 21,
"assets": [
{
"id": 30,
"type": "Server",
"name": "Fileserver2",
"item": "IBM X5",
"last_modified": "2022-12-09 23:30:02"
},
{
...
...
}
]
}
}
Get-Asset
GET https://vertask.com/api/requests/get-asset/13
Use this method to get details on an asset. This method returns a json object with the details of the asset provided
Returns:
{
"code": 200,
"desc": "Asset found",
"response": {
"id": 30,
"type": "Server",
"name": "Fileserver2",
"mfgr": "IBM",
"item": "IBM X5",
"sn": "50G6T53",
"status": 1,
"memory": "64GB",
"processor": null,
"warranty_date": "2028-12-10",
"notes": "For developers",
"architecture": "X64",
"os_publisher": "Windows",
"os_version": "Server 2019",
"privateIP4": "172.16.2.20",
"privateIP6": null,
"publicIP4": null,
"publicIP6": null,
"v_agent_sync": "0000-00-00 00:00:00",
"date_added": "2022-12-09 23:30:02"
}
}
Get-Property-Assets
GET https://vertask.com/api/requests/get-property-assets/8
Use this method to get all assets assigned to a location. This method returns a json object with the assets at the location provided.
Returns:
{
"code": 200,
"desc": "Assets found",
"response": {
"rows": 4,
"location_id": 8,
"assets": [
{
"id": 30,
"asset_name": "Fileserver2",
"type": "Server",
"model": "IBM X5",
"status": 1
},
{
...
...
}
]
}
}
Get-Property-Assets
GET https://vertask.com/api/requests/get-property-assets/4
Lists the assets/equipment assigned to a property. Each asset now also returns its per-placement install_date and placement_notes (added with the property asset-inventory feature). Requires the Assets dashboard and asset permission.
Returns:
{
"code": 200,
"desc": "Assets found",
"response": {
"rows": 1,
"location_id": 4,
"assets": [
{
"id": 88,
"asset_name": "Rooftop HVAC #2",
"type": "HVAC",
"model": "Carrier 48TC",
"status": 1,
"install_date": "2023-05-01",
"placement_notes": "Roof, north wing"
}
]
}
}Update-Property-Asset-Meta
POST https://vertask.com/api/requests/update-property-asset-meta
Sets the install date and/or placement notes for an asset that is already at a property. Asset serial, model and warranty live on the asset itself — manage those through the asset endpoints. The asset must already be assigned to the property (use Update-Property-Assets to assign it).
Post Fields:
| Field | Required | Description |
|---|---|---|
| property | Yes | The id of the property. |
| asset | Yes | The id of the asset (already placed at the property). |
| install_date | No | YYYY-MM-DD, or empty string to clear. |
| notes | No | Free-text placement note (e.g. "attic / north wing"). |
Returns:
{ "code": 200, "desc": "Asset placement updated", "response": true }Create-Asset (POST)
POST https://vertask.com/api/requests/create-asset
Create a new asset. The below paramaters are accepted during the asset creation as posted form-data, and only a title is required.
Parameters:
| Value | Type | Description |
|---|---|---|
| name | string | Asset name |
| type | int | Asset type id |
| mfgr | int | Asset manufacturer id |
| model | string | The model number or name of the asset |
| offices | int,string | Single or comma seperated string of office ids. |
| clients | int,string | Single or comma seperated string of client ids. |
| tags | int,string | Single or comma seperated string of tag ids. |
Returns
The created
asset idis returned, or error message if a problem occured.{ "code": 200, "desc": "success", "response": { "asset": 38 } }
Create-Asset-Group
POST https://vertask.com/api/requests/create-asset-group
Use this method to create a new asset group.
Post body:
{
"groupName": "Server Room A",
"desc": "Primary server room assets"
}
Returns:
{
"code": 200,
"desc": "Asset group created",
"response": {
"group_id": 5,
"group_name": "Server Room A",
"desc": "Primary server room assets"
}
}
Update-Asset
POST https://vertask.com/api/requests/update-asset
Use this method to update asset details. To enable or disable an asset, pass status as 1 (active) or 0 (inactive). Omit status to leave it unchanged.
Post body:
{
"asset": 30,
"asset_name": "Fileserver2",
"asset_model": "IBM X5",
"asset_type": 3,
"asset_mfgr": 7,
"asset_serial_key": "SN-00123",
"warranty_end_date": "2027-01-01",
"notes": "Located in server room B",
"status": 1
}
Returns:
{
"code": 200,
"desc": "Asset updated",
"response": {
"asset_id": 30,
"status": 1
}
}
Update-Asset-Delete
POST https://vertask.com/api/requests/update-asset-delete
Use this method to permanently delete an asset. This will also delete all associated locations, owners, task history, local accounts, disks, programs, tags, and group memberships. This action cannot be undone.
Post body:
{
"asset": 30
}
Returns:
{
"code": 200,
"desc": "Asset deleted"
}
Update-Asset-Addtag
POST https://vertask.com/api/requests/update-asset-addtag
Use this method to add and/or remove existing tags on an asset in a single request. Pass comma-separated tag ids in add and/or remove. Tags are not created — only links to existing tags in the company library are managed. The response includes counts of added, skipped, and removed tags.
Post body:
{
"asset": 30,
"add": "44,45,46",
"remove": "41,42"
}
Returns:
{
"code": 200,
"desc": "Tags updated",
"response": {
"asset_id": 30,
"added": 3,
"skipped": 0,
"removed": 2
}
}
Update-Asset-Member
POST https://vertask.com/api/requests/update-asset-member
Use this method to add or remove a client as an owner of an asset. Pass action as add or remove.
Post body:
{
"asset": 30,
"client": 12,
"action": "add"
}
Returns:
{
"code": 200,
"desc": "Client added to asset"
}
Update-Asset-Group
POST https://vertask.com/api/requests/update-asset-group
Use this method to update the name and description of an asset group.
Post body:
{
"group": 5,
"groupName": "Server Room A",
"desc": "Primary server room assets"
}
Returns:
{
"code": 200,
"desc": "Asset group updated",
"response": {
"group_id": 5,
"group_name": "Server Room A",
"desc": "Primary server room assets"
}
}
Update-Asset-Group-Add-Asset
POST https://vertask.com/api/requests/update-asset-group-add-asset
Use this method to add an asset to an asset group. Returns a 400 if the asset is already in the group.
Post body:
{
"group": 5,
"asset": 30
}
Returns:
{
"code": 200,
"desc": "Asset added to group",
"response": {
"group_id": 5,
"asset_id": 30
}
}
Update-Asset-Group-Remove-Asset
POST https://vertask.com/api/requests/update-asset-group-remove-asset
Use this method to remove an asset from an asset group.
Post body:
{
"group": 5,
"asset": 30
}
Returns:
{
"code": 200,
"desc": "Asset removed from group"
}
Update-Asset-Group-Delete
POST https://vertask.com/api/requests/update-asset-group-delete
Use this method to permanently delete an asset group. All asset memberships within the group are also removed. The assets themselves are not deleted.
Post body:
{
"group": 5
}
Returns:
{
"code": 200,
"desc": "Asset group deleted"
}
Asset Type methods
Asset type use and management methods. Each company keeps its own asset type list, and also sees a shared set of built-in global asset types. Global asset types are read-only: they appear in Get-Asset-Types with "global": true and cannot be updated, merged, or deleted through the API.
Get-Asset-Types
GET https://vertask.com/api/requests/get-asset-types
GET https://vertask.com/api/requests/get-asset-types/value
Use this method to get a list of all asset types available to your company (your own plus the shared globals). Add an optional id or term value to filter the list — a numeric value matches an id or any name/description containing it, and a text value matches the name or description.
Returns:
{
"code": 200,
"desc": "Asset types found",
"response": {
"rows": 3,
"asset_types": [
{
"id": 1,
"type": "Laptop",
"desc": "Portable computers",
"photo": "https://cdn.example.com/laptop.png",
"global": true
},
{
"id": 42,
"type": "Monitor",
"desc": "",
"photo": "",
"global": false
},
{
"id": 51,
"type": "Label Printer",
"desc": "",
"photo": "",
"global": false
}
]
}
}
Create-Asset-Type
POST https://vertask.com/api/requests/create-asset-type
Use this method to create a new asset type for your company.
Post Fields:
| Field | Required | Description |
|---|---|---|
| type | Yes | The asset type name. Must be unique within your company and must not match a shared global name. |
| desc | No | A description for the asset type. |
| photo | No | A photo/icon image URL for the asset type. |
Returns:
{
"code": 200,
"desc": "success",
"response": {
"type": 52
}
}
Update-Asset-Type
POST https://vertask.com/api/requests/update-asset-type
Use this method to update one of your company's asset types. Only fields included in the post are updated. To clear the description or photo, post it with an empty value. Shared globals cannot be updated.
Post Fields:
| Field | Required | Description |
|---|---|---|
| type | Yes | The id of the asset type to update. |
| name | No | A new name for the asset type. Must be unique within your company. Cannot be posted empty. |
| desc | No | A new description. Post empty to clear. |
| photo | No | A new photo URL. Post empty to clear. |
Returns:
{
"code": 200,
"desc": "Changes saved",
"response": true
}
Update-Asset-Type-Merge
POST https://vertask.com/api/requests/update-asset-type-merge
Use this method to merge one of your asset types into another. Every asset using the from asset type is moved to the into asset type, then the from asset type is deleted. Both must belong to your company; shared globals cannot be merged.
Post Fields:
| Field | Required | Description |
|---|---|---|
| from | Yes | The id of the asset type to remove. Its assets are reassigned, then it is deleted. |
| into | Yes | The id of the asset type to keep. Must be different from from. |
Returns:
{
"code": 200,
"desc": "Asset types merged",
"response": {
"merged_from": 42,
"merged_into": 51,
"assets_moved": 6
}
}
Delete-Asset-Type
POST https://vertask.com/api/requests/delete-asset-type
Use this method to delete one of your company's asset types. Any of your assets still using it are left without an asset type (their type is cleared). To keep the asset type on those assets instead, use Update-Asset-Type-Merge. Shared globals cannot be deleted.
Post Fields:
| Field | Required | Description |
|---|---|---|
| type | Yes | The id of the asset type to delete. |
Returns:
{
"code": 200,
"desc": "Asset type deleted",
"response": {
"type": 42,
"assets_unassigned": 3
}
}
Billing audience methods
API methods to work with billing audience. Billing audience allows you to associate tasks, projects, kb and more with a particular company or customer.
Create-Audience
POST https://vertask.com/api/requests/create-audience
Use this method to create a new billing audience. SLA targets are optional — post any priority pair (_match + _measure) to set a target at creation time. Each pair must be posted together; a match value without a valid measure will return an error.
Post Fields:
| Field | Required | Description |
|---|---|---|
| name | Yes | The audience name. Max 100 characters. Must be unique within your company. |
| contact | No | The main contact name for this audience. |
| status | No | Active state. 1 = active (default), 0 = inactive. |
| SLA Fields — post a _match and _measure pair for each priority you want to set: | ||
| severe_match | No | SLA target value for severe priority (number, e.g. 1). |
| severe_measure | No* | SLA unit for severe. Required if severe_match is set. |
| critical_match | No | SLA target value for critical priority (number, e.g. 3). |
| critical_measure | No* | SLA unit for critical. Required if critical_match is set. |
| high_match | No | SLA target value for high priority (number, e.g. 1). |
| high_measure | No* | SLA unit for high. Required if high_match is set. |
| medium_match | No | SLA target value for medium priority (number, e.g. 7). |
| medium_measure | No* | SLA unit for medium. Required if medium_match is set. |
| low_match | No | SLA target value for low priority (number, e.g. 1). |
| low_measure | No* | SLA unit for low. Required if low_match is set. |
Measure Units:
| Value | Unit |
|---|---|
1 | min |
2 | hr |
3 | d |
4 | wk |
5 | mon |
6 | yr |
Returns:
{
"code": 200,
"desc": "success",
"response": {
"audience": 5
}
}
Update-Audience
POST https://vertask.com/api/requests/update-audience
Use this method to update an existing billing audience. Only fields included in the post will be updated. To clear a field, post it with an empty value. For SLA fields, always post the _match and _measure together — posting only one will clear the other. To remove an SLA target, post _match as empty.
Post Fields:
| Field | Required | Description |
|---|---|---|
| audience | Yes | The id of the audience to update. |
| name | No | A new name for the audience. Max 100 characters. Must be unique. Cannot be posted empty. |
| contact | No | A new main contact. Post empty to clear. |
| status | No | Active state. 1 = active, 0 = inactive. |
| SLA Fields — always post the _match and _measure together: | ||
| severe_match | No | Updated SLA target for severe (number). Post empty to clear. |
| severe_measure | No* | SLA unit for severe. Required if severe_match has a value. |
| critical_match | No | Updated SLA target for critical (number). Post empty to clear. |
| critical_measure | No* | SLA unit for critical. Required if critical_match has a value. |
| high_match | No | Updated SLA target for high (number). Post empty to clear. |
| high_measure | No* | SLA unit for high. Required if high_match has a value. |
| medium_match | No | Updated SLA target for medium (number). Post empty to clear. |
| medium_measure | No* | SLA unit for medium. Required if medium_match has a value. |
| low_match | No | Updated SLA target for low (number). Post empty to clear. |
| low_measure | No* | SLA unit for low. Required if low_match has a value. |
| First-Response SLA Fields — the target for the first agent reply. Same units. Post _response_match and _response_measure together. (Requires the first-response SLA columns to be installed.) | ||
| severe_response_match | No | First-response target for severe (number). |
| severe_response_measure | No* | Unit for the severe first-response target. |
| critical_response_match | No | First-response target for critical. |
| critical_response_measure | No* | Unit for the critical first-response target. |
| high_response_match | No | First-response target for high. |
| high_response_measure | No* | Unit for the high first-response target. |
| medium_response_match | No | First-response target for medium. |
| medium_response_measure | No* | Unit for the medium first-response target. |
| low_response_match | No | First-response target for low. |
| low_response_measure | No* | Unit for the low first-response target. |
Measure Units:
| Value | Unit |
|---|---|
1 | min |
2 | hr |
3 | d |
4 | wk |
5 | mon |
6 | yr |
Returns:
{
"code": 200,
"desc": "Changes saved",
"response": true
}
Get-Audience
GET https://vertask.com/api/requests/get-audience/3
Returns the full SLA configuration for one billing audience: name, contact, status, and per priority tier both the resolution target (resolution_match/resolution_measure) and the first-response target (response_match/response_measure). Measure units: 1=min 2=hr 3=d 4=wk 5=mon 6=yr. A match of 0 means no target set for that tier.
| Field | Description |
|---|---|
| id | The audience id, as the URL segment after /get-audience/. |
Returns:
{
"code": 200,
"desc": "Audience found",
"response": {
"id": 3,
"name": "Contoso",
"contact": "[email protected]",
"status": 1,
"measures": { "1":"minute","2":"hour","3":"day","4":"week","5":"month","6":"year" },
"sla": {
"severe": { "resolution_match": 4, "resolution_measure": 2, "response_match": 30, "response_measure": 1 },
"critical": { "resolution_match": 8, "resolution_measure": 2, "response_match": 1, "response_measure": 2 },
"high": { "resolution_match": 1, "resolution_measure": 3, "response_match": 2, "response_measure": 2 },
"medium": { "resolution_match": 2, "resolution_measure": 3, "response_match": 4, "response_measure": 2 },
"low": { "resolution_match": 5, "resolution_measure": 3, "response_match": 8, "response_measure": 2 }
}
}
}
Get-Business-Hours
GET https://vertask.com/api/requests/get-business-hours
The company support-hours the SLA engine uses to walk minute/hour targets across working time. open/close are minutes from midnight (0–1440) in timezone; null means closed that day. When enabled is 0, SLAs run on a 24/7 clock.
Returns:
{
"code": 200,
"desc": "Business hours",
"response": {
"enabled": 1,
"timezone": "America/New_York",
"days": {
"mon": { "open": 540, "close": 1020 },
"tue": { "open": 540, "close": 1020 },
"wed": { "open": 540, "close": 1020 },
"thu": { "open": 540, "close": 1020 },
"fri": { "open": 540, "close": 1020 },
"sat": { "open": null, "close": null },
"sun": { "open": null, "close": null }
}
}
}
Update-Business-Hours
POST https://vertask.com/api/requests/update-business-hours
Sets the SLA support hours. All fields optional — days you don't post keep their current value. Times accept either HH:MM (e.g. 09:00) or minutes from midnight (e.g. 540). An open day must have a close later than its open, otherwise it is stored as closed.
Post Fields:
| Field | Required | Description |
|---|---|---|
| enabled | No | 1 to count SLA time only during these hours, 0 for 24/7. |
| timezone | No | A PHP timezone identifier (e.g. America/New_York) or an attribute_timezones id. |
| {day}_open | No | Opening time for a day. day = mon,tue,wed,thu,fri,sat,sun. HH:MM or minutes. |
| {day}_close | No | Closing time for the day. |
| {day}_closed | No | Post 1 to mark that day fully closed (clears its open/close). |
Returns:
{ "code": 200, "desc": "Business hours saved", "response": true }
Get-Task-SLA
GET https://vertask.com/api/requests/get-task-sla/1149
The committed SLA state of a task: first-response and resolution targets, whether each is met/breached, whether the clock is paused (task on hold), and seconds remaining (negative = overdue). Prefers the committed SLA row; falls back to computing from the task's current audience + priority. has_sla is false when the task has no billing audience or no configured target.
| Field | Description |
|---|---|
| task | The task id (companyTaskID), as the URL segment after /get-task-sla/. |
Returns:
{
"code": 200,
"desc": "SLA state",
"response": {
"has_sla": true,
"paused": false,
"response": { "applicable": true, "responded": false, "remaining": 1740, "breached": false },
"resolution": { "applicable": true, "resolved": false, "remaining": 9600, "breached": false },
"task": 1149
}
}
Field Notes:
response.responded
response.on_time
resolution.resolved
*.remaining
paused
Get-Project-SLA
GET https://vertask.com/api/requests/get-project-sla/87
SLA health rolled up across all of a project's tickets (projects have no SLA of their own). Counts how many tickets are SLA-tracked, currently breached, currently paused (on hold), and were resolved on time — plus a plain count of open tickets past their due date.
| Field | Description |
|---|---|
| project | The project id, as the URL segment after /get-project-sla/. |
Returns:
{
"code": 200,
"desc": "Project SLA",
"response": {
"project": 87,
"sla_installed": true,
"tracked": 12,
"breached": 2,
"paused": 1,
"met": 7,
"open_overdue": 3
}
}
Get-Billing-Audiences
GET https://vertask.com/api/requests/get-audiences
GET https://vertask.com/api/requests/get-audiences/acme
Use this method to get a list of billing audiences available to this company. A billing audience is the "billed delegate" that can be attached to a project via the billto field. An optional URL segment performs a keyword search across first name, last name, and email. Results are paginated.
Optional Parameters:
{
"q": "search term",
"id": 42,
"page": 0
}
Parameter Notes:
q
id
page
Returns:
{
"code": 200,
"desc": "Billing audiences found",
"response": {
"total_rows": 12,
"rows": 12,
"page": 0,
"per_page": 50,
"total_pages": 1,
"audiences": [
{
"id": 42,
"fname": "Jane",
"lname": "Doe",
"name": "Jane Doe",
"email": "[email protected]"
},
{
...
...
}
]
}
}
Client methods
Get-Clients
GET https://vertask.com/api/requests/get-clients
Use this method to get a list of all clients.
Optional Parameters:
{
"q": "search term",
"status": 1,
"audience": 3,
"group": 7,
"page": 0
}
Parameter Notes:
q
status
audience
group
page
Returns:
{
"code": 200,
"desc": "Client users found",
"response": {
"total_rows": 87,
"rows": 50,
"page": 0,
"per_page": 50,
"total_pages": 2,
"clients": [
{
"id": 116,
"fname": "Paul",
"lname": "Nurse",
"username": "paul.admin",
"email": "[email protected]",
"status": 1,
"audience": 3,
"last_modified": "2022-12-09 23:30:02"
},
{
...
...
}
]
}
}
Get-Client
GET https://vertask.com/api/requests/get-client/13
Use this method to get details of a client. This method returns a json object with the details of the client provided
Returns:
{
"code": 200,
"desc": "Client found",
"response": {
"id": 13,
"status": 0,
"fname": "Paul",
"lname": "Nurse",
"username": "paul.nurse",
"email": "[email protected]",
"office_phone": "50012",
"mobile_phone": "",
"fax": "",
"job_title": "Sales",
"department": "200",
"office": "1001",
"address1": "1 Country Ln",
"address2": "",
"city": "Cleveland",
"state": "OH",
"country": "USA",
"zipcode": "44122",
"last_modified": "2022-12-09 23:30:02"
}
}
Get-Client-Contracts
GET https://vertask.com/api/requests/get-client-contracts/13
List the contracts linked to a client — the agreements they are the customer, billing contact or signatory on. This is the reverse of Get-Contract-Clients, and the client-side counterpart of Get-Property-Contracts.
Only contracts the calling agent can view are returned, so this never exposes a contract that Get-Contract would refuse. Contracts with no end date sort last. Dates are returned as null when unset rather than as 0000-00-00.
The contracts module must be enabled for the company. To link or unlink, use Update-Contract-Client and Update-Contract-Client-Delete.
Returns:
{
"code": 200,
"desc": "Contracts found",
"response": {
"client_id": 13,
"rows": 2,
"contracts": [
{
"id": 42,
"name": "Managed Services Agreement",
"relationship": "customer",
"start": "2026-01-01",
"end": "2026-12-31",
"cost": 1800,
"seller": "Acme Corp",
"linked": "2026-08-14 09:15:44"
},
{
...
...
}
]
}
}
Get-Client-Groups
GET https://vertask.com/api/requests/get-client-groups
Use this method to get a list of all client groups.
To search, pass a q query parameter. The search runs a full-text match against teamName, teamDesc, teamLocation, phone, and email. Results are ordered by relevance when a search term is provided.
GET https://vertask.com/api/requests/get-client-groups?q=vip
Returns:
{
"code": 200,
"desc": "Groups found",
"response": {
"rows": 10,
"groups": [
{
"id": 4,
"status": 1,
"group": "VIP Clients",
"desc": "High-priority client accounts",
"location": "New York, NY",
"phone": "212-555-0100",
"email": "[email protected]",
"creator": 3,
"date_created": "2023-04-11 09:22:00"
},
{
...
...
}
]
}
}
Get-Client-Group
GET https://vertask.com/api/requests/get-client-group/4
Use this method to get details on a client group. This method returns a json object with the details of the group provided.
Returns:
{
"code": 200,
"desc": "Group found",
"response": {
"id": 4,
"date_created": "2023-04-11 09:22:00",
"status": 1,
"name": "VIP Clients",
"desc": "High-priority client accounts",
"location": New York, NY,
"creator": 3,
"phone": "212-555-0100",
"email": "[email protected]",
"avatar": null
}
}
Get-Client-Group-Members
GET https://vertask.com/api/requests/get-client-group-members/4
Use this method to get a list of all clients in a group. This method returns a json object with the users in the group provided.
Returns:
{
"code": 200,
"desc": "Members found",
"response": {
"rows": 3,
"clients": [
{
"id": 12,
"status": 1,
"fname": "Jane",
"lname": "Doe",
"email": "[email protected]",
"office_phone": "312-555-0100",
"mobile_phone": "312-555-0199",
"job_title": "Procurement Manager",
"date_joined": "2023-05-02 14:10:33"
},
{
...
...
}
]
}
}
Create-Client
POST https://vertask.com/api/requests/create-client
Use this method to create a new client user. firstName and email are required. The client is created with a status of 0 (pending) and an invite_code is generated. Use Update-Client-Send-Invite to send the portal invite.
Post body:
{
"firstName": "Jane",
"lastName": "Doe",
"email": "[email protected]",
"username": "jdoe",
"ophone": "312-555-0100",
"mphone": "312-555-0199",
"job_title": "Procurement Manager",
"department": "Operations",
"office": "Chicago HQ",
"address": "123 Main St",
"city": "Chicago",
"state": "IL",
"country": "US",
"zip": "60601",
"audience": 1
}
Returns:
{
"code": 200,
"desc": "Client created",
"response": {
"client_id": 12,
"fname": "Jane",
"lname": "Doe",
"email": "[email protected]",
"status": 0,
"invite_code": "a3f9c..."
}
}
Update-Client
POST https://vertask.com/api/requests/update-client
Use this method to update a client user's details. firstName and email are required. To change the client status pass status as 2 to deactivate or 1/0 to restore a deactivated account. Omit status to leave it unchanged. If the email address is changed the client's status is automatically set to 0 (pending re-verification).
Post body:
{
"client": 12,
"firstName": "Jane",
"lastName": "Doe",
"email": "[email protected]",
"username": "jdoe",
"ophone": "312-555-0100",
"mphone": "312-555-0199",
"fax": "",
"job_title": "Procurement Manager",
"department": "Operations",
"office": "Chicago HQ",
"address": "123 Main St",
"city": "Chicago",
"state": "IL",
"country": "US",
"zip": "60601",
"audience": 1,
"status": 2
}
Returns:
{
"code": 200,
"desc": "Client updated",
"response": {
"client_id": 12,
"email": "[email protected]"
}
}
Update-Client-Send-Invite
POST https://vertask.com/api/requests/update-client-send-invite
Use this method to send or resend the portal invite email to a client. The invite link uses the client's existing invite_code and directs them to set up access to the client portal.
Post body:
{
"client": 12
}
Returns:
{
"code": 200,
"desc": "Invite sent",
"response": {
"client_id": 12,
"email": "[email protected]"
}
}
Update-Client-Note
POST https://vertask.com/api/requests/update-client-note
Use this method to save or update the authenticated agent's personal note about a client. Notes are per-agent — each agent has their own note on a client. If no note exists yet one will be created.
Post body:
{
"client": 12,
"note": "Prefers contact by email. Key account for Q3."
}
Returns:
{
"code": 200,
"desc": "Note saved",
"response": {
"client_id": 12
}
}
Contract methods
API methods to work with contracts. Contracts let you track agreements and their commercial terms, manage per-agent access, set renewal reminders and automation, attach versioned documents, link properties and workbooks, route approvals and signatures, track budget vs. actual spend, and run reports. All requests use Basic authentication and return the standard { code, desc, response } envelope. Read methods require view access on the contract; write methods require edit access.
Get-Contracts
GET https://vertask.com/api/requests/get-contracts
GET https://vertask.com/api/requests/get-contracts/renewal
List the contracts the calling agent can view. An optional URL segment (or q) keyword-searches name and seller. Supports filters and pagination. Each row includes normalized Annual Recurring Value (arv) and Monthly Recurring Cost (mrc).
Parameters:
| Parameter | Required | Description |
|---|---|---|
| q | No | Keyword search across name and seller (alt to URL segment). |
| active | No | 0 = inactive, 1 = active (omit for all). |
| expiry | No | expired | 30 | 60 | 90 — contracts ending in that window. |
| seller | No | Filter by seller name. |
| page | No | Page number, 1-based (default 1). |
| limit | No | Rows per page, default 50, max 200. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"total": 63,
"page": 1,
"limit": 50,
"contracts": [
{
"id": 42,
"name": "Acme SaaS Subscription",
"seller": "Acme Corp",
"cost": "12500.00",
"billing_period": "annual",
"arv": 12500.0,
"mrc": 1041.67,
"contract_start": "2024-01-01",
"contract_end": "2024-12-31",
"initial_date": "2022-01-01",
"active": 1,
"is_template": 0,
"creator": 116,
"auto_create_renewal_task": 1,
"renewal_days_warning": 60
},
{
...
...
}
]
}
}
Get-Contract
GET https://vertask.com/api/requests/get-contract/42
Return the full detail for a single contract, including normalized arv/mrc, related record counts, and the calling agent's access. The caller must hold view access.
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 42,
"name": "Acme SaaS Subscription",
"details": "Annual subscription covering 50 seats.",
"seller": "Acme Corp",
"cost": "12500.00",
"cost_monthly": "0.00",
"cost_actual": "3120.00",
"billing_period": "annual",
"arv": 12500.0,
"mrc": 1041.67,
"contract_start": "2024-01-01",
"contract_end": "2024-12-31",
"initial_date": "2022-01-01",
"active": 1,
"creator": 116,
"datenow": "2024-08-12 14:22:01",
"status_approval": "approved",
"renewal_days_warning": 60,
"auto_create_renewal_task": 1,
"is_template": 0,
"contract_template_id": 0,
"counts": {
"files": 3,
"links": 2,
"workbooks": 1,
"stakeholders": 4,
"reminders": 2
},
"can_view": 1,
"can_edit": 1
}
}
Create-Contract
POST https://vertask.com/api/requests/create-contract
Create a new contract. The calling agent is automatically granted view + edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| name | Yes | The contract name. |
| details | No | HTML-allowed details/description. |
| seller | No | Seller / vendor name. |
| cost | No | Contract value, e.g. 12500.00. |
| billing_period | No | annual | quarterly | monthly | one_time (default annual). |
| cost_monthly | No | Recurring monthly charge (budget tracking). |
| cost_actual | No | Actual spend to date (budget tracking). |
| contract_start | No | Start date, YYYY-MM-DD. |
| contract_end | No | End / renewal date, YYYY-MM-DD. |
| initial_date | No | Original agreement date, YYYY-MM-DD. |
| renewal_days_warning | No | Days before end to warn / auto-create a renewal (default 30). |
| auto_create_renewal_task | No | 1 to auto-create a renewal task as it nears expiry. |
| is_template | No | 1 to create the record as a reusable template. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 42
}
}
Update-Contract
POST https://vertask.com/api/requests/update-contract/42
Update an existing contract. Only fields included in the POST are changed. The calling agent must hold edit access. Accepts the same fields as Create-Contract , plus active (0|1).
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| name | No | New name. Cannot be posted empty. |
| … | No | Any create-contract field, plus active (0|1). |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 42
}
}
Update-Contract-Delete
POST https://vertask.com/api/requests/update-contract-delete/42
Archive a contract (sets active = 0). Pass purge=1 to permanently delete the contract and all of its child rows (files, permissions, reminders, links, workbooks, renewals, stakeholders) plus the physical attachment files. Edit access required. Purge cannot be undone.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| purge | No | 1 = hard-delete instead of archive. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 42,
"archived": 1
}
}
Get-Contract-Permissions
GET https://vertask.com/api/requests/get-contract-permissions/42
List the agents who have access to a contract. The caller must hold view or edit on the contract.
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"permissions": [
{
"id": 901,
"agent_id": 116,
"name": "Paul Nurse",
"view": 1,
"edit": 1
},
{
...
...
}
]
}
}
Update-Contract-Permission
POST https://vertask.com/api/requests/update-contract-permission/42
Grant, change, or remove an agent's access. Edit access required. Setting edit = 1 implies view = 1; setting both to 0 removes the permission.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| agent_id | Yes | Agent to grant/modify/remove. |
| view | No | 0 | 1. |
| edit | No | 0 | 1 (implies view = 1). |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"agent_id": 116,
"view": 1,
"edit": 1
}
}
Get-Contract-Reminders
GET https://vertask.com/api/requests/get-contract-reminders/42
List the reminders set on a contract. View access required.
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"reminders": [
{
"id": 812,
"remind_date": "2024-11-15",
"note": "Begin renewal negotiations",
"creator": 116,
"datenow": "2024-08-12 14:22:01"
},
{
...
...
}
]
}
}
Update-Contract-Reminders
POST https://vertask.com/api/requests/update-contract-reminders/42
Add or remove a reminder. Edit access required. To add, post remind_date (and optional note). To remove, post reminder_id with remove = 1.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| remind_date | Yes* | Add only — YYYY-MM-DD. |
| note | No | Add only — optional note. |
| reminder_id | Yes* | Remove only — id to delete. |
| remove | Yes* | Remove only — set to 1. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 812,
"contract_id": 42
}
}
Update-Contract-Billing
POST https://vertask.com/api/requests/update-contract-billing/42
Set the billing period. Edit access required. Returns the recomputed arv/mrc.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| billing_period | Yes | annual | quarterly | monthly | one_time. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"billing_period": "monthly",
"arv": 12000.0,
"mrc": 1000.0
}
}
Update-Contract-Budget
POST https://vertask.com/api/requests/update-contract-budget/42
Update budget figures. Edit access required. Any subset of cost, cost_monthly, cost_actual. Returns the saved values plus budget_remaining (cost − cost_actual).
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| cost | No | Contract value. |
| cost_monthly | No | Recurring monthly charge. |
| cost_actual | No | Actual spend to date. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"cost": "12500.00",
"cost_monthly": "0.00",
"cost_actual": "3120.00",
"budget_remaining": 9380.0
}
}
Get-Contract-Files
GET https://vertask.com/api/requests/get-contract-files/42
List the document attachments on a contract. View access required.
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"files": [
{
"id": 51,
"filename": "MSA-signed.pdf",
"version": "signed",
"notes": "Countersigned copy",
"file_size": 482113,
"file_type": "pdf",
"uploaded": "2024-08-12 14:22:01",
"uploaded_by": "Paul Nurse"
},
{
...
...
}
]
}
}
Create-Contract-File
POST https://vertask.com/api/requests/create-contract-file/42
Upload a document. Edit access required. The file is sent as Base64 (raw or data-URL). Max 25 MB. Allowed types: pdf, doc, docx, xls, xlsx, jpg, jpeg, png, gif, zip.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| filename | Yes | Original file name incl. extension. |
| file | Yes | Base64 or data-URL encoded bytes. |
| version | No | signed | draft | amended (default signed). |
| notes | No | Optional note. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 52,
"version": "signed"
}
}
Update-Contract-File
POST https://vertask.com/api/requests/update-contract-file/42
Edit the version and/or notes of an attachment. Edit access required.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| file_id | Yes | Attachment id. |
| version | No | signed | draft | amended. |
| notes | No | Note text. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 52
}
}
Update-Contract-File-Delete
POST https://vertask.com/api/requests/update-contract-file-delete/42
Delete an attachment (database row and physical file). Edit access required.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| file_id | Yes | Attachment id. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 52
}
}
Get-Contract-Links
GET https://vertask.com/api/requests/get-contract-links/42
List the properties/locations linked to a contract. View access required.
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"links": [
{
"id": 7,
"location_id": 310,
"location_name": "HQ Building",
"relationship": "lease",
"linked": "2024-08-12 14:22:01"
},
{
...
...
}
]
}
}
Update-Contract-Link
POST https://vertask.com/api/requests/update-contract-link/42
Link a property/location to the contract. Edit access required. The location must belong to the company. No-ops if already linked.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| entity_id | Yes | Location/property id. |
| relationship | No | lease | service | warranty | other (default lease). |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 7,
"contract_id": 42,
"location_id": 310,
"relationship": "lease"
}
}
Update-Contract-Link-Delete
POST https://vertask.com/api/requests/update-contract-link-delete/42
Unlink a property/location from the contract. Edit access required.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| location_id | Yes | Location/property id to unlink. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"location_id": 310
}
}
Get-Contract-Clients
GET https://vertask.com/api/requests/get-contract-clients/42
List the clients linked to a contract — for example the customer a service agreement is for, the billing contact, or the signatory. View access required.
Clients are end customers. For agent approvers and signers on a contract, see Get-Contract-Stakeholders instead. Links whose client has since been deleted are omitted.
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"clients": [
{
"id": 14,
"client_id": 208,
"client_name": "Dana Whitfield",
"email": "[email protected]",
"job_title": "Facilities Manager",
"relationship": "customer",
"linked": "2026-08-14 09:15:44"
},
{
...
...
}
]
}
}
Update-Contract-Client
POST https://vertask.com/api/requests/update-contract-client/42
Link a client to the contract. Edit access required. The client must belong to the company. No-ops if already linked, so the call is safe to retry.
Use Get-Clients to resolve a name or email address to a client id first.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| client_id | Yes | Client id to link. |
| relationship | No | customer | billing | signatory | other (default customer). |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 14,
"contract_id": 42,
"client_id": 208,
"relationship": "customer"
}
}
Update-Contract-Client-Delete
POST https://vertask.com/api/requests/update-contract-client-delete/42
Unlink a client from the contract. Edit access required. This removes the link only — the client record itself is not deleted.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| client_id | Yes | Client id to unlink. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"client_id": 208
}
}
Get-Contract-Workbooks
GET https://vertask.com/api/requests/get-contract-workbooks/42
List the workbooks linked to a contract. View access required.
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"workbooks": [
{
"id": 3,
"workbook_id": 88,
"assigned_by": 116,
"datenow": "2024-08-12 14:22:01"
},
{
...
...
}
]
}
}
Update-Contract-Workbook
POST https://vertask.com/api/requests/update-contract-workbook/42
Link a workbook to the contract. Edit access required.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| workbook_id | Yes | Workbook id. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 3,
"contract_id": 42,
"workbook_id": 88
}
}
Update-Contract-Workbook-Delete
POST https://vertask.com/api/requests/update-contract-workbook-delete/42
Unlink a workbook from the contract. Edit access required.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| workbook_id | Yes | Workbook id. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"workbook_id": 88
}
}
Get-Contract-Stakeholders
GET https://vertask.com/api/requests/get-contract-stakeholders/42
List the approval/sign-off stakeholders on a contract. View access required. Role is one of view, edit, approve, sign.
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"stakeholders": [
{
"id": 12,
"agent_id": 116,
"name": "Paul Nurse",
"role": "approve",
"approved_date": "2024-09-01 10:00:00",
"signature_date": null,
"notes": "Finance sign-off",
"task_id": 4501
},
{
...
...
}
]
}
}
Update-Contract-Stakeholder
POST https://vertask.com/api/requests/update-contract-stakeholder/42
Add or update a stakeholder. Edit access required. Grants the underlying view/edit access the role implies (never downgrades). approve/sign roles may also generate an approval task.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| agent_id | Yes | Agent to add as a stakeholder. |
| role | No | view | edit | approve | sign (default view). |
| notes | No | Optional note. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 12,
"contract_id": 42,
"agent_id": 116,
"role": "approve"
}
}
Update-Contract-Stakeholder-Approve
POST https://vertask.com/api/requests/update-contract-stakeholder-approve/42
Record an approval or signature. Allowed if the caller has edit, or is recording their own approval. Stamps the date and closes the linked approval task if present.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| agent_id | No | Defaults to the calling agent. |
| action | No | approve | sign (default approve). |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"agent_id": 116,
"action": "approve",
"date": "2024-09-01 10:00:00"
}
}
Update-Contract-Stakeholder-Delete
POST https://vertask.com/api/requests/update-contract-stakeholder-delete/42
Remove a stakeholder. Edit access required. Closes any linked approval task first.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| agent_id | Yes | Stakeholder agent id. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"agent_id": 116
}
}
Get-Contract-Renewals
GET https://vertask.com/api/requests/get-contract-renewals/42
List the renewal records for a contract. View access required.
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"renewals": [
{
"id": 21,
"status": "pending",
"task_id": 4502,
"datenow": "2024-10-01 06:00:00"
},
{
...
...
}
]
}
}
Update-Contract-Renewal
POST https://vertask.com/api/requests/update-contract-renewal/42
Create a renewal task for this contract immediately. Edit access required. Skips creation if a pending/in_progress renewal already exists.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"task_id": 4502,
"created": 1
}
}
Update-Contract-Check-Expiry
GET https://vertask.com/api/requests/update-contract-check-expiry
Sweep the company's active, auto-renewal contracts ending within the horizon and create renewal tasks, skipping any already in progress. This is the per-request companion to the all-companies cron.
Parameters:
| Parameter | Required | Description |
|---|---|---|
| days | No | Look-ahead window in days (default 90). |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"checked": 12,
"created": 3,
"skipped_existing": 2,
"horizon_days": 90
}
}
Get-Contract-Templates
GET https://vertask.com/api/requests/get-contract-templates
List the contract templates the agent can view.
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"templates": [
{
"id": 9,
"name": "Standard MSA",
"seller": "",
"cost": "0.00",
"billing_period": "annual"
},
{
...
...
}
]
}
}
Create-Contract-From-Template
POST https://vertask.com/api/requests/create-contract-from-template/9
Create a new live contract by copying a template. The new contract is granted to the caller as view + edit.
Post Fields:
| Field | Required | Description |
|---|---|---|
| template_id | Yes | Template contract id (URL segment). |
| name | No | Name for the new contract (defaults to '<template> (copy)'). |
| contract_start | No | Start date for the new contract, YYYY-MM-DD. |
| contract_end | No | End date for the new contract, YYYY-MM-DD. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"id": 43,
"template_id": 9
}
}
Update-Contract-Set-Template
POST https://vertask.com/api/requests/update-contract-set-template/42
Mark or unmark a contract as a reusable template. Edit access required.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | Contract id (URL segment). |
| is_template | Yes | 0 | 1. |
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"contract_id": 42,
"is_template": 1
}
}
Get-Contract-Reports
GET https://vertask.com/api/requests/get-contract-reports
List the available contract report definitions (the catalog).
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"reports": [
{
"key": "budget_variance",
"name": "Budget Variance",
"description": "Cost vs actual spend with variance % and status."
},
{
...
...
}
]
}
}
Get-Contract-Report
GET https://vertask.com/api/requests/get-contract-report/budget_variance
Run one report and return its rows. Permission-scoped at the query level — only contracts the agent can access are included. Valid keys come from get-contract-reports (e.g. expiration, spend_summary, spend_by_seller, active_inventory, pending_approvals, recent_additions, templates, document_status, budget_variance, full_data).
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"key": "budget_variance",
"name": "Budget Variance",
"columns": [
"Contract",
"Cost",
"Actual",
"Variance %",
"Status"
],
"rows": [
{
...
...
}
],
"summary": {
"over_budget": 2,
"on_track": 7,
"under_budget": 4
}
}
}
Get-Contract-Billing-Periods
GET https://vertask.com/api/requests/get-contract-billing-periods
Static lookup of the valid billing periods and their display labels.
Returns:
{
"code": 200,
"desc": "OK",
"response": {
"billing_periods": [
{
"value": "annual",
"label": "per Year"
},
{
"value": "quarterly",
"label": "per Quarter"
},
{
"value": "monthly",
"label": "per Month"
},
{
"value": "one_time",
"label": "One-time"
}
]
}
}
Knowledge Base methods
API methods to read and search knowledge base sections and pages. Only sections and pages the authenticated user has been granted access to are returned.
Get-KB-Sections
GET https://vertask.com/api/requests/get-kb-sections
Use this method to get a list of all knowledge base sections accessible to the authenticated user. Only active sections the user has been granted access to (directly or via a group) are returned.
To search sections, pass a q query parameter. Results are ordered by relevance when provided, otherwise alphabetically by title.
GET https://vertask.com/api/requests/get-kb-sections?q=onboarding
Returns:
{
"code": 200,
"desc": "Sections found",
"response": {
"rows": 5,
"sections": [
{
"id": 3,
"title": "Onboarding Guide",
"public_view": 1,
"can_edit": 1,
"date_created": "2023-06-01 08:00:00"
},
{
...
...
}
]
}
}
Get-KB-Section
GET https://vertask.com/api/requests/get-kb-section/3
Use this method to get details on a single knowledge base section. This method returns a json object with the details of the section provided.
Returns:
{
"code": 200,
"desc": "Section found",
"response": {
"id": 3,
"title": "Onboarding Guide",
"public_view": 1,
"can_edit": 1,
"date_created": "2023-06-01 08:00:00"
}
}
Get-KB-Pages
GET https://vertask.com/api/requests/get-kb-pages/3
Use this method to get a list of all pages within a knowledge base section. This method returns a json object with the pages in the section provided, ordered by sort order then date created.
Returns:
{
"code": 200,
"desc": "Pages found",
"response": {
"rows": 4,
"section_id": 3,
"pages": [
{
"id": 12,
"title": "Getting Started",
"sort_order": 1,
"date_created": "2023-06-01 08:10:00"
},
{
...
...
}
]
}
}
Get-KB-Page
GET https://vertask.com/api/requests/get-kb-page/12?section=3
Use this method to get the full content of a single knowledge base page. Both the page id (URL segment) and the section id (query parameter) are required. The details field contains the full HTML content of the page.
Returns:
{
"code": 200,
"desc": "Page found",
"response": {
"id": 12,
"title": "Getting Started",
"details": "<p>Welcome to the onboarding guide...</p>",
"section_id": 3,
"section_title": "Onboarding Guide",
"can_edit": 1,
"date_created": "2023-06-01 08:10:00"
}
}
Get-KB-Search
GET https://vertask.com/api/requests/get-kb-search/onboarding
Use this method to search across all knowledge base sections and pages accessible to the authenticated user. The search performs a full-text match against section titles, page titles, page content, and associated tags. Results are ordered by combined relevance score and limited to 32 results. Each result carries a numeric relevance score.
Two optional filters narrow the results: section_id restricts the search to a single KB section, and min_relevance drops pages scoring below a threshold — handy for cutting noise on broad searches or tightening a targeted lookup.
Query parameters:
| Param | Type | Description |
|---|---|---|
| section_id | int | Optional — restrict results to this KB section ID. Omit to search every accessible section. |
| min_relevance | number | Optional — return only pages whose combined relevance score is at or above this value. Default 0 (all scored matches). Use the relevance field in the response to calibrate the threshold. |
GET https://vertask.com/api/requests/get-kb-search/onboarding # search all sections
GET https://vertask.com/api/requests/get-kb-search/onboarding?section_id=3 # only within section 3
GET https://vertask.com/api/requests/get-kb-search/onboarding?min_relevance=2 # drop weak matches
GET https://vertask.com/api/requests/get-kb-search/vpn?section_id=3&min_relevance=1 # both filtersReturns:
{
"code": 200,
"desc": "Results found",
"response": {
"rows": 3,
"results": [
{
"section_id": 3,
"section_title": "Onboarding Guide",
"page_id": 12,
"page_title": "Getting Started",
"public_view": 1,
"relevance": 7.4213
},
{
...
...
}
]
}
}
Create-KB-Section
POST https://vertask.com/api/requests/create-kb-section
Use this method to create a new knowledge base section. The authenticated agent is automatically granted edit access to the new section.
Post body:
{
"title": "Onboarding Guide"
}
Returns:
{
"code": 200,
"desc": "Section created",
"response": {
"section_id": 3,
"title": "Onboarding Guide"
}
}
Update-KB-Section
POST https://vertask.com/api/requests/update-kb-section
Use this method to update a knowledge base section title. Optionally pass a comma-separated list of page ids in the pages field to set their sort order.
Post body:
{
"section": 3,
"title": "Onboarding Guide v2",
"pages": "12,15,9,22"
}
Returns:
{
"code": 200,
"desc": "Section updated",
"response": {
"section_id": 3,
"title": "Onboarding Guide v2"
}
}
Update-KB-Section-Delete
POST https://vertask.com/api/requests/update-kb-section-delete
Use this method to permanently delete a knowledge base section. This will also delete all pages, attachments, editor photos, and tags associated with the section. This action cannot be undone.
Post body:
{
"kb": 3
}
Returns:
{
"code": 200,
"desc": "Section deleted"
}
Create-KB-Page
POST https://vertask.com/api/requests/create-kb-page
Use this method to create a new page within a knowledge base section. The title must not be identical to the most recently created page in the same section.
Post body:
{
"kb": 3,
"title": "Getting Started"
}
Returns:
{
"code": 200,
"desc": "Page created",
"response": {
"page_id": 12,
"section_id": 3,
"title": "Getting Started"
}
}
Update-KB-Page
POST https://vertask.com/api/requests/update-kb-page
Use this method to update a knowledge base page title and content. A version is automatically saved before overwriting if the content has changed significantly. The details field accepts HTML content.
Post body:
{
"page": 12,
"title": "Getting Started",
"details": "<p>Welcome to the onboarding guide...</p>"
}
Returns:
{
"code": 200,
"desc": "Page updated",
"response": {
"page_id": 12,
"title": "Getting Started"
}
}
Update-KB-Page-Delete
POST https://vertask.com/api/requests/update-kb-page-delete
Use this method to permanently delete a knowledge base page. This will also delete all attachments, editor photos, and tags associated with the page. This action cannot be undone.
Post body:
{
"page": 12
}
Returns:
{
"code": 200,
"desc": "Page deleted"
}
Update-KB-Section-Clientportal
POST https://vertask.com/api/requests/update-kb-section-clientportal
Use this method to add or remove a knowledge base section from the client self-service portal. Pass set as 1 to enable or 0 to disable.
Post body:
{
"kb": 3,
"set": 1
}
Returns:
{
"code": 200,
"desc": "Section added to client portal",
"response": {
"section_id": 3,
"public_view": 1
}
}
Update-KB-Section-Permissions
POST https://vertask.com/api/requests/update-kb-section-permissions
Use this method to manage user and group permissions on a knowledge base section. Pass an action to specify the operation. This method only adds or removes the entries you provide and never affects other existing permissions.
For add-users and add-groups, pass ids as id|canEdit where canEdit is true or false. If the user or group already has access, only the canEdit value is updated. For remove-users and remove-groups, pass ids only.
Add users:
{
"kb": 3,
"action": "add-users",
"users": "25|true,30|false"
}
Remove users:
{
"kb": 3,
"action": "remove-users",
"users": "25,30"
}
Add groups:
{
"kb": 3,
"action": "add-groups",
"groups": "4|true,7|false"
}
Remove groups:
{
"kb": 3,
"action": "remove-groups",
"groups": "4,7"
}
Returns:
{
"code": 200,
"desc": "Users added"
}
Update-KB-Page-Tags
POST https://vertask.com/api/requests/update-kb-page-tags
Use this method to add and/or remove tags on a knowledge base page in a single request. Pass comma-separated tag ids in add and/or remove. Both fields are optional but at least one must be provided. Adding tags only creates the links — tags are not created. Removing tags only removes the links — tags remain in the company library.
Post body:
{
"page": 12,
"add": "44,45,46",
"remove": "41,42"
}
Returns:
{
"code": 200,
"desc": "Tags updated",
"response": {
"page_id": 12,
"added": 3,
"skipped": 0,
"removed": 2
}
}
Manufacturer methods
Manufacturer (mfgr) use and management methods. Each company keeps its own manufacturer list, and also sees a shared set of built-in global manufacturers. Global manufacturers are read-only: they appear in Get-Mfgrs with "global": true and cannot be updated, merged, or deleted through the API.
Get-Mfgrs
GET https://vertask.com/api/requests/get-mfgrs
GET https://vertask.com/api/requests/get-mfgrs/value
Use this method to get a list of all manufacturers available to your company (your own plus the shared globals). Add an optional id or term value to filter the list — a numeric value matches an id or any name/logo containing it, and a text value matches the name or logo.
Returns:
{
"code": 200,
"desc": "Manufacturers found",
"response": {
"rows": 3,
"mfgrs": [
{
"id": 1,
"mfgr": "Dell",
"logo": "https://cdn.example.com/dell.png",
"global": true
},
{
"id": 42,
"mfgr": "Globex",
"logo": "",
"global": false
},
{
"id": 51,
"mfgr": "Initech",
"logo": "",
"global": false
}
]
}
}
Create-Mfgr
POST https://vertask.com/api/requests/create-mfgr
Use this method to create a new manufacturer for your company.
Post Fields:
| Field | Required | Description |
|---|---|---|
| mfgr | Yes | The manufacturer name. Must be unique within your company and must not match a shared global name. |
| logo | No | A logo image URL for the manufacturer. |
Returns:
{
"code": 200,
"desc": "success",
"response": {
"mfgr": 52
}
}
Update-Mfgr
POST https://vertask.com/api/requests/update-mfgr
Use this method to update one of your company's manufacturers. Only fields included in the post are updated. To clear the logo, post it with an empty value. Shared globals cannot be updated.
Post Fields:
| Field | Required | Description |
|---|---|---|
| mfgr | Yes | The id of the manufacturer to update. |
| name | No | A new name for the manufacturer. Must be unique within your company. Cannot be posted empty. |
| logo | No | A new logo URL. Post empty to clear. |
Returns:
{
"code": 200,
"desc": "Changes saved",
"response": true
}
Update-Mfgr-Merge
POST https://vertask.com/api/requests/update-mfgr-merge
Use this method to merge one of your manufacturers into another. Every asset using the from manufacturer is moved to the into manufacturer, then the from manufacturer is deleted. Both must belong to your company; shared globals cannot be merged.
Post Fields:
| Field | Required | Description |
|---|---|---|
| from | Yes | The id of the manufacturer to remove. Its assets are reassigned, then it is deleted. |
| into | Yes | The id of the manufacturer to keep. Must be different from from. |
Returns:
{
"code": 200,
"desc": "Manufacturers merged",
"response": {
"merged_from": 42,
"merged_into": 51,
"assets_moved": 6
}
}
Delete-Mfgr
POST https://vertask.com/api/requests/delete-mfgr
Use this method to delete one of your company's manufacturers. Any of your assets still using it are left without a manufacturer (their manufacturer is cleared). To keep the manufacturer on those assets instead, use Update-Mfgr-Merge. Shared globals cannot be deleted.
Post Fields:
| Field | Required | Description |
|---|---|---|
| mfgr | Yes | The id of the manufacturer to delete. |
Returns:
{
"code": 200,
"desc": "Manufacturer deleted",
"response": {
"mfgr": 42,
"assets_unassigned": 3
}
}
Project methods
Create-Project
POST https://vertask.com/api/requests/create-project
Use this method to create a new project. If neither assigned nor groups is provided, the calling agent is automatically assigned to the new project so it is never orphaned.
Post Fields:
| Field | Required | Description |
|---|---|---|
| name | Yes | The project name / title. |
| details | No | HTML-allowed details or description of the project. |
| assigned | No | Comma-separated list of agent ids to assign (e.g. 116,204,318). |
| groups | No | Comma-separated list of group / team ids to assign (e.g. 7,12). |
| priority | No | Priority / severity level. One of 5 (low, default), 10 (medium), 15 (high), 20 (urgent), 25 (critical). |
| due_date | No | Due / target date, format YYYY-MM-DD. |
| billto | No | Billing audience / delegate id. See Get-Audiences to look one up. |
| status | No | Open state. 1 = open (default), 0 = closed. |
Returns:
{
"code": 200,
"desc": "success",
"response": {
"project": 87
}
}
Update-Project
POST https://vertask.com/api/requests/update-project
Use this method to update an existing project. Only fields included in the post are updated. To clear the due date or details, post the field with an empty value. The name field cannot be posted empty. The calling agent must have access to the project (be directly assigned, be in an assigned group, or be the original creator).
Post Fields:
| Field | Required | Description |
|---|---|---|
| project | Yes | The id of the project to update. |
| name | No | A new name for the project. Cannot be posted empty. |
| details | No | HTML-allowed details. Post empty to clear. |
| status | No | Open state. 1 = open, 0 = closed. Closing the project also stamps the close date. |
| priority | No | Priority / severity level. One of 5, 10, 15, 20, 25. |
| due_date | No | Due / target date, YYYY-MM-DD. Post empty to clear. |
| billto | No | Billing audience / delegate id. Use Update-Project-Billto for a single-purpose call. |
Returns:
{
"code": 200,
"desc": "Changes saved",
"response": true
}
Delete-Project
POST https://vertask.com/api/requests/update-project-delete
Use this method to permanently delete a project. This action cascades and removes all agent assignments, all group / team assignments, all bookmark (star) entries, and the project record itself. Any tasks that were attached to the project are detached (returned to the unassigned-project pool) rather than deleted. The calling agent must have access to the project. This action cannot be undone.
Post Fields:
| Field | Required | Description |
|---|---|---|
| project | Yes | The id of the project to delete. |
Returns:
{
"code": 200,
"desc": "Project deleted",
"response": true
}
Update-Project-Agent
POST https://vertask.com/api/requests/update-project-agent
Use this method to add or remove an agent on a project. Pass action=add (the default) to assign an agent, or action=remove to unassign one. The calling agent must have access to the project, and on add the agent being added must belong to the same company. On remove the project must retain at least one assignment (direct agent or group) — the call refuses to remove the last assignment so projects are never orphaned.
Post Fields:
| Field | Required | Description |
|---|---|---|
| project | Yes | The id of the project. |
| agent | Yes | The id of the agent to add or remove. |
| action | No | Either add (default) or remove. |
Returns:
{
"code": 200,
"desc": "Agent added",
"response": true
}
Update-Project-Group
POST https://vertask.com/api/requests/update-project-groups
Use this method to add or remove an agent group / team on a project. Pass action=add (the default) to assign a group, or action=remove to unassign one. The calling agent must have access to the project, and on add the group must belong to the same company. On remove the project must retain at least one assignment (direct agent or group) — the call refuses to remove the last assignment so projects are never orphaned.
Post Fields:
| Field | Required | Description |
|---|---|---|
| project | Yes | The id of the project. |
| group | Yes | The id of the agent group / team to add or remove. |
| action | No | Either add (default) or remove. |
Returns:
{
"code": 200,
"desc": "Group added",
"response": true
}
Update-Project-Bookmark
POST https://vertask.com/api/requests/update-project-bookmark
Use this method to bookmark (star) or un-bookmark a project for the calling agent. Bookmarks are per-agent — they affect only the calling agent's view of the project. The calling agent must have access to the project.
Post Fields:
| Field | Required | Description |
|---|---|---|
| project | Yes | The id of the project. |
| bookmark | No | Bookmark state. 1 = bookmark / star (default), 0 = remove the bookmark. |
Returns:
{
"code": 200,
"desc": "Bookmark added",
"response": {
"project": 87,
"bookmarked": 1
}
}
Update-Project-Billto
POST https://vertask.com/api/requests/update-project-billto
Use this method to set the billing audience (bill-to delegate) on a project. Post 0 to clear the current billto. The calling agent must have access to the project. This is a single-purpose alternative to setting billto via Update-Project. To look up valid billing audience ids, use Get-Billing-Audiences.
Post Fields:
| Field | Required | Description |
|---|---|---|
| project | Yes | The id of the project. |
| billto | Yes | The id of the billing audience / delegate. Post 0 to clear. |
Returns:
{
"code": 200,
"desc": "Billto updated",
"response": true
}
Get-Projects
GET https://vertask.com/api/requests/get-projects | GET https://vertask.com/api/requests/get-projects/roll out
List projects. Add a search term as a URL segment or as ?q= to full-text match the project name and details. Returns 50 per page.
Each row carries a live task rollup (tasks_total, tasks_done, tasks_open, tasks_overdue) and a health value derived from it, so a dashboard does not need a second call per project.
Query Parameters:
Post Fields:
| Field | Required | Description |
|---|---|---|
| q | No | Search term. Also accepted as a URL segment. |
| status | No | 0 closed or 1 open. Anything else is ignored. |
| priority | No | Priority tier to filter on. |
| start | No | Only projects due on or after this date (YYYY-MM-DD). |
| end | No | Only projects due on or before this date (YYYY-MM-DD). |
| id | No | Return a single project by id. |
| archived | No | 1 for archived projects, 0 to exclude them. |
| page | No | Zero-based page number. 50 rows per page. |
Returns:
{
"code": 200,
"desc": "Projects found",
"response": {
"total_rows": 12,
"rows": 12,
"page": 0,
"per_page": 50,
"projects": [
{
"id": 8,
"name": "Office 365 rollout",
"details": "Migrate all staff mailboxes",
"status": 1,
"priority": 15,
"due_date": "2026-09-30 17:00:00",
"billto": 4,
"creator": 2,
"archived": 0,
"created_at": "2026-06-01 10:04:11",
"closed_at": "",
"health": "on_track",
"tasks_total": 24,
"tasks_done": 9,
"tasks_open": 15,
"tasks_overdue": 2
}
]
}
}
Get-Project
GET https://vertask.com/api/requests/get-project/8
Get one project with its full rollup. Returns 400 if the project does not exist or the calling agent has no access to it — the two cases are deliberately not distinguished.
Adds counts and logged time that Get-Projects does not carry: agents_count, groups_count, phases_count, bookmarked, and time_logged as H:MM alongside time_seconds.
Returns:
{
"code": 200,
"desc": "Project found",
"response": {
"id": 8,
"name": "Office 365 rollout",
"details": "Migrate all staff mailboxes",
"status": 1,
"priority": 15,
"due_date": "2026-09-30 17:00:00",
"billto": 4,
"creator": 2,
"archived": 0,
"created_at": "2026-06-01 10:04:11",
"closed_at": "",
"bookmarked": true,
"health": "on_track",
"agents_count": 3,
"groups_count": 1,
"phases_count": 4,
"tasks_total": 24,
"tasks_done": 9,
"tasks_open": 15,
"tasks_overdue": 2,
"time_logged": "37:20",
"time_seconds": 134400
}
}
Get-Project-Tasks
GET https://vertask.com/api/requests/get-project-tasks/8
List the tasks grouped under a project, each with its phase and whether it is currently blocked by a dependency. phase_id and phase_name are null for tasks not assigned to a phase.
is_blocked is true when at least one incomplete task blocks this one; blocker_count is how many. Use Get-Project-Dependencies for the detail.
Returns:
{
"code": 200,
"desc": "Tasks found",
"response": {
"project": 8,
"rows": 24,
"tasks": [
{
"id": 1904,
"title": "Migrate finance mailboxes",
"details": "Batch 3",
"status": 1,
"priority": 15,
"due_date": "2026-09-12 17:00:00",
"created_at": "2026-06-04 09:00:00",
"phase_id": 12,
"phase_name": "Migration",
"is_blocked": true,
"blocker_count": 1
}
]
}
}
Get-Project-Agents
GET https://vertask.com/api/requests/get-project-agents/8
List the agents assigned to a project. id is the assignment row; agent_id is the agent. To change assignments use Update-Project-Agent.
Returns:
{
"code": 200,
"desc": "Agents found",
"response": {
"project": 8,
"rows": 3,
"agents": [
{
"id": 41,
"agent_id": 2,
"fname": "Paul",
"lname": "Nurse",
"assigned_at": "2026-06-01 10:05:02"
}
]
}
}
Get-Project-Groups
GET https://vertask.com/api/requests/get-project-groups/8
List the agent groups assigned to a project, with each group's member count. To change them use Update-Project-Groups.
Returns:
{
"code": 200,
"desc": "Groups found",
"response": {
"project": 8,
"rows": 1,
"groups": [
{
"id": 17,
"group_id": 5,
"name": "Service Desk",
"member_count": 6,
"assigned_at": "2026-06-01 10:05:40"
}
]
}
}
Get-Project-Phases
GET https://vertask.com/api/requests/get-project-phases/8
List a project's phases in display order, each with the number of tasks currently in it.
Phases are optional and depend on a schema migration. Where the table is absent this returns 200 with "desc": "Phases not available" and an empty array rather than an error, so a client can call it unconditionally.
Returns:
{
"code": 200,
"desc": "Phases found",
"response": {
"project": 8,
"rows": 4,
"phases": [
{
"id": 12,
"name": "Migration",
"color": "#6c757d",
"sort_order": 2,
"task_count": 9
}
]
}
}
Get-Project-Activity
GET https://vertask.com/api/requests/get-project-activity/8
The project audit trail, newest first — who did what and when. Paged; pass ?page= (zero-based).
Like phases, this degrades to an empty result with "desc": "Activity log not available" rather than failing when the log table is not installed.
Query Parameters:
Post Fields:
| Field | Required | Description |
|---|---|---|
| page | No | Zero-based page number. |
Returns:
{
"code": 200,
"desc": "Activity found",
"response": {
"project": 8,
"total_rows": 140,
"rows": 50,
"page": 0,
"activity": [
{
"id": 903,
"action": "task_added",
"details": "Migrate finance mailboxes",
"agent": "Paul Nurse",
"date": "2026-06-04 09:00:12"
}
]
}
}
Get-Project-Dependencies
GET https://vertask.com/api/requests/get-project-dependencies/1904
Both sides of a task's dependencies. Note the URL segment is a task id, not a project id — dependencies are held per task.
blocked_by lists tasks that must finish first; blocking lists tasks waiting on this one. is_blocked is true when any entry in blocked_by is still incomplete. Each entry carries a dep_id, which is what Update-Project-Dependencies removes.
Returns:
{
"code": 200,
"desc": "Dependencies found",
"response": {
"task_id": 1904,
"blocked_by": [
{ "dep_id": 31, "task_id": 1888, "title": "Provision licences", "status": 1 }
],
"blocking": [
{ "dep_id": 34, "task_id": 1921, "title": "Decommission old server", "status": 1 }
],
"is_blocked": true
}
}
Get-Project-Billto
GET https://vertask.com/api/requests/get-project-billto | GET https://vertask.com/api/requests/get-project-billto/acme
List the billing audiences a project can be assigned to, for populating a picker. Add a search term as a URL segment or ?q=. Paged, 50 per page.
The id returned here is what Update-Project-Billto expects, and what appears as billto on Get-Project.
Query Parameters:
Post Fields:
| Field | Required | Description |
|---|---|---|
| q | No | Search term. Also accepted as a URL segment. |
| page | No | Zero-based page number. 50 rows per page. |
Returns:
{
"code": 200,
"desc": "Records found",
"response": {
"total_rows": 6,
"rows": 6,
"page": 0,
"per_page": 50,
"total_pages": 1,
"audiences": [
{
"id": 4,
"fname": "Acme",
"lname": "Corp",
"name": "Acme Corp",
"email": "[email protected]"
}
]
}
}
Get-Project-SLA
GET https://vertask.com/api/requests/get-project-sla/8
An SLA rollup across every ticket in the project. Check sla_installed first — when it is false the SLA tables are not present and every counter is zero.
open_overdue is counted from ticket due dates rather than SLA rows, so it is meaningful even where no SLA target is committed.
Returns:
{
"code": 200,
"desc": "Project SLA",
"response": {
"project": 8,
"sla_installed": true,
"tracked": 18,
"breached": 2,
"paused": 1,
"met": 9,
"open_overdue": 3
}
}
Update-Project-Phases
POST https://vertask.com/api/requests/update-project-phases
One endpoint for all phase operations. action selects which, and the other required fields depend on it.
Post Fields:
| Field | Required | Description |
|---|---|---|
| project | Yes | Project id. |
| action | Yes | create | update | delete | assign. Anything else returns 400. |
| name | create: Yes update: No | Phase name. On update, send name and/or color; sending neither returns 400. |
| color | No | Hex colour. Defaults to #6c757d on create. |
| phase_id | update / delete: Yes assign: No | The phase to act on. On assign, omit it or send 0 to clear a task's phase. |
| task_id | assign: Yes | The task to move into the phase. |
Returns:
{ "code": 200, "desc": "Phase created", "response": { "phase_id": 12 } }
{ "code": 200, "desc": "Phase updated", "response": true }
{ "code": 200, "desc": "Phase deleted", "response": true }
{ "code": 200, "desc": "Task phase updated", "response": true }
Update-Project-Archive
POST https://vertask.com/api/requests/update-project-archive
Archive or restore a project. Archiving hides it from the default project list without deleting anything — to remove a project use Delete-Project.
archive defaults to 1, so a call omitting it archives. Send archive=0 to restore.
Post Fields:
| Field | Required | Description |
|---|---|---|
| project | Yes | Project id. |
| archive | No | 1 to archive (default), 0 to restore. |
Returns:
{
"code": 200,
"desc": "Project archived",
"response": { "project": 8, "archived": 1 }
}
Update-Project-Dependencies
POST https://vertask.com/api/requests/update-project-dependencies
Add or remove a "task A cannot start until task B is done" link. action selects which.
Adding is validated: both tasks must exist in the company, a task cannot depend on itself, the same pair cannot be linked twice, and a link that would create a circular dependency is rejected. Each returns 400 with the reason.
Post Fields:
| Field | Required | Description |
|---|---|---|
| action | Yes | add or remove. |
| task_id | add: Yes | The task that is blocked. |
| blocked_by | add: Yes | The task that must finish first. |
| dep_id | remove: Yes | The dependency row id, from Get-Project-Dependencies. |
Returns:
{ "code": 200, "desc": "Dependency added", "response": { "dep_id": 31 } }
{ "code": 200, "desc": "Dependency removed", "response": true }
Property methods
Property methods
API methods to work with properties (locations/sites). Sites hold address, contact, and network details, and act as anchors for assets, clients, and tags. Tag, asset, and client links live in separate pivot tables and are managed by the update-property-tags, update-property-assets, and update-property-clients endpoints.
Get-Properties (GET)
GET https://vertask.com/api/requests/get-properties
Returns a paginated list of active properties/locations for the company. When a search term is provided, results are ordered by relevance; otherwise the order and sort parameters control ordering. The task_count field reflects how many tasks have been linked to each location.
Parameters:
| Value | Type | Description |
|---|---|---|
| q | string | Filter across name, address, city, state, phone, fax, URL, IP, and notes fields. |
| order | string |
Column to order by when no search term is provided.
"name" (default)"address""city""state""phone" |
| sort | string | Sort direction. "asc" (default) or "desc". |
| page | int | Zero-based page number. Defaults to 0. 20 results per page. |
Returns
{
"code": 200,
"desc": "Results",
"response": {
"locations": [
{
"id": 4,
"name": "Chicago HQ",
"address": "123 Main St",
"city": "Chicago",
"state": "IL",
"phone": "312-555-0100",
"phone2": "",
"office_number": "CHI-01",
"task_count": 17
}
],
"total": 12,
"page": 0,
"per_page": 20,
"total_pages": 1
}
}
Get-Property
GET https://vertask.com/api/requests/get-property/4
Use this method to get the full details of a property. This method returns a json object with all the details of the property provided.
Returns:
{
"code": 200,
"desc": "Site found",
"response": {
"id": 4,
"status": 6,
"name": "HQ",
"office_number": "0001",
"last_modified": "2021-12-09 01:00:05",
"location_address1": "1 Industry Dr",
"location_address2": null,
"city": "Cleveland",
"state": "OH",
"zip": "44125",
"location_phone1": "216-123-4567",
"location_phone2": null,
"location_fax1": null,
"location_fax2": null,
"location_url1": null,
"location_url2": null,
"location_hours": null,
"location_details": "Parking in the rear, smart card entry",
"network_details": "Network facility on second floor"
}
}
Create-Site
POST https://vertask.com/api/requests/create-property
Use this method to create a new property. Only name is required; every other field is optional and defaults to empty. New properties default to active (status=1).
Post Fields:
| Field | Required | Description |
|---|---|---|
| name | Yes | The property name. |
| address1 | No | Street address line 1. |
| address2 | No | Street address line 2. |
| city | No | City. |
| state | No | State / province. |
| zip | No | Postal / zip code. |
| country | No | Country. |
| phone1 | No | Primary phone. |
| phone2 | No | Secondary phone. |
| fax1 | No | Primary fax. |
| fax2 | No | Secondary fax. |
| url1 | No | Primary URL. |
| url2 | No | Secondary URL. |
| ip1 | No | Primary IP / network address. |
| ip2 | No | Secondary IP / network address. |
| details | No | HTML-allowed general details. |
| network_details | No | HTML-allowed network notes (servers, switches, VLANs, etc.). |
| office_number | No | Free-form office / branch code identifier. |
| status | No | Active state. 1 = active (default), 0 = inactive. |
Returns:
{
"code": 200,
"desc": "success",
"response": {
"property": 312
}
}
Update-Property
POST https://vertask.com/api/requests/update-property
Use this method to update an existing property. Only fields included in the post are updated. To clear a string field, post it with an empty value. The name field cannot be posted empty.
Post Fields:
| Field | Required | Description |
|---|---|---|
| property | Yes | The id of the property to update. |
| name | No | New property name. Cannot be posted empty. |
| address1 | No | Street address line 1. |
| address2 | No | Street address line 2. |
| city | No | City. |
| state | No | State / province. |
| zip | No | Postal / zip code. |
| country | No | Country. |
| phone1 | No | Primary phone. |
| phone2 | No | Secondary phone. |
| fax1 | No | Primary fax. |
| fax2 | No | Secondary fax. |
| url1 | No | Primary URL. |
| url2 | No | Secondary URL. |
| ip1 | No | Primary IP / network address. |
| ip2 | No | Secondary IP / network address. |
| details | No | HTML-allowed general details. Post empty to clear. |
| network_details | No | HTML-allowed network notes. Post empty to clear. |
| office_number | No | Free-form office / branch code identifier. |
| status | No | Active state. 1 = active, 0 = inactive (soft-archived). |
Returns:
{
"code": 200,
"desc": "Changes saved",
"response": true
}
Update-Property-Delete
POST https://vertask.com/api/requests/update-property-delete
Use this method to permanently delete a property. This action cascades and removes all asset assignments, client assignments, tag assignments, task references, export-queue entries, and recently-viewed entries for the property, then deletes the property record itself. This action cannot be undone. To soft-archive a property without deleting it, use Update-Property with status=0 instead.
Post Fields:
| Field | Required | Description |
|---|---|---|
| property | Yes | The id of the property to delete. |
Returns:
{
"code": 200,
"desc": "Site deleted",
"response": true
}
Update-Property-Tags
POST https://vertask.com/api/requests/update-property-tags
Use this method to add or remove a tag on a property. Pass action=add (the default) to assign a tag, or action=remove to unassign one. The tag must already exist in this company. On add, returns a 400 if the tag is already assigned. On remove, returns a 400 if the tag isn't currently assigned.
Post Fields:
| Field | Required | Description |
|---|---|---|
| property | Yes | The id of the property. |
| tag | Yes | The id of an existing tag. |
| action | No | Either add (default) or remove. |
Returns:
{
"code": 200,
"desc": "Tag added",
"response": true
}
Update-Property-Assets
POST https://vertask.com/api/requests/update-property-assets
Use this method to add or remove an asset at a property. Pass action=add (the default) to assign an asset, or action=remove to unassign one. The asset must belong to the same company. On add, returns a 400 if the asset is already at the property. On remove, returns a 400 if the asset isn't currently at the property.
Post Fields:
| Field | Required | Description |
|---|---|---|
| property | Yes | The id of the property. |
| asset | Yes | The id of the asset. |
| action | No | Either add (default) or remove. |
Returns:
{
"code": 200,
"desc": "Asset added",
"response": true
}
Update-Property-Clients
POST https://vertask.com/api/requests/update-property-clients
Use this method to add or remove a client at a property. Pass action=add (the default) to assign a client, or action=remove to unassign one. The client must belong to the same company. On add, returns a 400 if the client is already at the property. On remove, returns a 400 if the client isn't currently at the property.
Post Fields:
| Field | Required | Description |
|---|---|---|
| property | Yes | The id of the property. |
| client | Yes | The id of the client. |
| action | No | Either add (default) or remove. |
Returns:
{
"code": 200,
"desc": "Client added",
"response": true
}
Get-Property-Clients
GET https://vertask.com/api/requests/get-property-clients/4
Lists the clients / tenants assigned to a property, including the contact role, the is_primary flag and per-link notes. Primary contact is returned first.
Returns:
{
"code": 200,
"desc": "Client found",
"response": {
"rows": 1,
"location_id": 4,
"clients": [
{
"id": 53,
"name": "Jane Doe",
"fname": "Jane",
"lname": "Doe",
"email": "[email protected]",
"office_phone": "216-555-0100",
"mobile_phone": "",
"role": "tenant",
"is_primary": true,
"notes": "Lease holder, unit 4B"
}
]
}
}Update-Property-Client-Role
POST https://vertask.com/api/requests/update-property-client-role
Sets the role, primary flag and/or notes for a client already assigned to a property. (Assign/unassign the client itself with Update-Property-Clients.) Setting is_primary=1 clears the primary flag on the property's other contacts. At least one of role, is_primary or notes must be provided.
Post Fields:
| Field | Required | Description |
|---|---|---|
| property | Yes | The id of the property. |
| client | Yes | The id of the client (already assigned to the property). |
| role | No | tenant | owner | contractor | vendor | property_manager | other |
| is_primary | No | 1 to make this the primary contact, 0 to clear. |
| notes | No | Free-text note for this contact link. |
Returns:
{ "code": 200, "desc": "Contact updated", "response": true }Get-Property-Tags
GET https://vertask.com/api/requests/get-property-tags/4
Lists the tags assigned to a property. Companion to Update-Property-Tags (add/remove).
Returns:
{
"code": 200,
"desc": "Tags found",
"response": {
"rows": 2,
"location_id": 4,
"tags": [
{ "id": 7, "name": "fix" },
{ "id": 12, "name": "priority" }
]
}
}Get-Property-Files
GET https://vertask.com/api/requests/get-property-files/4
Lists the documents and photos attached to a property. Returns active files only. Each row includes a download_url that streams the binary through Get-Property-File. Optionally filter to one category.
Parameters:
| Value | Type | Description |
|---|---|---|
| category | string | Optional filter: photo | inspection | deed | tax | insurance | lease | document | other. |
Returns:
{
"code": 200,
"desc": "File found",
"response": {
"rows": 1,
"location_id": 4,
"files": [
{
"id": 201,
"category": "inspection",
"title": "2024 Roof Inspection",
"original_name": "roof-2024.pdf",
"mime_type": "application/pdf",
"file_ext": "pdf",
"file_size": 482931,
"is_image": false,
"notes": "",
"uploaded_by": 5,
"uploaded": "2024-09-01 14:22:10",
"download_url": "https://api.example.com/get-property-file/201"
}
]
}
}Get-Property-File
GET https://vertask.com/api/requests/get-property-file/201
Streams the raw bytes of a single property file (not JSON). The response carries the file's real Content-Type; add ?download=1 to force a download instead of inline display. Scoped to the calling company. On error this returns a normal JSON error envelope (e.g. 404).
Create-Property-File
POST https://vertask.com/api/requests/create-property-file (multipart/form-data)
Uploads a document or photo to a property. Send the binary in a multipart field named file. Accepted types: images (jpg, jpeg, png, gif, webp, heic, bmp), pdf, doc(x), xls(x), csv, ppt(x), txt, rtf, odt, ods, zip. Max 25 MB.
Post Fields:
| Field | Required | Description |
|---|---|---|
| property | Yes | The id of the property. |
| file | Yes | The upload, as a multipart file field named file. |
| category | No | photo | inspection | deed | tax | insurance | lease | document (default) | other. |
| title | No | Display title. Defaults to the uploaded file name. |
| notes | No | Optional note. |
Returns:
{ "code": 200, "desc": "File uploaded", "response": { "file": 201 } }Update-Property-Files
POST https://vertask.com/api/requests/update-property-files
Removes a document/photo from a property. The metadata row is soft-deleted and the stored file is removed from disk. (Upload with Create-Property-File.)
Post Fields:
| Field | Required | Description |
|---|---|---|
| property | Yes | The id of the property. |
| file | Yes | The id of the file to remove. |
| action | No | Only remove is supported (default). |
Returns:
{ "code": 200, "desc": "File removed", "response": true }Get-Property-Contracts
GET https://vertask.com/api/requests/get-property-contracts/4
Lists the contracts/leases linked to a property, with the relationship label (lease | service | warranty | other). Unset dates come back as null.
Returns:
{
"code": 200,
"desc": "Contract found",
"response": {
"rows": 1,
"location_id": 4,
"contracts": [
{
"id": 30,
"name": "Unit 4B Lease 2025",
"relationship": "lease",
"start": "2025-01-01",
"end": "2025-12-31",
"cost": 1500.00,
"seller": "Acme Realty",
"linked": "2025-01-03 09:10:00"
}
]
}
}Update-Property-Contracts
POST https://vertask.com/api/requests/update-property-contracts
Links or unlinks an existing contract to a property. The contract must already exist in this company (create it with your contracts endpoints first). On add, returns a 400 if it's already linked; on remove, a 400 if it isn't linked.
Post Fields:
| Field | Required | Description |
|---|---|---|
| property | Yes | The id of the property. |
| contract | Yes | The id of an existing contract. |
| action | No | add (default) or remove. |
| relationship | No | On add: lease (default) | service | warranty | other. |
Returns:
{ "code": 200, "desc": "Contract linked", "response": true }Get-Property-Inspections
GET https://vertask.com/api/requests/get-property-inspections/4
Lists the inspection checklists (workbooks) linked to a property, with their purpose (pre_movein | post_moveout | annual | inspection | other) and workbook status. Requires the Workbooks feature.
Returns:
{
"code": 200,
"desc": "Inspection found",
"response": {
"rows": 1,
"location_id": 4,
"inspections": [
{
"id": 9,
"name": "HQ — Annual (Sep 1, 2024)",
"purpose": "annual",
"status": 1,
"status_label": "Active",
"created": "2024-09-01 12:00:00",
"linked": "2024-09-01 12:05:00"
}
]
}
}Update-Property-Inspections
POST https://vertask.com/api/requests/update-property-inspections
Links or unlinks an existing workbook to a property as an inspection. The workbook must already exist in this company (to start a fresh copy from a template, clone it with your workbooks tools first, then link it). Unlinking removes only the property link — the workbook is never deleted. Requires the Workbooks feature.
Post Fields:
| Field | Required | Description |
|---|---|---|
| property | Yes | The id of the property. |
| workbook | Yes | The id of an existing workbook. |
| action | No | add (default) or remove. |
| purpose | No | On add: inspection (default) | pre_movein | post_moveout | annual | other. |
Returns:
{ "code": 200, "desc": "Inspection linked", "response": true }Get-Property-Health
GET https://vertask.com/api/requests/get-property-health/4
Returns a computed health score (0–100) for a property plus the metrics behind it. The score starts at 100 and is reduced by the factors below; it never drops below 0.
| Factor | Penalty | Max |
|---|---|---|
| Overdue open tasks | −10 each | −40 |
| Other open tasks (open minus overdue) | −2 each | −20 |
| Overdue maintenance schedules | −10 each | −30 |
| Expired asset warranties | −5 each | −15 |
| Warranties expiring within 60 days | −2 each | −10 |
| Leases expiring within 30 days | −10 each | −20 |
Bands: ≥80 → Good, ≥50 → Needs attention, <50 → At risk. Contacts, document counts and inspection counts are reported but do not change the score.
Returns:
{
"code": 200,
"desc": "Health computed",
"response": {
"location_id": 4,
"score": 78,
"label": "Needs attention",
"tasks": { "open": 6, "overdue": 2, "on_hold": 1 },
"contacts": { "total": 3 },
"assets": { "total": 9, "warranty_expired": 1, "warranty_expiring_60d": 2 },
"maintenance": { "active": 4, "overdue": 0, "next_run": "2025-04-01" },
"leases": { "total": 2, "expiring_30d": 0, "next_end": "2025-12-31" },
"inspections": { "total": 3 },
"documents": { "total": 12 }
}
}Task methods
API methods that work with helpdesk tasks
Get-Tasks
GET https://vertask.com/api/requests/get-tasks
Gets a list of tasks the current user has permissions to see. Returns a JSON array.
When a keyword search term is supplied (as a URL segment, e.g. /get-tasks/allstate, or via ?q=), each returned task also carries a cache field: a short plain-text snippet of the task's cached search text, centred on the match. The cache is drawn from the task's title, details, comments, assignees, assets, locations, tags, and OCR text extracted from attached images — so the snippet shows why a task matched even when the term never appears in its title. The cache field is omitted for plain (unfiltered) listings.
Query parameters:
| Param | Type | Description |
|---|---|---|
| q | string | Keyword search across title, details and the task's cached search text (comments, assignees, assets, locations, tags, OCR). May also be passed as a URL segment, e.g. /get-tasks/printer. |
| include_comments | int | 1 = also match live comment bodies for q. Default 0. |
| include_kb_matches | int | 1 = attach a kb_matches array to every returned task — related knowledge-base pages ranked by fulltext relevance to the task title, each with page_id, section_id, title and a numeric relevance score. Default 0. Only pages in KB sections the caller can access are returned (up to 5 per task); the array is empty when the KB feature is off or nothing matches. For performance the first 200 tasks of the result set are enriched. |
| status | int | Exact status: 0 Closed, 1 Open, 2 On Hold. |
| severity | int | Exact severity: 5 / 10 / 15 / 20 / 25. |
| severity_min | int | Return tasks at OR ABOVE this priority tier (5/10/15/20/25) — e.g. 15 = High, Critical and Severe. Use instead of severity for "this level and up". Ignored if an exact severity is supplied. |
| title | string | Title-only search (stacks with q). |
| duedate_start | string | YYYY-MM-DD — tasks due on or after this date. |
| duedate_end | string | YYYY-MM-DD — tasks due on or before this date. |
| project | int | Filter by project ID. |
| sort | string | Order results by one or more comma-separated keys, each field_direction. Fields: severity (alias priority), duedate, created, status, task. Directions: asc, desc. Example: sort=severity_desc,duedate_asc surfaces the most urgent tasks first. Undated tasks always sort last; unknown keys are ignored. |
| sort_by | string | REST-style ordering field (same field list as sort), paired with order. Equivalent to sort; if both are sent, sort wins. |
| order | string | asc or desc (default desc) — direction for sort_by. |
| overdue | int | 1 = return only tasks that are past their due date and still active (any priority). A closed task is never overdue. |
| focus | int | 1 = "my focus" smart-triage view — the caller's active (non-closed) tasks ranked overdue-first, then by severity, then soonest due. Pair with limit for the top N (defaults to 10). See also the dedicated Get-Tasks-Top endpoint. |
| limit | int | Max tasks to return, 1–1000. Defaults to 1000, or 10 when focus=1. |
| page | int | 1-based page number for paging large result sets; each page holds limit rows (offset = (page−1) × limit). |
| assigned | int | Agent ID — return tasks assigned to that agent (company-wide), e.g. a manager reviewing another agent's queue. Omit to use your own default scope. |
My focus (smart triage)
Pass focus=1 to get the calling agent's active (non-closed) tasks ranked for triage: overdue first, then by severity (Severe → Low), then soonest due. Pair with limit for the top N (defaults to 10). For a one-shot "give me my top N" call, use the dedicated Get-Tasks-Top endpoint instead.
GET https://vertask.com/api/requests/get-tasks?focus=1&limit=10 # my top 10 to triage
GET https://vertask.com/api/requests/get-tasks?sort=severity_desc,duedate_asc # most urgent first
GET https://vertask.com/api/requests/get-tasks?sort_by=severity&order=desc&limit=5 # same, REST-style
GET https://vertask.com/api/requests/get-tasks?overdue=1 # only past-due active tasks
GET https://vertask.com/api/requests/get-tasks?severity_min=15 # High and above
GET https://vertask.com/api/requests/get-tasks?assigned=42&status=1 # agent 42's open tasksResponse fields:
| Value | Type | Description |
|---|---|---|
| code | string | 200 is okay |
| desc | string | Task(s) found / not found |
| response | array | Array of agent information |
| rows | int | Total results found |
| tasks | array | Array of each task found |
| task | int | Task id |
| title | string | Name of the task |
| severity | int | Possible values:
|
| status | int | Possible values:
|
| duedate | string | Date the task is due (UTC time). Empty when no due date is set. |
| has_duedate | int | 1 when the task has a real due date; 0 when none is set (in which case duedate is empty). Use this to tell "no deadline" apart from a date value. |
| overdue | int | 1 when the task is past its due date and still active; 0 otherwise (always 0 for closed or undated tasks). Returned on every task. |
| cache | string | Search results only — a short plain-text snippet of the task's cached search text (title, details, comments, assignees, assets, locations, tags, and OCR from attached images) centred on the matched term. Omitted when no search term is supplied. |
| kb_matches | array | Only when include_kb_matches=1. Related knowledge-base pages for the task, ordered by descending relevance (max 5). Each item has page_id (int), section_id (int), title (string — the page title) and relevance (float — fulltext score). Empty array when the KB feature is off or nothing matches. |
Returns
{
"code": 200,
"desc": "Tasks found",
"response": {
"rows": 7,
"tasks": [
{
"task": 791,
"title": "This is a sample task",
"severity": 25,
"status": 1,
"duedate": "2025-11-29 01:16:05",
"has_duedate": 1,
"overdue": 1
},
{
"task": 887,
"title": "This is another test",
"severity": 10,
"status": 1,
"duedate": "",
"has_duedate": 0,
"overdue": 0
}
]
}
}Related KB pages (include_kb_matches)
Pass include_kb_matches=1 to surface the knowledge-base pages most relevant to each task in the same response — handy for "here's the task and the docs that might resolve it" without a second call to KB search. Each task gains a kb_matches array (up to 5 pages, most relevant first) built from a fulltext match on the task title against KB section titles, page titles/bodies and page tags. Only pages in sections the caller can access are included, and the array is empty when the KB feature is disabled or nothing scores.
GET https://vertask.com/api/requests/get-tasks?status=1&include_kb_matches=1 # open tasks + related KB pages
GET https://vertask.com/api/requests/get-tasks/printer%20offline?include_kb_matches=1 # search + related KB pagesReturns (each task carries a
kb_matchesarray)
{
"code": 200,
"desc": "Tasks found",
"response": {
"rows": 1,
"tasks": [
{
"task": 791,
"title": "Printer offline in the west office",
"severity": 15,
"status": 1,
"duedate": "2026-08-12 17:00:00",
"has_duedate": 1,
"overdue": 0,
"kb_matches": [
{ "page_id": 825, "section_id": 171, "title": "Resetting a network printer", "relevance": 9.4213 },
{ "page_id": 604, "section_id": 171, "title": "Printer troubleshooting checklist", "relevance": 5.1077 }
]
}
]
}
}Get-Tasks-Top
GET https://vertask.com/api/requests/get-tasks-top
Returns the caller's top N priority tasks in a single call, ranked server-side so the client never has to pull the full list and sort it. Ranking is fixed to the "my focus" order: overdue first, then by severity (Severe → Low), then soonest due. Only the caller's active (non-closed) tasks are considered.
This is a convenience wrapper over Get-Tasks with focus=1 pre-applied; every other Get-Tasks filter (overdue, severity_min, assigned, project, q, …) still works, and the response shape is identical (including the overdue and has_duedate fields).
Query parameters:
| Param | Type | Description |
|---|---|---|
| limit | int | Number of tasks to return, 1–1000. Defaults to 5. |
Examples
GET https://vertask.com/api/requests/get-tasks-top # my top 5 to work on next
GET https://vertask.com/api/requests/get-tasks-top?limit=10 # top 10Returns
Identical shape to Get-Tasks — a tasks array where each item has task, title, severity, status, duedate, has_duedate and overdue, already ordered most-urgent-first.
Task-KB-Reference
GET https://vertask.com/api/requests/task-kb-reference
Batch-matches the caller's open tasks against knowledge-base content by topic and returns the most relevant KB pages, with a relevance score, for each task — in a single call. This replaces the old multi-step workflow (list tasks, then a KB search per task — roughly 15 round-trips) with one request. Relevance and access scoping match Get-KB-Search: only pages in KB sections the caller can access are considered, and matching runs as a fulltext query over KB section titles, page titles/bodies and page tags. Requires the Knowledge Base feature; returns 503 when it is disabled.
Query parameters:
| Param | Type | Description |
|---|---|---|
| status | int | Which tasks to cross-reference: 1 Open (default), 2 On Hold, 0 Closed. |
| limit | int | Max tasks to scan, 1–200. Default 50. Tasks are taken most-urgent-first (severity desc), so a cap keeps the highest-priority ones. |
| per_task | int | Max KB pages returned per task, 1–10. Default 5. |
| min_relevance | number | Drop KB matches whose relevance score is below this threshold. Default 0 (keep every scored match). |
| assigned | int | Agent ID — cross-reference that agent's tasks company-wide instead of your own (e.g. a manager reviewing a queue). Omit to use your own scope. |
| project | int | Only cross-reference tasks in this project ID. |
| only_matched | int | 1 = return only tasks that matched at least one KB page. Default 0 (every scanned task is returned, with an empty kb_matches when nothing scored). |
Response fields:
| Value | Type | Description |
|---|---|---|
| rows | int | Number of tasks in results. |
| tasks_scanned | int | How many open tasks were cross-referenced (before only_matched filtering). |
| tasks_matched | int | Of those scanned, how many had at least one KB match. |
| results | array | One entry per task: task (int), title (string), severity (int), status (int) and kb_matches (array). |
| kb_matches | array | Related KB pages for the task, most relevant first (max per_task). Each item has page_id (int), section_id (int), title (string — the page title) and relevance (float — fulltext score). Empty when nothing matched. |
GET https://vertask.com/api/requests/task-kb-reference # my open tasks + related KB pages
GET https://vertask.com/api/requests/task-kb-reference?only_matched=1 # only tasks that have a KB match
GET https://vertask.com/api/requests/task-kb-reference?limit=25&per_task=3 # cap tasks scanned / matches per task
GET https://vertask.com/api/requests/task-kb-reference?assigned=42&status=2 # agent 42's on-hold tasksReturns
{
"code": 200,
"desc": "Cross-reference complete",
"response": {
"rows": 2,
"tasks_scanned": 2,
"tasks_matched": 1,
"results": [
{
"task": 791,
"title": "Printer offline in the west office",
"severity": 15,
"status": 1,
"kb_matches": [
{ "page_id": 825, "section_id": 171, "title": "Resetting a network printer", "relevance": 9.4213 },
{ "page_id": 604, "section_id": 171, "title": "Printer troubleshooting checklist", "relevance": 5.1077 }
]
},
{
"task": 812,
"title": "New hire onboarding for A. Diaz",
"severity": 10,
"status": 1,
"kb_matches": []
}
]
}
}Get-Tasks Search
GET https://vertask.com/api/requests/get-tasks/{search_term}
Returns a permission-filtered list of tasks. An optional {search_term} URL segment
performs a keyword search across task title and details. Any combination of the query-string
filters below can be appended to narrow results further — filters stack with each other
and with the keyword search.
Results are ordered by title relevance when a keyword is supplied, otherwise by task ID descending.
URL Segment
| Segment | Type | Description |
|---|---|---|
| search_term | string |
Keyword or phrase searched across task title and info.
Multi-word terms are split on whitespace — a task matches if any word appears
in either field. Special characters (- + " @) are stripped
automatically. URL-encode spaces as %20
(e.g. /get-tasks/fix%20printer). Omit the segment entirely to skip
keyword filtering.
|
Query-String Filters
| Parameter | Type | Description |
|---|---|---|
| status | int | Filter by exact task status:
0 – Closed1 – Open2 – On hold |
| severity | int | Filter by exact severity level:
5 – Low10 – Medium15 – High20 – Critical25 – Severe |
| title | string |
Search the title field only. Splits on whitespace and matches any
word. Stacks with the URL search_term — both must match.
|
| duedate_start | string |
Return only tasks with a due date on or after this date.
Format: YYYY-MM-DD. Tasks with no due date set
(0000-00-00) are excluded automatically.
|
| duedate_end | string |
Return only tasks with a due date on or before this date.
Format: YYYY-MM-DD. Tasks with no due date set are excluded automatically.
|
| project | int | Filter by project ID. |
| include_comments | int |
Set to 1 to widen the keyword search so it also matches text inside
task comments, not just the title and details. Use this when the thing you are
looking for might only appear in a comment thread (for example a fix or workaround posted
as a reply). Has no effect unless a search_term / q keyword is
also supplied. Default 0 (title + details only).
|
| q | string |
Alternative to the URL segment — pass the keyword as a query-string parameter
instead (e.g. /get-tasks?q=printer&status=1).
The URL segment takes priority if both are supplied.
|
Response values
Identical to Get-Tasks — see that section for the full field list.
Example requests
GET https://vertask.com/api/requests/get-tasks?status=1
GET https://vertask.com/api/requests/get-tasks/printer?status=1
GET https://vertask.com/api/requests/get-tasks?severity=15&duedate_end=2025-01-31
GET https://vertask.com/api/requests/get-tasks/network%20issue?status=1&severity=20
GET https://vertask.com/api/requests/get-tasks?title=login&project=4&status=2
GET https://vertask.com/api/requests/get-tasks/printer?include_comments=1
Returns
{
"code": 200,
"desc": "Tasks found",
"response": {
"rows": 2,
"tasks": [
{
"task": 812,
"title": "Printer offline on 3rd floor",
"severity": 10,
"status": 1,
"duedate": "2023-01-15 09:00:00",
"cache": "… Comment: rebooted the print spooler, printer still offline ;; OCR DATA: HP LaserJet error 49.4c02 …"
},
{
"task": 798,
"title": "Replace ink — HP printer lobby",
"severity": 5,
"status": 1,
"duedate": "0000-00-00 00:00:00",
"cache": "… Details: printer in the lobby is out of ink ;; Tag: printer …"
}
]
}
}Get-Task
GET https://vertask.com/api/requests/get-task/791
Gets details of a single task. The method returns a task JSON object.
Parameters:
| Value | Type | Description |
|---|---|---|
| code | string | 200 is okay |
| desc | string | Task(s) found / not found |
| response | array | Array of task information |
| id | int | Task ID |
| creator | int | ID of user who created the task |
| creator_type | int | Possible values:
|
| created | datetime | Date and time the task was created in UTC |
| severity | int | Possible values:
|
| resolution | string | Resolution ID (unique per company — see custom resolution settings page) |
| title | string | Title of the task |
| info | string | Details provided for the task |
| cache | string | Pre-rendered searchable text blob for the task — includes the title, details, status, resolution, comments, assigned agents/teams, impacted clients, assets, locations, tags, and OCR text extracted from any attached images/screenshots and comment files. Rebuilt on recache, so it may lag the live fields above. |
| duedate | string | Date and time the task is due in UTC |
| duedate_set_by | int | ID of the agent who set a due date |
| resolved | string | Date and time the task was resolved in UTC |
| resolved_by | int | ID of the agent who resolved |
| billto | int | Billing audience ID |
| project | int | Project ID |
Returns:
{
"code": 200,
"desc": "Task found",
"response": {
"id": 791,
"creator": 18,
"creator_type": 1,
"created": "2022-12-20 03:28:07",
"severity": 5,
"status": 0,
"resolution": 6,
"title": "This is the description of a sample task",
"info": "This is a sample task",
"cache": "[[ Type: Ticket ;; ID: 791 ;; Title: This is the description of a sample task ;; Details: This is a sample task ;; ... OCR DATA FROM EDITOR PHOTOS: Photo: 5a1f9c-photo.jpg ;; OCR DATA: Invoice #4021 total $350.00 ;; ... ]]",
"duedate": "0000-00-00 00:00:00",
"duedate_set_by": null,
"resolved": "2022-12-20 03:42:34",
"resolved_by": 18,
"billto": 0,
"project": 0
}
}Get-Task-Assets
GET https://vertask.com/api/requests/get-task-assets/795
Use this method to all assets link to a task. This method returns a json object with the list of assets.
Returns:
{
"code": 200,
"desc": "Assets found",
"response": {
"rows": 5,
"assets": {
"30": {
"asset": Fileserver1,
"type": "Server",
"mfgr": "Unknown",
"model": null,
"status": 1,
"created": "2022-09-24 19:51:18"
},
"35": {
...
...
}
}
}
}
Get-Task-Comments
GET https://vertask.com/api/requests/get-task-comments/340
Use this method to get all comments on a task. This method returns a json object with the comments.
Returns:
{
"code": 200,
"desc": "Comments found",
"response": {
"rows": 5,
"comments": [
{
"id": 268,
"task": 340,
"commentor_admin": 10,
"commentor_client": null,
"file": null,
"file_type": null,
"date": "2022-09-24 19:51:18",
"comment": "This is a comment",
"kb": null,
"private": 0
},
{
...
...
}
]
}
}
Get-Task-Members
GET https://vertask.com/api/requests/get-task-members/795
Use this method to get a list of all agents, clients and groups linked to a task. This method returns a json object with all members.
Returns:
{
"code": 200,
"desc": "Members found",
"response": {
"task": 795,
"agents": {
"18": {
"fname": "Paul",
"lname": "Nurse",
"email": "[email protected]",
"title": "IT Support",
"photo": "http://photo-path-here",
"last_login": "2022-12-09 23:30:02",
"status": 1
},
"10": {
...
...
}
},
"groups": {
"6": {
"team": "IT Support",
"team_desc": "IT memembers",
"date_created": "2019-07-03 01:08:43",
"status": 1
},
"2": {
...
...
}
},
"clients": {
"6": {
"fname": "Paul",
"lname": "Nurse",
"email": "[email protected]",
"photo": "http://photo-path-here",
"created": "2022-12-09 23:30:02",
"status": 1
},
"9": {
...
...
}
}
}
}
Get-Task-Tags
GET https://vertask.com/api/requests/get-task-tags/795
Use this method to get a list of all tags linked to a task. This method returns a json object with the tags.
Returns:
{
"code": 200,
"desc": "Results found",
"response": {
"task": 795,
"tags": {
"18": {
"tag": "accounting",
"created": "2022-12-09 23:30:02"
},
"29": {
...
...
}
}
}
}
Create-Task (POST)
POST https://vertask.com/api/requests/create-task
Creates a new task or ticket. All parameters are accepted as posted form-data. Only title is required.
Parameters:
| Value | Type | Description |
|---|---|---|
| title | string | Required. Task or ticket title. |
| type | int, string |
Whether to create a task or a ticket. Possible values:
"2" or "ticket" (default) – Ticket"1" or "task" – Task |
| clients | int, string | Client IDs or email addresses to link to this task. Comma-separate multiple values. |
| assets | int | Asset IDs to link to this task. Comma-separate multiple values. |
| assigned | int | Agent IDs to assign to this task. Comma-separate multiple values. Defaults to the calling agent if neither assigned nor group-assigned is provided. |
| group-assigned | int | Agent group IDs to assign to this task. Comma-separate multiple values. |
| priority | int, string |
Possible values:
"5" or "low" (default) – Low"10" or "medium" – Medium"15" or "high" – High"20" or "critical" – Critical"25" or "severe" – Severe |
| visible | int |
Possible values:
"0" (default) – Public"1" – Private |
| billto | int | Billing audience ID to tie to this task. |
| info | string | Details or task objectives. HTML is accepted. |
| project | int | Project ID to link to this task. |
| tags | int | Tag IDs to assign to this task. Comma-separate multiple values. |
| office | int | Office/location IDs to link to this task. Comma-separate multiple values. |
| duedate | string | Due date of the task. Format: YYYY-MM-DD HH:MM:SS. |
| resolution | int | Resolution ID to set on this task. Use Get-Resolutions to retrieve valid IDs for your company. |
| auto-create | int |
If a client in clients does not exist, auto-create them when an email address is provided.
"0" (default) – No"1" – Yes |
| auto-invite | int |
If a client is auto-created, send them an invite to the end-user portal.
"0" (default) – No"1" – Yes |
Returns
The created task/ticket ID (e.g. 795), or an error message if a problem occurred.
{
"0": 795
}
Update-Task (POST)
POST https://vertask.com/api/requests/update-task
Change task parameters, one or many at a time.
The method allows editing tasks you have access to. Parameters are accepted as posted form-data.
task is required with every request. Only submit the other parameters you want to
modify — omitting a parameter leaves its current value unchanged. Submitting an empty value for
a parameter will clear any existing value saved for that field.
Parameters:
| Value | Type | Description |
|---|---|---|
| task | int | Required. The task ID to update. |
| type | int, string |
Convert between task and ticket types:
"2" or "ticket" – Ticket"1" or "task" – Task |
| status | int |
Possible values:
"0" – Closed"1" (default) – Open"2" – On Hold |
| resolution | int | Resolution ID to set on this task. Use Get-Resolutions to retrieve valid IDs for your company. Submit empty to clear the current resolution. |
| title | string | Update the task title. Submitting an empty value returns an error — a title is always required. |
| clients | int, string | Add client IDs or email addresses to link to this task. Comma-separate multiple values. |
| assets | int | Add asset IDs to link to this task. Comma-separate multiple values. |
| assigned | int | Add agent IDs to assign to this task. Comma-separate multiple values. |
| group-assigned | int | Add agent group IDs to assign to this task. Comma-separate multiple values. |
| remove-assigned | int | Remove agent IDs from this task. Comma-separate multiple values. |
| remove-group-assigned | int | Remove agent group IDs from this task. Comma-separate multiple values. |
| priority | int, string |
Possible values:
"5" or "low" (default) – Low"10" or "medium" – Medium"15" or "high" – High"20" or "critical" – Critical"25" or "severe" – Severe |
| visible | int |
Possible values:
"0" (default) – Public"1" – Private |
| billto | int | Add or change the billing audience tied to this task. Submit empty to clear. |
| info | string | Add or change task details or objectives. HTML is accepted. Submit empty to clear. |
| project | int | Add or change the project ID linked to this task. Submit empty to remove from project. |
| tags | int | Add tag IDs to this task. Comma-separate multiple values. Submit empty to remove all tags. |
| office | int | Add office/location IDs to this task. Comma-separate multiple values. Submit empty to remove all offices. |
| duedate | string | Add or change the due date. Format: YYYY-MM-DD HH:MM:SS. Submit empty to clear. |
Returns
trueif there were no errors, or an error message otherwise.
{
"code": 200,
"desc": "Changes saved",
"response": true
}
Update-Task-Options (POST)
POST https://vertask.com/api/requests/update-task-options
Set one or more boolean option flags on a task. Parameters are accepted as posted form-data. task is required; submit only the options you want to change — omitting an option leaves its current value unchanged.
Unlike the toggle behaviour in the UI, the API requires an explicit value so that repeated calls are idempotent. The follow option applies to the calling agent only.
Parameters:
| Value | Type | Description |
|---|---|---|
| task | int | Required. The task ID to update. |
| block-client | int |
Block client(s) from viewing the task.
"0" – Off (default)"1" – On |
| follow | int |
Follow or unfollow the task as the calling agent.
"0" – Unfollow"1" – Follow (default) |
| visible | int |
Set the task visibility (private task).
"0" – Public (default)"1" – Private |
Returns the options that were changed and their new saved values, or an error message if a problem occurred.
{
"code": 200,
"desc": "Options updated",
"response": {
"block-client": 1,
"follow": 1,
"visible": 0
}
}
Update-Task-Add-Comment
POST https://vertask.com/api/requests/update-task-add-comment
Use this method to add a comment to a task. Comments can be set as private so that only agents can see them, or public so that clients can also see them.
Post body:
{
"task": 101,
"comment": "Please see the attached notes.",
"privacy": 0
}
Returns:
{
"code": 200,
"desc": "Comment added",
"response": {
"comment_id": 55,
"task_id": 101,
"date_created": "2024-03-01 10:22:00",
"private": 0
}
}
Update-Task-Delete-Comment
POST https://vertask.com/api/requests/update-task-delete-comment
Use this method to delete a comment from a task. Both the task id and the comment id must be provided. If the comment has an attachment it will also be removed.
Post body:
{
"task": 101,
"comment": 55
}
Returns:
{
"code": 200,
"desc": "Comment deleted"
}
Update-Tasks-Bulk (POST)
POST https://vertask.com/api/requests/update-tasks-bulk
Applies one set of field changes to many tasks in a single request — for example closing a batch of tickets, reassigning several tasks to one agent, or bumping the priority on a group of items. The body is sent as application/json. Only the fields you include are changed; any field you omit is left untouched on every task.
Each task is processed independently and is subject to the same permission rule as Update-Task: the caller must be the task creator, directly assigned to the task, a member of a team the task is assigned to, or the task must be public. Tasks that fail the permission check (or do not exist) are skipped and reported individually in the response, so a partial failure never blocks the rest. A maximum of 200 task ids may be sent per call.
This endpoint deliberately supports fewer fields than Update-Task — only the ones that make sense applied uniformly across many tasks. For richer single-task edits (title, tags, offices, clients, assets, type) call Update-Task per task.
Post body:
| Field | Type | Description |
|---|---|---|
| ids | array<int> | Required. Task ids to update. A comma-separated string is also accepted. At least one id, maximum 200. |
| status | int | Set task status on every id:
0 – Closed1 – Open2 – On hold |
| priority | string | Set severity on every id. Accepts a word (low, medium, high,
critical, severe) or the matching number (5, 10,
15, 20, 25). Unrecognised values default to low. |
| assigned | string | Comma-separated agent ids. Replaces the agent assignee set on each task (existing agent assignees are removed first, then the supplied agents are added). Each agent is validated against the company before linking. Send an empty value to clear all agent assignees. |
| duedate | string | Local date/time as YYYY-MM-DD HH:MM:SS; stored in UTC. Send an empty value to clear the due date. |
| resolution | int | Resolution id (validated against the company once, up front). Send 0 to clear the resolution. Typically paired with status: 0 when closing tasks. |
Post body:
{
"ids": [101, 102, 103],
"status": 0,
"resolution": 4
}
Returns:
{
"code": 200,
"desc": "3 of 3 task(s) updated",
"response": {
"requested": 3,
"updated": 3,
"failed": 0,
"results": [
{ "task": 101, "ok": true, "changed": ["status", "resolution"] },
{ "task": 102, "ok": true, "changed": ["status", "resolution"] },
{ "task": 103, "ok": true, "changed": ["status", "resolution"] }
]
}
}
A task that the caller cannot edit comes back as
{ "task": 104, "ok": false, "error": "You do not have permission to modify this task." }
while the rest still succeed.
Get-Resolutions (GET)
GET https://vertask.com/api/requests/get-resolutions
Returns a paginated list of all resolution types configured for your company. Use the returned id values when setting a resolution on a task via Create-Task or Update-Task.
Parameters:
| Value | Type | Description |
|---|---|---|
| q | string | Optional. Filter results by resolution name or description. |
| sort | string |
Sort order for results by name.
"asc" (default) – Ascending"desc" – Descending |
| page | int | Zero-based page number for pagination. Defaults to 0 (first page). 20 results are returned per page. |
Returns
A paginated list of resolution objects, along with pagination metadata.
{
"code": 200,
"desc": "Results",
"response": {
"resolutions": [
{
"id": 3,
"name": "Fixed",
"description": "Issue has been resolved",
"color": "#28a745",
"color_id": 7
}
],
"total": 5,
"page": 0,
"per_page": 20,
"total_pages": 1
}
}
Task-Tags (POST)
POST https://vertask.com/api/requests/task-tags
Add, remove, or replace the tags on a task. Use Get-Tags to look up valid tag IDs for your company. Parameters are accepted as posted form-data.
set is the most direct option when you want to define the exact final tag list.
When set is supplied, any add or remove values in the
same request are ignored — set always takes exclusive control.
Use add and remove together when you only want to make incremental changes.
Parameters:
| Value | Type | Description |
|---|---|---|
| task | int | Required. The task ID to modify. |
| add | int |
Tag IDs to add to the task. Comma-separate multiple values.
Tags already linked to the task are silently skipped.
Ignored when set is also supplied.
|
| remove | int |
Tag IDs to remove from the task. Comma-separate multiple values.
Tags not currently linked are silently skipped.
Ignored when set is also supplied.
|
| set | int |
Replaces all current tags on the task with this exact list.
Comma-separate multiple values. Pass an empty value (set=)
to clear all tags. When present, add and remove
are ignored.
|
Example requests
task=791&add=4,7
task=791&remove=7
task=791&add=12&remove=4
task=791&set=4,12
task=791&set=
Returns
On success, returns the tag IDs that were actually changed. Tags skipped (already added or not linked) are not included in the response.
{
"code": 200,
"desc": "Tags updated",
"response": {
"added": [4, 7],
"removed": [12]
}
}
{
"code": 200,
"desc": "Tags updated",
"response": {
"set": [4, 12]
}
}Get-Dashboard-Summary
GET https://vertask.com/api/requests/get-dashboard-summary
Returns a single aggregated snapshot of the calling agent's workload — built to answer the common opening questions ("what should I focus on?", "summarize my day", "what's overdue?", "what's due this week?") in one request instead of several separate task and contract list calls.
Tasks are scoped to the calling agent: assigned directly, assigned via a team the agent belongs to,
or created by the agent. Each bucket returns an exact count plus a capped list of up to
15 items. Contract data is included only when the Contracts module is enabled for the
account.
Query-String Parameters
| Parameter | Type | Description |
|---|---|---|
| period | string | Window for the "due soon" task bucket and the "expiring soon" contract horizon:
today – through end of today (contracts: 30 days)this_week (default) – next 7 days (contracts: 30 days)this_month – next 1 month (contracts: 60 days)Overdue is always measured relative to now, regardless of period. |
Response values
| Value | Type | Description |
|---|---|---|
| period | string | The period that was applied |
| now | datetime | Server time the snapshot was taken (UTC) |
| due_soon_through | datetime | Upper bound of the "due soon" window (UTC) |
| list_cap | int | Maximum items returned per bucket list (counts are always exact) |
| tasks.open | object | count + items — open tasks (status 1) |
| tasks.overdue | object | count + items — past due date, not closed |
| tasks.on_hold | object | count + items — on hold (status 2) |
| tasks.due_soon | object | count + items — due within the period window, not closed |
| tasks.high_priority | object | count + items — severity ≥ 15 (High/Critical/Severe), not closed |
| tasks.*.items[].task | int | Task id |
| tasks.*.items[].title | string | Task title |
| tasks.*.items[].severity | int | 5 Low / 10 Medium / 15 High / 20 Critical / 25 Severe |
| tasks.*.items[].status | int | 0 Closed / 1 Open / 2 On hold |
| tasks.*.items[].duedate | string | Due date (UTC), empty when none set |
| contracts_expiring | object | Present only when the Contracts module is enabled |
| contracts_expiring.horizon_days | int | How many days ahead "expiring" looked (30 or 60) |
| contracts_expiring.expiring_count | int | Exact count of active contracts expiring within the horizon |
| contracts_expiring.expiring[] | array | Up to 15 contracts, soonest first: id, name, contract_end, days_left |
Example requests
GET https://vertask.com/api/requests/get-dashboard-summary
GET https://vertask.com/api/requests/get-dashboard-summary?period=today
GET https://vertask.com/api/requests/get-dashboard-summary?period=this_month
Returns
{
"code": 200,
"desc": "Dashboard summary",
"response": {
"period": "this_week",
"now": "2026-06-16 14:05:00",
"due_soon_through": "2026-06-23 23:59:59",
"list_cap": 15,
"tasks": {
"open": { "count": 12, "items": [ ] },
"overdue": { "count": 3, "items": [
{ "task": 812, "title": "Printer offline on 3rd floor", "severity": 15, "status": 1, "duedate": "2026-06-10 09:00:00" }
] },
"on_hold": { "count": 1, "items": [ ] },
"due_soon": { "count": 4, "items": [ ] },
"high_priority": { "count": 5, "items": [ ] }
},
"contracts_expiring": {
"horizon_days": 30,
"expiring_count": 2,
"expiring": [
{ "id": 44, "name": "Acme support renewal", "contract_end": "2026-06-30", "days_left": 14 }
]
}
}
}Tasks Kanban methods
API methods for managing kanban boards, columns, and task cards. Kanban boards provide a drag-and-drop visual layer on top of existing tasks — no data duplication. A task can appear on a board only once. If no active board exists when get-kanban-board is called, one is auto-created with four default columns.
Get-Kanban-Board
GET https://vertask.com/api/requests/get-kanban-board
Fetches the active kanban board for the current company. Returns the board metadata, all columns in left-to-right order, and each column's tasks in top-to-bottom order. If no active board exists, one is auto-created with four default columns: To Do, In Progress, Review, Done.
Parameters:
| Value | Type | Description |
|---|---|---|
| code | string | 200 is okay |
| desc | string | Board found |
| response | object | Board and column data |
| board | object | Board metadata |
| board.id | int | Board ID |
| board.title | string | Board title |
| board.project_id | int|null | Project ID if board is tied to a project, null for standalone |
| board.creator_id | int | Agent ID who created the board |
| board.status | int | Possible values:
"1" – Active"0" – Closed |
| board.created | datetime | Date and time the board was created (UTC) |
| columns | array | Array of column objects, sorted by sort_order ascending |
| columns[].id | int | Column ID |
| columns[].title | string | Column title |
| columns[].color | string | Hex color code for column header (e.g. #0d6efd) |
| columns[].sort_order | int | Left-to-right position (0-based) |
| columns[].wip_limit | int|null | Maximum tasks allowed in this column, null if unlimited |
| columns[].tasks | array | Array of task objects in this column, sorted by sort_order ascending |
| columns[].tasks[].item_id | int | Kanban item ID (the board-card record) |
| columns[].tasks[].task_id | int | Task ID (references the task itself) |
| columns[].tasks[].title | string | Task title |
| columns[].tasks[].status | int | Possible values:
"0" – Closed"1" – Open"2" – On hold |
| columns[].tasks[].priority | int | Possible values:
"5" – Low"10" – Medium"15" – High"20" – Critical"25" – Severe |
| columns[].tasks[].duedate | string | Due date (UTC) |
| columns[].tasks[].sort_order | int | Vertical position within the column (0-based) |
Returns
{
"code": 200,
"desc": "Board found",
"response": {
"board": {
"id": 1,
"title": "Kanban Board",
"project_id": null,
"creator_id": 18,
"status": 1,
"created": "2025-06-01 12:00:00"
},
"columns": [
{
"id": 1,
"title": "To Do",
"color": "#6c757d",
"sort_order": 0,
"wip_limit": null,
"tasks": [
{
"item_id": 5,
"task_id": 791,
"title": "Fix login page CSS",
"status": 1,
"priority": 10,
"duedate": "2025-06-15 09:00:00",
"sort_order": 0
},
{
...
}
]
},
{
"id": 2,
"title": "In Progress",
"color": "#0d6efd",
...
}
]
}
}Get-Kanban-Columns
GET https://vertask.com/api/requests/get-kanban-columns/1
Use this method to get all columns belonging to a kanban board. Returns an array of column objects sorted by their display order.
Returns:
{
"code": 200,
"desc": "Columns found",
"response": {
"board": 1,
"rows": 4,
"columns": [
{
"id": 1,
"title": "To Do",
"color": "#6c757d",
"sort_order": 0,
"wip_limit": null
},
{
"id": 2,
"title": "In Progress",
"color": "#0d6efd",
"sort_order": 1,
"wip_limit": 5
},
{
...
}
]
}
}
Get-Kanban-Items
GET https://vertask.com/api/requests/get-kanban-items/1
Use this method to get all task items (cards) on a kanban board. Returns task details alongside their column placement and sort position.
Returns:
{
"code": 200,
"desc": "Items found",
"response": {
"board": 1,
"rows": 8,
"items": [
{
"item_id": 5,
"column_id": 1,
"column_title": "To Do",
"task_id": 791,
"title": "Fix login page CSS",
"status": 1,
"priority": 10,
"duedate": "2025-06-15 09:00:00",
"sort_order": 0,
"added_by": 18,
"added": "2025-06-01 12:30:00"
},
{
...
}
]
}
}
Create-Kanban-Column (POST)
POST https://vertask.com/api/requests/create-kanban-column
Add a new column to a kanban board. The column is appended at the end. Parameters are accepted as posted form-data.
Parameters:
| Value | Type | Description |
|---|---|---|
| board_id | int | Required. The board to add the column to. |
| title | string | Required. Column title (e.g. "QA Review"). |
| color | string | Hex color for the column header. Default: #6c757d. Format: #RRGGBB. |
| wip_limit | int | Maximum number of tasks allowed in this column. Set to 0 or omit to leave unlimited. |
Post body:
{
"board_id": 1,
"title": "QA Review",
"color": "#fd7e14",
"wip_limit": 3
}
Returns:
{
"code": 200,
"desc": "Column created",
"response": {
"column_id": 5,
"board_id": 1,
"title": "QA Review",
"color": "#fd7e14",
"sort_order": 4,
"wip_limit": 3
}
}
Update-Kanban-Column (POST)
POST https://vertask.com/api/requests/update-kanban-column
Update one or more properties on a kanban column. column_id is required; submit only the properties you want to change — omitting a property leaves its current value unchanged.
Parameters:
| Value | Type | Description |
|---|---|---|
| column_id | int | Required. The column to update. |
| title | string | New column title. |
| color | string | New hex color. Format: #RRGGBB. |
| wip_limit | int | New WIP limit. Set to 0 to remove the limit. |
Post body:
{
"column_id": 2,
"title": "In Development",
"wip_limit": 5
}
Returns:
{
"code": 200,
"desc": "Column updated"
}
Delete-Kanban-Column (POST)
POST https://vertask.com/api/requests/update-kanban-column-delete
Delete a column from a kanban board. Tasks in the deleted column are automatically moved to the first remaining column. The last column on a board cannot be deleted.
Parameters:
| Value | Type | Description |
|---|---|---|
| column_id | int | Required. The column to delete. |
| board_id | int | Required. The board the column belongs to. |
Post body:
{
"column_id": 5,
"board_id": 1
}
Returns:
{
"code": 200,
"desc": "Column deleted"
}
Reorder-Kanban-Columns (POST)
POST https://vertask.com/api/requests/update-kanban-column-reorder
Set the left-to-right display order of columns on a board. Pass all column IDs in the desired order.
Parameters:
| Value | Type | Description |
|---|---|---|
| board_id | int | Required. The board. |
| order | string | Required. Comma-separated column IDs in the new left-to-right order. |
Post body:
{
"board_id": 1,
"order": "3,1,2,4"
}
Returns:
{
"code": 200,
"desc": "Columns reordered"
}
Add-Kanban-Item (POST)
POST https://vertask.com/api/requests/create-kanban-item
Add an existing task to a kanban board as a card. The task is placed at the bottom of the target column. A task can only appear once per board — adding a task that is already on the board returns an error. Does not create a new task; use Create-Task first if needed.
Parameters:
| Value | Type | Description |
|---|---|---|
| board_id | int | Required. The board to add the task to. |
| task_id | int | Required. The task ID to add. |
| column_id | int | Target column. Defaults to the first column on the board if omitted. |
Post body:
{
"board_id": 1,
"task_id": 887,
"column_id": 2
}
Returns:
{
"code": 200,
"desc": "Task added to board",
"response": {
"item_id": 12,
"board_id": 1,
"column_id": 2,
"task_id": 887
}
}
Move-Kanban-Item (POST)
POST https://vertask.com/api/requests/update-kanban-item-move
Move a task to a different column and/or position on the board. WIP limits are enforced — the move is rejected if the target column is full.
Parameters:
| Value | Type | Description |
|---|---|---|
| board_id | int | Required. The board. |
| task_id | int | Required. The task to move. |
| column_id | int | Required. Target column. |
| position | int | Target vertical position within the column (0-based). Default: 0 (top). |
Post body:
{
"board_id": 1,
"task_id": 791,
"column_id": 3,
"position": 2
}
Returns:
{
"code": 200,
"desc": "Task moved"
}
Remove-Kanban-Item (POST)
POST https://vertask.com/api/requests/update-kanban-item-remove
Remove a task from the kanban board. This removes the card only — it does not delete the underlying task. The task can be re-added later via Add-Kanban-Item.
Parameters:
| Value | Type | Description |
|---|---|---|
| board_id | int | Required. The board. |
| task_id | int | Required. The task to remove from the board. |
Post body:
{
"board_id": 1,
"task_id": 791
}
Returns:
{
"code": 200,
"desc": "Task removed from board"
}
Reorder-Kanban-Items (POST)
POST https://vertask.com/api/requests/update-kanban-item-reorder
Set the vertical order of task cards within a column. All tasks listed in order are moved into the specified column_id and assigned sequential sort positions. WIP limits are enforced — the request is rejected if the number of tasks exceeds the column's limit. This is the primary endpoint used by drag-and-drop.
Parameters:
| Value | Type | Description |
|---|---|---|
| board_id | int | Required. The board. |
| column_id | int | Required. The target column. |
| order | string | Required. Comma-separated task IDs in the new top-to-bottom order. |
Post body:
{
"board_id": 1,
"column_id": 2,
"order": "887,791,812"
}
Returns:
{
"code": 200,
"desc": "Tasks reordered"
}
Tag methods
Tag use and management methods that work site wide.
Get-Tags
GET https://vertask.com/api/requests/get-tags
GET https://vertask.com/api/requests/get-tags/value
Use this method to get a list of all tags. This method returns a json object with all tags, or add an optional id or term value to only return the data for one tag.
Returns:
{
"code": 200,
"desc": "Tags found",
"response": {
"rows": 3,
"tags": [
{
"id": 1,
"tag": "Hardware",
"tagDesc": "Hardware related issues"
},
{
"id": 2,
"tag": "Network",
"tagDesc": "Network related issues"
},
{
"id": 3,
"tag": "Software",
"tagDesc": "Software related issues"
}
]
}
}
Create-Tag
POST https://vertask.com/api/requests/create-tag
Use this method to create a new tag.
Post Fields:
| Field | Required | Description |
|---|---|---|
| tag | Yes | The tag name. Must be unique within your company. |
| tagDesc | No | A description for the tag. |
Returns:
{
"code": 200,
"desc": "success",
"response": {
"tag": 4
}
}
Update-Tag
POST https://vertask.com/api/requests/update-tag
Use this method to update an existing tag. Only fields included in the post will be updated. To clear a field, post it with an empty value.
Post Fields:
| Field | Required | Description |
|---|---|---|
| tag | Yes | The id of the tag to update. |
| name | No | A new name for the tag. Must be unique within your company. Cannot be posted empty. |
| tagDesc | No | A new description for the tag. Post empty to clear. |
Returns:
{
"code": 200,
"desc": "Changes saved",
"response": true
}
Workbook methods
API methods to work with Workbooks — configurable matrices used for things like CMMC shared-responsibility tracking. A workbook owns fields (typed columns: text, textarea, select — each either a template reference column or an entry answer column), sections (row groups), and objectives (rows, each carrying a status and one value per field). Everything is company-scoped. The workbook creator always has edit access; other agents are granted view or edit access per workbook (see Workbook permission methods). These methods require the CMMC option to be enabled for the company.
Get-Workbooks
GET https://vertask.com/api/requests/get-workbooks
GET https://vertask.com/api/requests/get-workbooks/responsibility
Use this method to get a paginated list of workbooks the calling agent can access (creator, granted, or any workbook with no grants yet). An optional URL segment performs a keyword search across the workbook name, description, section names, field labels, and objective answer values. Pass ?status=1 to return only Published workbooks (e.g. for the portal list) or ?status=0 for Drafts. Results are ordered by last updated.
Optional Parameters:
{
"q": "search term",
"status": 1,
"page": 0
}
Parameter Notes:
q
status
page
Returns:
{
"code": 200,
"desc": "Workbooks found",
"response": {
"total_rows": 7,
"rows": 7,
"page": 0,
"per_page": 50,
"total_pages": 1,
"workbooks": [
{
"id": 12,
"name": "CMMC Shared Responsibility Matrix",
"description": "MSP / OSC responsibility split",
"status": 1,
"field_count": 5,
"entry_count": 2,
"section_count": 14,
"total_objectives": 110,
"completed_objectives": 47,
"percent_complete": 43,
"created_at": "2025-02-01 09:12:00 UTC",
"updated_at": "2025-05-18 14:02:11 UTC"
},
{ ... }
]
}
}
Get-Workbook
GET https://vertask.com/api/requests/get-workbook/12
Use this method to get a single workbook with its counts, completion progress, and the calling agent's own access level. The calling agent must be able to access the workbook.
Returns:
{
"code": 200,
"desc": "Workbook found",
"response": {
"id": 12,
"name": "CMMC Shared Responsibility Matrix",
"description": "MSP / OSC responsibility split",
"status": 1,
"creator": 18,
"access": "edit",
"field_count": 5,
"section_count": 14,
"total_objectives": 110,
"completed_objectives": 47,
"percent_complete": 43,
"created_at": "2025-02-01 09:12:00 UTC",
"updated_at": "2025-05-18 14:02:11 UTC"
}
}
Create-Workbook
POST https://vertask.com/api/requests/create-workbook
Use this method to create a new workbook. The calling agent becomes the creator and implicitly has edit access. New workbooks start as Draft (status = 0).
Post Fields:
| Field | Required | Description |
|---|---|---|
| name | Yes | The workbook name. |
| description | No | A description for the workbook. |
Returns:
{
"code": 200,
"desc": "success",
"response": {
"workbook": 12
}
}
Update-Workbook
POST https://vertask.com/api/requests/update-workbook
Use this method to update a workbook. Only fields included in the post are updated. The name cannot be posted empty. The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| workbook | Yes | The id of the workbook to update. |
| name | No | A new name. Cannot be posted empty. |
| description | No | A new description. Post empty to clear. |
| status | No | Publish state. 0 = Draft, 1 = Published. |
Returns:
{
"code": 200,
"desc": "Changes saved",
"response": {
"workbook": 12
}
}
Update-Workbook-Status
POST https://vertask.com/api/requests/update-workbook-status
Single-purpose alternative to setting status via Update-Workbook. The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| workbook | Yes | The id of the workbook. |
| status | Yes | Publish state. 0 = Draft, 1 = Published. |
Returns:
{
"code": 200,
"desc": "Status updated",
"response": {
"workbook": 12,
"status": 1
}
}
Clone-Workbook
POST https://vertask.com/api/requests/update-workbook-clone
Use this method to duplicate a workbook. The copy keeps the full structure (fields, sections, rows) and the template-role values, but entry answers are not copied and every objective is reset to not_started. The copy is owned by the calling agent and starts as Draft. The calling agent must be able to access the source workbook.
Post Fields:
| Field | Required | Description |
|---|---|---|
| workbook | Yes | The id of the workbook to clone. |
Returns:
{
"code": 200,
"desc": "Workbook cloned",
"response": {
"workbook": 18
}
}
Delete-Workbook
POST https://vertask.com/api/requests/update-workbook-delete
Use this method to move a workbook to the trash (soft delete). It can be restored within the retention window, after which it is purged automatically. The calling agent must hold edit access. To permanently delete instead, use Purge-Workbook.
Post Fields:
| Field | Required | Description |
|---|---|---|
| workbook | Yes | The id of the workbook to trash. |
Returns:
{
"code": 200,
"desc": "Workbook moved to trash",
"response": {
"workbook": 12,
"retention_days": 30
}
}
Workbook trash methods
Trashed workbooks are kept for the retention window so they can be restored, then purged automatically. You can also purge one immediately. These methods are limited to workbooks the calling agent can manage (creator or granted).
Get-Workbook-Trash
GET https://vertask.com/api/requests/get-workbook-trash
Use this method to list trashed workbooks the calling agent can manage, including when each is due for automatic removal.
Returns:
{
"code": 200,
"desc": "Workbooks found",
"response": {
"rows": 2,
"retention_days": 30,
"workbooks": [
{
"id": 9,
"name": "Old Matrix",
"description": "Superseded draft",
"section_count": 6,
"deleted_at": "2025-05-10 11:00:00 UTC",
"auto_delete_at": "2025-06-09 11:00:00 UTC",
"days_left": 17
},
{ ... }
]
}
}
Restore-Workbook
POST https://vertask.com/api/requests/update-workbook-restore
Use this method to restore a trashed workbook back to the active list. The calling agent must hold edit access on the workbook.
Post Fields:
| Field | Required | Description |
|---|---|---|
| workbook | Yes | The id of the trashed workbook to restore. |
Returns:
{
"code": 200,
"desc": "Workbook restored",
"response": {
"workbook": 9
}
}
Purge-Workbook
POST https://vertask.com/api/requests/update-workbook-purge
Use this method to permanently delete a trashed workbook now. This cascades and removes all of its objective values, objectives, sections, fields, and permission grants, then the workbook record itself. The calling agent must hold edit access. This action cannot be undone.
Post Fields:
| Field | Required | Description |
|---|---|---|
| workbook | Yes | The id of the trashed workbook to delete permanently. |
Returns:
{
"code": 200,
"desc": "Workbook permanently deleted"
}
Workbook field methods
Fields are the typed columns of a workbook. field_type is one of text, textarea, or select (for select, options holds the choices, one per line). role is template (reference data set up by the publisher) or entry (answered on the portal).
Get-Workbook-Fields
GET https://vertask.com/api/requests/get-workbook-fields/12
Use this method to list the fields of a workbook in sort order. Pass an optional ?role=template or ?role=entry to filter. The calling agent must be able to access the workbook.
Returns:
{
"code": 200,
"desc": "Fields found",
"response": {
"workbook": 12,
"rows": 5,
"fields": [
{
"id": 41,
"label": "MSP Responsibility",
"field_type": "select",
"role": "template",
"options": "MSP\nOSC\nShared\nN/A",
"sort_order": 0
},
{ ... }
]
}
}
Get-Workbook-Field
GET https://vertask.com/api/requests/get-workbook-field/41
Use this method to get a single field. The calling agent must be able to access the parent workbook.
Returns:
{
"code": 200,
"desc": "Field found",
"response": {
"id": 41,
"workbook_id": 12,
"label": "MSP Responsibility",
"field_type": "select",
"role": "template",
"options": "MSP\nOSC\nShared\nN/A",
"sort_order": 0
}
}
Create-Workbook-Field
POST https://vertask.com/api/requests/create-workbook-field
Use this method to add a field (column) to a workbook. The calling agent must hold edit access. An unrecognised field_type falls back to text; an unrecognised role falls back to template.
Post Fields:
| Field | Required | Description |
|---|---|---|
| workbook | Yes | The id of the workbook. |
| label | Yes | The column label. |
| field_type | No | One of text (default), textarea, select. |
| role | No | One of template (default) or entry. |
| options | No | For select fields: the choices, one per line. |
Returns:
{
"code": 200,
"desc": "Field added",
"response": {
"field_id": 41,
"workbook_id": 12,
"label": "MSP Responsibility",
"field_type": "select",
"role": "template"
}
}
Update-Workbook-Field
POST https://vertask.com/api/requests/update-workbook-field
Use this method to update a field. Only fields included in the post are updated. label cannot be posted empty. The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| field | Yes | The id of the field to update. |
| label | No | New label. Cannot be posted empty. |
| field_type | No | One of text, textarea, select. |
| role | No | One of template or entry. |
| options | No | Dropdown choices, one per line. Post empty to clear. |
Returns:
{
"code": 200,
"desc": "Field updated",
"response": {
"field_id": 41
}
}
Delete-Workbook-Field
POST https://vertask.com/api/requests/update-workbook-field-delete
Use this method to delete a field and all of its stored values across every objective. The calling agent must hold edit access. This action cannot be undone.
Post Fields:
| Field | Required | Description |
|---|---|---|
| field | Yes | The id of the field to delete. |
Returns:
{
"code": 200,
"desc": "Field deleted"
}
Sort-Workbook-Fields
POST https://vertask.com/api/requests/update-workbook-field-sort
Use this method to set the column order. Pass the field ids as a comma-separated list in the exact order you want them; sort_order is assigned from the list position. Ids that don't belong to the workbook are ignored. The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| workbook | Yes | The id of the workbook. |
| fields | Yes | Comma-separated field ids in the desired order (e.g. 43,41,42). |
Returns:
{
"code": 200,
"desc": "Fields reordered",
"response": {
"workbook": 12,
"order": [43, 41, 42]
}
}
Workbook section methods
Sections group the rows (objectives) of a workbook.
Get-Workbook-Sections
GET https://vertask.com/api/requests/get-workbook-sections/12
Use this method to list a workbook's sections in sort order, each with its objective count. The calling agent must be able to access the workbook.
Returns:
{
"code": 200,
"desc": "Sections found",
"response": {
"workbook": 12,
"rows": 14,
"sections": [
{
"id": 88,
"name": "Access Control (AC)",
"sort_order": 0,
"objective_count": 22
},
{ ... }
]
}
}
Get-Workbook-Section
GET https://vertask.com/api/requests/get-workbook-section/88
Use this method to get a single section. The calling agent must be able to access the parent workbook.
Returns:
{
"code": 200,
"desc": "Section found",
"response": {
"id": 88,
"workbook_id": 12,
"name": "Access Control (AC)",
"sort_order": 0
}
}
Create-Workbook-Section
POST https://vertask.com/api/requests/create-workbook-section
Use this method to add a section to a workbook. The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| workbook | Yes | The id of the workbook. |
| name | Yes | The section name. |
Returns:
{
"code": 200,
"desc": "Section created",
"response": {
"section_id": 88,
"workbook_id": 12,
"name": "Access Control (AC)"
}
}
Update-Workbook-Section
POST https://vertask.com/api/requests/update-workbook-section
Use this method to rename a section. The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| section | Yes | The id of the section. |
| name | Yes | The new section name. |
Returns:
{
"code": 200,
"desc": "Section updated",
"response": {
"section_id": 88,
"name": "Access Control (AC)"
}
}
Delete-Workbook-Section
POST https://vertask.com/api/requests/update-workbook-section-delete
Use this method to delete a section and all of its objectives and their values. The calling agent must hold edit access. This action cannot be undone.
Post Fields:
| Field | Required | Description |
|---|---|---|
| section | Yes | The id of the section to delete. |
Returns:
{
"code": 200,
"desc": "Section deleted"
}
Sort-Workbook-Sections
POST https://vertask.com/api/requests/update-workbook-section-sort
Use this method to set section order. Pass the section ids as a comma-separated list in the desired order. Ids that don't belong to the workbook are ignored. The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| workbook | Yes | The id of the workbook. |
| sections | Yes | Comma-separated section ids in the desired order (e.g. 90,88,89). |
Returns:
{
"code": 200,
"desc": "Sections reordered",
"response": {
"workbook": 12,
"order": [90, 88, 89]
}
}
Workbook objective methods
Objectives are the rows of a workbook. Each belongs to a section, carries a status (not_started, in_progress, completed), and holds one value per field. Values are addressed by field_id.
Get-Workbook-Objectives
GET https://vertask.com/api/requests/get-workbook-objectives/88
Use this method to list the objectives (rows) in a section, each with its field values keyed by field_id. Pass an optional ?status=not_started (or in_progress / completed) to return only rows in that status. The calling agent must be able to access the parent workbook.
Optional Parameters:
status
Returns:
{
"code": 200,
"desc": "Objectives found",
"response": {
"section": 88,
"rows": 2,
"objectives": [
{
"id": 5012,
"sort_order": 0,
"status": "in_progress",
"values": {
"41": "MSP",
"42": "Implemented via Intune"
}
},
{ ... }
]
}
}
Get-Workbook-Objective
GET https://vertask.com/api/requests/get-workbook-objective/5012
Use this method to get a single objective with its field values. The calling agent must be able to access the parent workbook.
Returns:
{
"code": 200,
"desc": "Objective found",
"response": {
"id": 5012,
"section_id": 88,
"workbook_id": 12,
"sort_order": 0,
"status": "in_progress",
"values": {
"41": "MSP",
"42": "Implemented via Intune"
}
}
}
Create-Workbook-Objective
POST https://vertask.com/api/requests/create-workbook-objective
Use this method to add an objective (row) to a section. Optionally seed its values by posting a fields map keyed by field_id; only field ids that belong to the same workbook are saved. The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| section | Yes | The id of the section the row belongs to. |
| status | No | One of not_started (default), in_progress, completed. |
| fields[<field_id>] | No | Value for a field, e.g. fields[41]=MSP. Repeat for multiple fields. |
Example request (form-data)
section=88&status=in_progress&fields[41]=MSP&fields[42]=Implemented via Intune
Returns:
{
"code": 200,
"desc": "Objective created",
"response": {
"objective_id": 5012,
"section_id": 88,
"status": "in_progress"
}
}
Update-Workbook-Objective
POST https://vertask.com/api/requests/update-workbook-objective
Use this method to set values on an objective in bulk and/or change its status. Post a fields map keyed by field_id; each posted value is upserted (only field ids belonging to the workbook are saved). Provide fields, status, or both. The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| objective | Yes | The id of the objective to update. |
| fields[<field_id>] | No* | Value for a field, e.g. fields[42]=Done. Repeat for multiple fields. |
| status | No* | One of not_started, in_progress, completed. |
* Provide at least one of fields or status.
Returns:
{
"code": 200,
"desc": "Objective saved",
"response": {
"objective_id": 5012
}
}
Update-Workbook-Objective-Status
POST https://vertask.com/api/requests/update-workbook-objective-status
Single-purpose alternative for setting an objective's status. The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| objective | Yes | The id of the objective. |
| status | Yes | One of not_started, in_progress, completed. |
Returns:
{
"code": 200,
"desc": "Status updated",
"response": {
"objective_id": 5012,
"status": "completed"
}
}
Update-Workbook-Objective-Value
POST https://vertask.com/api/requests/update-workbook-objective-value
Use this method to set a single cell — one field's value on one objective. The field must belong to the same workbook as the objective. The value is upserted (created if absent, otherwise overwritten). The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| objective | Yes | The id of the objective (row). |
| field | Yes | The id of the field (column). |
| value | No | The cell value. Post empty to clear. |
Returns:
{
"code": 200,
"desc": "Value saved",
"response": {
"objective_id": 5012,
"field_id": 42
}
}
Delete-Workbook-Objective
POST https://vertask.com/api/requests/update-workbook-objective-delete
Use this method to delete an objective (row) and all of its values. The calling agent must hold edit access. This action cannot be undone.
Post Fields:
| Field | Required | Description |
|---|---|---|
| objective | Yes | The id of the objective to delete. |
Returns:
{
"code": 200,
"desc": "Objective deleted"
}
Sort-Workbook-Objectives
POST https://vertask.com/api/requests/update-workbook-objective-sort
Use this method to set the row order within a section. Pass the objective ids as a comma-separated list in the desired order. Ids that don't belong to the section are ignored. The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| section | Yes | The id of the section. |
| objectives | Yes | Comma-separated objective ids in the desired order (e.g. 5014,5012,5013). |
Returns:
{
"code": 200,
"desc": "Objectives reordered",
"response": {
"section": 88,
"order": [5014, 5012, 5013]
}
}
Workbook permission methods
Access to a workbook is governed per workbook. The creator always has manage (edit) access. Other company agents are granted Manage (can_edit = 1) or View (can_edit = 0). A workbook with no grants is open to any agent in the company until the first grant is added.
Get-Workbook-Permissions
GET https://vertask.com/api/requests/get-workbook-permissions/12
Use this method to list the agents with access to a workbook, including the creator. role is a friendly mapping of can_edit — Manage when 1, View when 0. The calling agent must be able to access the workbook.
Returns:
{
"code": 200,
"desc": "Permissions found",
"response": {
"workbook": 12,
"rows": 2,
"permissions": [
{
"agent_id": 18,
"fname": "Paul",
"lname": "Nurse",
"status": 1,
"can_edit": 1,
"role": "Manage",
"creator": true
},
{
"agent_id": 30,
"fname": "Jane",
"lname": "Doe",
"status": 1,
"can_edit": 0,
"role": "View",
"creator": false
}
]
}
}
Update-Workbook-Permission
POST https://vertask.com/api/requests/update-workbook-permission
Use this method to grant, modify, or revoke an agent's access to a workbook. The calling agent must hold manage (edit) access. The creator's access is implicit and cannot be changed here, and an agent cannot revoke their own access. The target agent must belong to the same company.
Post Fields:
| Field | Required | Description |
|---|---|---|
| workbook | Yes | The id of the workbook. |
| agent | Yes | The id of the agent whose access is being changed. |
| action | Yes | One of grant or remove. |
| level | No | For grant only. edit (default, = Manage) or view. Ignored for remove. |
Returns (grant):
{
"code": 200,
"desc": "Access updated",
"response": {
"workbook": 12,
"agent": 30,
"can_edit": 0,
"role": "View"
}
}
Returns (remove):
{
"code": 200,
"desc": "Access removed"
}
Workbook lookup methods
Static helper lists for building dropdowns. Values map directly to the enum columns used by the field and objective methods.
Get-Workbook-Field-Types
GET https://vertask.com/api/requests/get-workbook-field-types
Returns the valid field_type values for a field.
Returns:
{
"code": 200,
"desc": "Field types found",
"response": {
"rows": 3,
"field_types": [
{ "value": "text", "name": "Text" },
{ "value": "textarea", "name": "Text area" },
{ "value": "select", "name": "Dropdown" }
]
}
}
Get-Workbook-Field-Roles
GET https://vertask.com/api/requests/get-workbook-field-roles
Returns the valid role values for a field.
Returns:
{
"code": 200,
"desc": "Field roles found",
"response": {
"rows": 2,
"field_roles": [
{ "value": "template", "name": "Template" },
{ "value": "entry", "name": "Entry" }
]
}
}
Get-Workbook-Objective-Statuses
GET https://vertask.com/api/requests/get-workbook-objective-statuses
Returns the valid status values for an objective (row).
Returns:
{
"code": 200,
"desc": "Statuses found",
"response": {
"rows": 3,
"statuses": [
{ "value": "not_started", "name": "Not started" },
{ "value": "in_progress", "name": "In progress" },
{ "value": "completed", "name": "Completed" }
]
}
}
Get-Workbook-Statuses
GET https://vertask.com/api/requests/get-workbook-statuses
Returns the valid publish status values for a workbook.
Returns:
{
"code": 200,
"desc": "Statuses found",
"response": {
"rows": 2,
"statuses": [
{ "value": 0, "name": "Draft" },
{ "value": 1, "name": "Published" }
]
}
}
Get-Workbook-Stats
GET https://vertask.com/api/requests/get-workbook-stats/12
Use this method to get completion stats for a workbook: an overall roll-up plus the same breakdown per section. filled counts rows that have at least one non-empty entry value; percent_complete is completed / rows. The calling agent must be able to access the workbook.
Returns:
{
"code": 200,
"desc": "Stats found",
"response": {
"workbook": 12,
"overall": {
"rows": 110,
"filled": 52,
"not_started": 40,
"in_progress": 23,
"completed": 47,
"percent_complete": 43
},
"sections": [
{
"section_id": 88,
"name": "Access Control (AC)",
"rows": 22,
"filled": 12,
"not_started": 6,
"in_progress": 5,
"completed": 11
},
{ ... }
]
}
}
Save-Workbook-Section
POST https://vertask.com/api/requests/update-workbook-section-entries
Use this method to save a whole section in one request — the portal "Save this section" action. Post entry values as a rows map and row statuses as a status map, both keyed by objective id. Only entry-role field values are written (template columns are read-only here), and only objectives that belong to the section are touched. Provide rows, status, or both. The calling agent must hold edit access.
Post Fields:
| Field | Required | Description |
|---|---|---|
| section | Yes | The id of the section being saved. |
| rows[<objective_id>][<field_id>] | No* | Entry value for one cell, e.g. rows[5012][42]=Implemented via Intune. Non-entry field ids are ignored. |
| status[<objective_id>] | No* | Row status: not_started, in_progress, or completed. |
* Provide at least one of rows or status.
Example request (form-data)
section=88
&rows[5012][42]=Implemented via Intune
&rows[5013][42]=Pending review
&status[5012]=completed
&status[5013]=in_progress
Returns:
{
"code": 200,
"desc": "Saved",
"response": {
"section": 88,
"values_saved": 2,
"status_saved": 2
}
}