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-tags/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 }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 }
}
}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 // optional: 1 = active, 0 = inactive
}
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" // or "remove"
}
Returns:
{
"code": 200,
"desc": "Client added to asset" // or "Client removed from 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.
Get-Audience
GET https://vertask.com/api/requests/get-audience
GET https://vertask.com/api/requests/get-audience/795
Use this method to get a list of all audience. This method returns a json object with all audience, or add an optional id to only return the data for one audience.
Returns:
{
"code": 200,
"desc": "Members found",
"response": {
"2": {
"name": "Customer",
"status": 1,
"sla": {
"severe": "1hr",
"critical": "3hr",
"high": "1d",
"medium": "7d",
"low": "1m"
}
},
"3": {
"name": "Warehouse",
"status": 0,
"sla": {
"severe": null,
"critical": null,
"high": null,
"medium": null,
"low": null
}
},
"4": {
"name": "General support",
"status": 1,
"sla": {
"severe": "3hr",
"critical": "24hr",
"high": "3d",
"medium": "1w",
"low": "1m"
}
}
}
}
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. |
Measure Units:
| Value | Unit |
|---|---|
1 | min |
2 | hr |
3 | d |
4 | wk |
5 | mon |
6 | yr |
Returns:
{
"code": 200,
"desc": "Changes saved",
"response": true
}
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 // optional – full-text search across name, email, phone, address, and more
status // optional – 0=Pending 1=Active 2=Inactive (omit for all)
audience // optional – billing audience ID (omit for all)
group // optional – client group ID (omit for all)
page // optional – zero-based page number, 50 results per page (default: 0)
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-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 // optional: 2 = deactivate, 1 or 0 = restore deactivated account
}
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-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.
Returns:
{
"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
},
{
...
...
}
]
}
}
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" // optional: page ids in desired sort order
}
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 // 1 = visible in client portal, 0 = hidden
}
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" // desc reflects the action taken
}
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
API methods to work with projects. Projects group tasks, hold assignments to agents and groups (teams), and carry metadata such as priority, due date, status, phases, health indicators, and a billing audience. Bookmarks (stars) are per-agent. Projects can be archived for soft-deletion.
Get-Projects
GET https://vertask.com/api/requests/get-projects
GET https://vertask.com/api/requests/get-projects/renewal
Use this method to get a list of all projects the calling agent has access to. Returns health indicators, task counts, and archive status for each project. An optional URL segment performs a keyword search. Results are paginated.
Optional Parameters:
{
"q": "search term",
"status": 1,
"priority": 15,
"archived": 0,
"start": "2024-01-01",
"end": "2024-12-31",
"id": 87,
"page": 0
}Parameter Notes:
q // optional – keyword search across name and details
status // optional – 0=closed 1=open (omit for all)
priority // optional – 5,10,15,20,25
archived // optional – 0=active only 1=archived only (omit for active)
start // optional – YYYY-MM-DD, duedate on or after this date
end // optional – YYYY-MM-DD, duedate on or before this date
id // optional – exact project id (overrides keyword search)
page // optional – zero-based page number, 50 per page (default: 0)Returns:
{
"code": 200,
"desc": "Projects found",
"response": {
"total_rows": 63,
"rows": 50,
"page": 0,
"per_page": 50,
"total_pages": 2,
"projects": [
{
"id": 87,
"name": "Datacenter migration",
"details": "Move primary workload.",
"status": 1,
"priority": 15,
"due_date": "2024-12-31",
"billto": 42,
"creator": 116,
"archived": 0,
"created_at": "2024-08-12 14:22:01",
"closed_at": "",
"health": "at_risk",
"tasks_total": 12,
"tasks_done": 5,
"tasks_open": 7,
"tasks_overdue": 2
}
]
}
}Get-Project
GET https://vertask.com/api/requests/get-project/87
Use this method to get the full details of a single project, including health status, phase count, time logged, bookmark state, and counts of attached agents, groups, and tasks. The calling agent must have access to the project.
Required Parameters:
| Field | Description |
|---|---|
| project | The project id, passed as the URL segment after /get-project/. |
Returns:
{
"code": 200,
"desc": "Project found",
"response": {
"id": 87,
"name": "Datacenter migration",
"details": "Move primary workload.",
"status": 1,
"priority": 15,
"due_date": "2024-12-31",
"billto": 42,
"creator": 116,
"archived": 0,
"created_at": "2024-08-12 14:22:01",
"closed_at": "",
"bookmarked": 1,
"health": "at_risk",
"agents_count": 3,
"groups_count": 1,
"phases_count": 4,
"tasks_total": 12,
"tasks_done": 5,
"tasks_open": 7,
"tasks_overdue": 2,
"time_logged": "14:30",
"time_seconds": 52200
}
}Get-Project-Tasks
GET https://vertask.com/api/requests/get-project-tasks/87
Use this method to get the list of tasks attached to a project. Each task includes its phase assignment and dependency (blocked) status. The calling agent must have access to the project.
Required Parameters:
| Field | Description |
|---|---|
| project | The project id, passed as a URL segment. |
Returns:
{
"code": 200,
"desc": "Tasks found",
"response": {
"project": 87,
"rows": 2,
"tasks": [
{
"id": 1408,
"title": "Draft requirements",
"details": "Outline scope.",
"status": 1,
"priority": 10,
"due_date": "2024-11-15",
"created_at": "2024-08-12 14:22:01",
"phase_id": 3,
"phase_name": "Design",
"is_blocked": true,
"blocker_count": 1
}
]
}
}Get-Project-Phases
GET https://vertask.com/api/requests/get-project-phases/87
Use this method to get all phases defined for a project. Each phase includes a task count. Phases are returned in sort order. The calling agent must have access to the project.
Required Parameters:
| Field | Description |
|---|---|
| project | The project id, passed as a URL segment. |
Returns:
{
"code": 200,
"desc": "Phases found",
"response": {
"project": 87,
"rows": 3,
"phases": [
{
"id": 1,
"name": "Planning",
"color": "#007bff",
"sort_order": 1,
"task_count": 4
}
]
}
}Get-Project-Activity
GET https://vertask.com/api/requests/get-project-activity/87
Use this method to get the activity log for a project. Returns a chronological list of changes (status changes, member updates, phase changes, task completions). Paginated, newest first.
Required Parameters:
| Field | Description |
|---|---|
| project | The project id, passed as a URL segment. |
Optional Parameters:
page // optional – zero-based page number, 50 per page (default: 0)Returns:
{
"code": 200,
"desc": "Activity found",
"response": {
"project": 87,
"total_rows": 24,
"rows": 24,
"page": 0,
"activity": [
{
"id": 501,
"action": "task_completed",
"details": "Task #1408 closed",
"agent": "Paul Nurse",
"date": "2024-10-15 09:30:00"
}
]
}
}Get-Task-Dependencies
GET https://vertask.com/api/requests/get-project-dependencies/1408
Use this method to get the dependency graph for a specific task. Returns two lists: tasks that block this one (blocked_by) and tasks that this one blocks (blocking), plus whether the task is currently blocked.
Required Parameters:
| Field | Description |
|---|---|
| task | The task id (companyTaskID), passed as a URL segment. |
Returns:
{
"code": 200,
"desc": "Dependencies found",
"response": {
"task_id": 1408,
"is_blocked": true,
"blocked_by": [
{ "dep_id": 12, "task_id": 1405, "title": "Set up VPN", "status": 1, "resolved": false }
],
"blocking": [
{ "dep_id": 15, "task_id": 1412, "title": "Final testing", "status": 1 }
]
}
}Update-Project-Phases
POST https://vertask.com/api/requests/update-project-phases
Use this method to create, update, delete, or assign phases on a project. Phases are workflow stages (e.g. Planning, Design, Testing) that tasks can be assigned to.
Required Parameters:
{
"project": 87,
"action": "create"
}Parameter Notes:
project // required – project id
action // required – "create", "update", "delete", or "assign"
// For action=create:
name // required – phase name
color // optional – hex color (default: #6c757d)
// For action=update:
phase_id // required – id of the phase to update
name // optional – new name
color // optional – new hex color
// For action=delete:
phase_id // required – id of the phase to delete (tasks become unphased)
// For action=assign:
task_id // required – task to assign
phase_id // required – phase id (use 0 or empty to unassign)Update-Project-Archive
POST https://vertask.com/api/requests/update-project-archive
Use this method to archive or restore a project. Archived projects are soft-deleted — hidden from default listings but recoverable.
Required Parameters:
{
"project": 87,
"archive": 1
}Parameter Notes:
project // required – project id
archive // optional – 1=archive (default), 0=restoreReturns:
{
"code": 200,
"desc": "Project archived",
"response": {
"project": 87,
"archived": 1
}
}Update-Task-Dependencies
POST https://vertask.com/api/requests/update-project-dependencies
Use this method to add or remove task dependencies. A dependency means one task is "blocked by" another — it cannot proceed until the blocker is closed. Circular dependencies are automatically prevented.
Required Parameters:
{
"action": "add",
"task_id": 1408,
"blocked_by": 1405
}Parameter Notes:
action // required – "add" or "remove"
// For action=add:
task_id // required – the task that will be blocked
blocked_by // required – the task that blocks it
// For action=remove:
dep_id // required – the dependency id to remove (from Get-Task-Dependencies)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 // optional – keyword search across fname, lname, and email (alt to URL segment)
id // optional – exact audience id (overrides keyword search)
page // optional – zero-based page number, 50 results per page (default: 0)
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]"
},
{
...
...
}
]
}
}
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
}
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_ip1": "172.16.2.20",
"location_ip2": null,
"location_exip1": null,
"location_exip2": 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
}
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.
Parameters:
| 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) |
Returns
{
"code": 200,
"desc": "Tasks found",
"response": {
"rows": 7,
"tasks": [
{
"task": 791,
"title": "This is a sample task",
"severity": 5,
"status": 1,
"duedate": "2022-12-31 01:16:05"
},
{
"task": 887,
"title": "This is another test",
"severity": 10,
"status": 0,
"duedate": "2022-11-25 06:10:22"
}
]
}
}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. |
| 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
// All open tasks
GET https://vertask.com/api/requests/get-tasks?status=1
// Keyword search — open tasks only
GET https://vertask.com/api/requests/get-tasks/printer?status=1
// High-severity tasks due before end of month
GET https://vertask.com/api/requests/get-tasks?severity=15&duedate_end=2025-01-31
// Keyword + status + severity combined
GET https://vertask.com/api/requests/get-tasks/network%20issue?status=1&severity=20
// Title contains "login", project 4, on hold
GET https://vertask.com/api/requests/get-tasks?title=login&project=4&status=2
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"
},
{
"task": 798,
"title": "Replace ink — HP printer lobby",
"severity": 5,
"status": 1,
"duedate": "0000-00-00 00:00:00"
}
]
}
}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 |
| 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",
"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 // 0 = public, 1 = private (agents only)
}
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"
}
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"
}
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
// Add two tags
task=791&add=4,7
// Remove one tag
task=791&remove=7
// Add and remove in the same request
task=791&add=12&remove=4
// Replace all tags — task will have exactly tags 4 and 12 after this
task=791&set=4,12
// Clear all tags
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.
// Response for: task=791&add=4,7&remove=12
{
"code": 200,
"desc": "Tags updated",
"response": {
"added": [4, 7],
"removed": [12]
}
}
// Response for: task=791&set=4,12
{
"code": 200,
"desc": "Tags updated",
"response": {
"set": [4, 12]
}
}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 // optional – keyword search (alt to URL segment); URL segment takes priority
status // optional – 0=Draft 1=Published (omit for all)
page // optional – zero-based page number, 50 results per page (default: 0)
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 // optional – not_started | in_progress | completed (omit for all)
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
}
}