Helpdesk API
Use Vertask's RESTful API to post new tasks, retrieve and update existing tasks and integrate with your existing applications.
Our API was just launched January 1, 2023. We're currently in BETA, check back weekly for new features. Contact us to report problems or to request additional methods.
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 (company id) is
Z2Web6-s0XEafand the api key is1234-5678, then we would convert Z2Web6-s0XEaf:1234-5678 to Base64 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"
}
}
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.
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"
}
}
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 } }
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"
}
}
}
}
Client methods
Get-Clients
GET https://vertask.com/api/requests/get-clients
Use this method to get a list of all clients.
Returns:
{
"code": 200,
"desc": "Client users found",
"response": {
"rows": 21,
"clients": [
{
"id": 116,
"fname": "Paul",
"lname": Nurse,
"username": "paul.admin",
"email": "[email protected]",
"last_modified": "2022-12-09 23:30:02"
},
{
"id": 116,
"fname": "Paul",
"lname": Nurse,
"username": "paul.admin",
"email": "[email protected]",
"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"
}
}
Contract methods
Get-Contracts
GET https://vertask.com/api/requests/get-contracts
Use this method to get a list of all contracts the authenticated user has access to.
Returns:
{
"code": 200,
"desc": "Contracts found",
"response": {
"rows": 6,
"contracts": [
{
"id": 2,
"last_modified": "2022-12-09 23:30:02",
"name": Eset AV,
"contract_start": "2018-11-08",
"contract_end": "2024-11-05",
"contract_value": "24350.00",
"status": 1
},
{
...
...
}
]
}
}
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
}
}
Project methods
Get-Projects
GET https://vertask.com/api/requests/get-projects
Use this method to get a list of all projects the authenticated user has access to.
Returns:
{
"code": 200,
"desc": "Projects found",
"response": {
"rows": 3,
"projects": [
{
"id": 787,
"severity": 5,
"date_completed": "0000-00-00 00:00:00",
"status": 1,
"title": "test project test",
"duedate": "0000-00-00",
"last_modified": "2022-09-24 19:51:18"
},
{
...
...
}
]
}
}
Get-Project
GET https://vertask.com/api/requests/get-project/787
Use this method to get the full details of a project. This method returns a json object with all the details of the project provided.
Returns:
{
"code": 200,
"desc": "Contract found",
"response": {
"id": 787,
"creator": 6,
"last_modified": "2022-09-24 19:51:18",
"severity": "2022-05-04 03:24:17",
"status": 0,
"title": "test project test",
"info": null,
"duedate": "0000-00-00",
"duedate_set_by": null,
"date_resolved": "0000-00-00 00:00:00",
"billto": 0,
"time_allocated": 00:00
}
}
Site methods
Get-Sites
GET https://vertask.com/api/requests/get-sites
Use this method to get a list of all sites/locations.
Returns:
{
"code": 200,
"desc": "Sites found",
"response": {
"rows": 7,
"sites": [
{
"id": 4,
"last_modified": "2022-09-24 19:51:18",
"name": "HQ",
"status": 1
},
{
...
...
}
]
}
}
Get-Site
GET https://vertask.com/api/requests/get-site/4
Use this method to get the full details of a site. This method returns a json object with all the details of the site 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"
}
}
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 a another test",
"severity": 10,
"status": 0,
"duedate": "2022-11-25 06:10:22"
}
]
}
}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 (these are unique to each company can can be seen on custom resolution settings page). |
| title | int | Title of the task |
| info | string | Details provide 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
Create a new task. The below paramaters are accepted during the task creation as posted form-data, and only a title is required.
Parameters:
| Value | Type | Description |
|---|---|---|
| title | string | Task title |
| clients | int, string | Client IDs or email addresses to link to this task, comma seperate multiple values |
| assets | int | Asset IDs to link to this task, comma seperate multiple values. |
| assigned | int | Agent IDs to assign to this task, comma seperate multiple values. |
| group-assigned | int | Agent group IDs to assign to this task, comma seperate multiple values. |
| priority | int,string | Possible values: |
| visible | int | Possible values: |
| billto | int | The billing audience to tie this task to |
| info | string | Details or task objectives |
| project | int | Project ID to link to this task |
| tags | int | Tag IDs to assign to this task, comma seperate multiple values. |
| office | int | Office IDs to link to this task, comma seperate multiple values. |
| duedate | string | Due date of the task using format YYYY-MM-DD HH:MM:SS |
| auto-create | int | If the client does not exist, should they be auto-created if an email address was provided? |
| auto-invite | int | If client is auto-created, should we send them an invite to sign into the end-user portal? |
Returns
The created
task idis returned (i.e., 795), or error message if a problem occured.{ "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 your own tasks details that you have access to. The below paramaters are accepted when you post as form-data. The task id is required with all requests., only submit the other paramaters you want to modify. Submitting an empty paramater will clear any existing value(s) saved for that value.
Parameters:
| Value | Type | Description |
|---|---|---|
| task | int | The task id to update |
| title | string | Updae task title |
| clients | int, string | Add client IDs or email addresses to link to this task, comma seperate multiple values |
| assets | int | Add asset IDs to link to this task, comma seperate multiple values. |
| assigned | int | Add agent IDs to assign to this task, comma seperate multiple values. |
| group-assigned | int | Add agent group IDs to assign to this task, comma seperate multiple values. |
| priority | int,string | Possible values: |
| visible | int | Possible values: |
| billto | int | Add/change the billing audience to tied this task to |
| info | string | Add/change details or task objectives |
| project | int | Add/change the project ID to link to this task |
| tags | int | Add tag IDs to assign to this task, comma seperate multiple values. |
| office | int | Add office IDs to link to this task, comma seperate multiple values. |
| duedate | string | Add/change due date of the task using format YYYY-MM-DD HH:MM:SS |
Returns
trueif there were no errors. Returns an error message otherwise.
{
"code": 200 ,
"desc": "Changes saved" ,
"response": true
}
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": []
}