Helpdesk 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
},
{
...
...
}
]
}
}
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"
}
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
Contract methods
API methods to work with contracts. Contracts allow you to track agreements, set renewal reminders, share access with other agents, and store contract metadata such as start/end dates, cost, and seller.
Get-Contracts
GET https://vertask.com/api/requests/get-contracts
GET https://vertask.com/api/requests/get-contracts/renewal
Use this method to get a list of all contracts the calling agent has access to. An optional URL segment performs a keyword search across name, details, and seller. Results are paginated.
Optional Parameters:
{
"q": "search term",
"status": 1,
"start": "2024-01-01",
"end": "2024-12-31",
"id": 42,
"page": 0
}
Parameter Notes:
q // optional – keyword search across name, details, and seller (alt to URL segment)
status // optional – 0=Inactive 1=Active (omit for all)
start // optional – YYYY-MM-DD, contract_start on or after this date
end // optional – YYYY-MM-DD, contract_end on or before this date
id // optional – exact contract id (overrides keyword search)
page // optional – zero-based page number, 50 results per page (default: 0)
Returns:
{
"code": 200,
"desc": "Contracts found",
"response": {
"total_rows": 63,
"rows": 50,
"page": 0,
"per_page": 50,
"total_pages": 2,
"contracts": [
{
"id": 42,
"name": "Acme SaaS Subscription",
"details": "Annual subscription covering 50 seats.",
"seller": "Acme Corp",
"cost": "12500.00",
"contract_start": "2024-01-01",
"contract_end": "2024-12-31",
"initial_date": "2022-01-01",
"status": 1,
"creator": 116,
"last_modified": "2024-08-12 14:22:01"
},
{
...
...
}
]
}
}
Get-Contract
GET https://vertask.com/api/requests/get-contract/13
Use this method to get the full details of a contract. This method returns a json object with all the details of the contract provided.
Returns:
{
"code": 200,
"desc": "Contract found",
"response": {
"id": 2,
"name": "Eset AV",
"details": "Renewal cannot exceed 3% price increase",
"last_modified": "2022-05-04 03:24:17",
"contract_start": "2018-11-08",
"contract_end": "2024-11-05",
"contract_initial_date": "0000-00-00",
"contract_creator": 2,
"contract_value": "24350.00",
"from": "Softchoice",
"status": 1
}
}
Get-Contract-Reminders
GET https://vertask.com/api/requests/get-contract-reminders/42
Use this method to get the calling agent's reminders for a specific contract. Reminders are personal — only reminders created by the calling agent are returned. Other agents' reminders on the same contract are not visible.
Required Parameters:
| Field | Description |
|---|---|
| contract | The contract id, passed either as a URL segment or as ?contract=. |
Returns:
{
"code": 200,
"desc": "Reminders found",
"response": {
"contract": 42,
"rows": 2,
"reminders": [
{
"id": 812,
"remind_at": "2024-11-15 09:00:00",
"note": "Begin renewal negotiations",
"creator": 116,
"reminded": 0,
"created_at": "2024-08-12 14:22:01"
},
{
...
...
}
]
}
}
Get-Contract-Permissions
GET https://vertask.com/api/requests/get-contract-permissions/42
Use this method to get a list of all agents who have access to a contract. The caller must hold a permission (view or edit) on the contract to retrieve the list. The role field is a friendly mapping of the edit flag — Editor when edit = 1 and Viewer when edit = 0.
Required Parameters:
| Field | Description |
|---|---|
| contract | The contract id, passed either as a URL segment or as ?contract=. |
Returns:
{
"code": 200,
"desc": "Permissions found",
"response": {
"contract": 42,
"rows": 3,
"permissions": [
{
"id": 901,
"agent_id": 116,
"fname": "Paul",
"lname": "Nurse",
"view": 1,
"edit": 1,
"role": "Editor",
"last_modified": "2024-08-12 14:22:01"
},
{
...
...
}
]
}
}
Create-Contract
POST https://vertask.com/api/requests/create-contract
Use this method to create a new contract. The calling agent is automatically granted view + edit access to the new record.
Post Fields:
| Field | Required | Description |
|---|---|---|
| name | Yes | The contract name. |
| details | No | HTML-allowed details or description of the contract. |
| contract_start | No | Start date, format YYYY-MM-DD. |
| contract_end | No | End / renewal date, format YYYY-MM-DD. |
| initial_date | No | The original / initial agreement date, format YYYY-MM-DD. |
| cost | No | Monetary value of the contract (number, e.g. 12500.00). |
| seller | No | The seller / vendor name. |
| status | No | Active state. 1 = active (default), 0 = inactive. |
Returns:
{
"code": 200,
"desc": "success",
"response": {
"contract": 42
}
}
Update-Contract
POST https://vertask.com/api/requests/update-contract
Use this method to update an existing contract. Only fields included in the post will be updated. To clear a date or text field, post it with an empty value. The name field cannot be posted empty. The calling agent must hold an editor permission on the contract.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | The id of the contract to update. |
| name | No | A new name for the contract. Cannot be posted empty. |
| details | No | HTML-allowed details. Post empty to clear. |
| contract_start | No | Start date, YYYY-MM-DD. Post empty to clear. |
| contract_end | No | End date, YYYY-MM-DD. Post empty to clear. |
| initial_date | No | Original agreement date, YYYY-MM-DD. Post empty to clear. |
| cost | No | Monetary value (number). |
| seller | No | Seller / vendor name. Post empty to clear. |
| status | No | Active state. 1 = active, 0 = inactive. |
Returns:
{
"code": 200,
"desc": "Changes saved",
"response": true
}
Update-Contract-Delete
POST https://vertask.com/api/requests/update-contract-delete
Use this method to permanently delete a contract. This action cascades through and removes all attached files (from disk and database), all reminders, all permissions, the contract record itself, and any recently-viewed entries referencing it. The calling agent must hold an editor permission on the contract. This action cannot be undone.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | The id of the contract to delete. |
Returns:
{
"code": 200,
"desc": "Contract deleted",
"response": true
}
Update-Contract-Permission
POST https://vertask.com/api/requests/update-contract-permission
Use this method to grant, modify, or remove an agent's permission on a contract. The calling agent must hold an editor permission on the contract. A contract must always have at least one editor — remove and self-downgrade operations are rejected if they would leave the contract with zero editors.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | The contract id. |
| agent | Yes | The id of the agent whose permission is being granted, modified, or removed. |
| action | Yes | One of: grant or remove. |
| edit | No* | For grant only. 1 = Editor, 0 = Viewer (default). Ignored for remove. |
Returns (grant):
{
"code": 200,
"desc": "Permission saved",
"response": {
"permission": 901,
"edit": 1
}
}
Returns (remove):
{
"code": 200,
"desc": "Permission removed",
"response": true
}
Update-Contract-Reminders
POST https://vertask.com/api/requests/update-contract-reminders
Use this method to add or delete a reminder on a contract. Reminders are personal — the calling agent can only add reminders for themselves, and can only delete reminders that they created. The calling agent must hold a permission (view or edit) on the contract.
Post Fields:
| Field | Required | Description |
|---|---|---|
| contract | Yes | The contract id. |
| action | Yes | One of: add or delete. |
Add — required when action = add: | ||
| date | Yes* | When to remind. Accepts any parseable date/time, e.g. 2024-11-15 09:00:00. |
| note | No | Optional HTML-allowed note for the reminder. |
Delete — required when action = delete: | ||
| reminder | Yes* | The id of the reminder to delete. Must be one created by the calling agent. |
Returns (add):
{
"code": 200,
"desc": "Reminder added",
"response": {
"reminder": 812,
"contract": 42,
"remind_at": "2024-11-15 09:00:00"
}
}
Returns (delete):
{
"code": 200,
"desc": "Reminder deleted",
"response": true
}
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
}
}
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, and a billing audience. Bookmarks (stars) are per-agent.
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 (be directly assigned, in an assigned group, or the project creator). An optional URL segment performs a keyword search across name and details. Results are paginated.
Optional Parameters:
{
"q": "search term",
"status": 1,
"priority": 15,
"start": "2024-01-01",
"end": "2024-12-31",
"id": 87,
"page": 0
}
Parameter Notes:
q // optional – keyword search across name and details (alt to URL segment)
status // optional – 0=closed 1=open (omit for all)
priority // optional – 5,10,15,20,25
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 results 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 to new region.",
"status": 1,
"priority": 15,
"due_date": "2024-12-31",
"billto": 42,
"creator": 116,
"created_at": "2024-08-12 14:22:01",
"closed_at": ""
},
{
...
...
}
]
}
}
Get-Project
GET https://vertask.com/api/requests/get-project/87
Use this method to get the full details of a single project, including the calling agent's 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 to new region.",
"status": 1,
"priority": 15,
"due_date": "2024-12-31",
"billto": 42,
"creator": 116,
"created_at": "2024-08-12 14:22:01",
"closed_at": "",
"bookmarked": 1,
"agents_count": 3,
"groups_count": 1,
"tasks_count": 12
}
}
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 specific project. The calling agent must have access to the project.
Required Parameters:
| Field | Description |
|---|---|
| project | The project id, passed either as a URL segment or as ?project=. |
Returns:
{
"code": 200,
"desc": "Tasks found",
"response": {
"project": 87,
"rows": 2,
"tasks": [
{
"id": 1408,
"title": "Draft initial requirements",
"details": "Outline scope and acceptance criteria.",
"status": 1,
"priority": 10,
"due_date": "2024-11-15",
"created_at": "2024-08-12 14:22:01"
},
{
...
...
}
]
}
}
Get-Project-Agents
GET https://vertask.com/api/requests/get-project-agents/87
Use this method to get the list of agents directly assigned to a project. Agents who only have access through an assigned group are not listed here — use Get-Project-Agents for that. The calling agent must have access to the project.
Required Parameters:
| Field | Description |
|---|---|
| project | The project id is passed either as a URL segment. |
Returns:
{
"code": 200,
"desc": "Agents found",
"response": {
"project": 87,
"rows": 2,
"agents": [
{
"id": 312,
"agent_id": 116,
"fname": "Paul",
"lname": "Nurse",
"assigned_at": "2024-08-12 14:22:01"
},
{
...
...
}
]
}
}
Get-Project-Groups
GET https://vertask.com/api/requests/get-project-groups/87
Use this method to get the list of agent groups / teams assigned to a project. Each group includes a member count. To list individual agents directly assigned to the project, use Get-Project-Groups. The calling agent must have access to the project.
Required Parameters:
| Field | Description |
|---|---|
| project | The project id, passed either as a URL segment or as ?project=. |
Returns:
{
"code": 200,
"desc": "Groups found",
"response": {
"project": 87,
"rows": 2,
"groups": [
{
"id": 441,
"group_id": 7,
"name": "Infrastructure",
"member_count": 5,
"assigned_at": "2024-08-12 14:22:01"
},
{
...
...
}
]
}
}
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
}
Site methods
Site 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"
}
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
}