General information

This document is the documentation for using your BOSSDesk account through an API.

API URL

The API URL is https://[your-account-subdomain].bossdesk.io/api/v1 and all the request URLs must be appended to this URL. For example to get a user list make a GET request to https://mycompany.bossdesk.io/api/v1/users.

Request headers

You must set the following Authorization and Content-Type headers with every request:

Authorization: Token token="your API key"
Content-Type: application/json

Response codes

Response code	Returned when
200 OK	Successful GET request
201 Created	Resource has been successfully created
204 No Content	Resource has been successfully updated
400 Bad Request	Request is erroneous (e.g a required parameter was not provided)
401 Unauthorized	Failed API authorization
402 Payment Required	Failed request due to account expiration or subscription plan limits (e.g no API access or no CMDB access)
403 Forbidden	No access to a resource (e.g makes a user list request but has no user list permission)
404 Not Found	Requested resource was not found
409 Conflict	Edit conflict between multiple updates (e.g two agents updating the same Ticket that would result in one overwriting the changes of the other)
422 Unprocessable Entity	Request was fine but failed because of validation errors (e.g the request tried to create a new user with a username that already exists)

Other things to keep in mind

When a parameter is required, it is marked as "REQUIRED FIELD". All other fields are optional.

Using the API

"Logging in" or retrieving user's API key and permissions info

To get the users API key, you must first authenticate with HTTP Basic Auth. Include the appropriate header:

Authorization: Basic ["username:password" encoded in Base64]

Thing	Value
URL	/sessions
Method	POST
Response	User with API key and permissions info

Example response:

{
  "id": 834,
  "friendly_id": 30,
  "username": "jackpot",
  "email": "jack.pot@example.com",
  "first_name": "Jack",
  "last_name": "Pot",
  "api_key": "c3176bbca97c5b7ee6cee715f3379366e031e0815862",
  "permissions": {
    "cis": ["index", "show"],
    "users": ["index"],
    "software": ["index", "show", "create", "update", "destroy"],
    "holiday_calendar": ["manage"]
  }
}

Account

Retrieving account info and settings

Thing	Value
URL	/account
Method	GET
Response	Account info

Example response:

{
  "name": "Example Service Desk",
  "full_domain": "example.bossdesk.io",
  "ci_barcode_type": "code_93",
  "ci_barcode_method": "name",
  "time_zone": "Eastern Time (US & Canada)",
  "beginning_of_week": 0,
  "autoassign_ci_control_numbers": true,
  "ticket_comment_is_public_by_default": true,
  "default_helpdesk_priority_id": 1234,
  "default_ticket_team_id": 4567,
  "currency": {
    "label": "Dollar ($)",
    "unit": "$",
    "icon": "fa fa-usd"
  },
  "subscription": {
    "agent_limit": 100,
    "custom_mail_server_feature": true,
    "custom_reports_feature": false,
    "dell_warranty_check_feature": true,
    "dependent_tasks_feature": true,
    "event_log_retention_limit": null,
    "hp_warranty_check_feature": true,
    "lenovo_warranty_check_feature": true,
    "team_viewer_integration_feature": true,
    "zapier_integration_feature": true
  }
}

Approval Requests

Creating a new Ticket Approval Request

Thing	Value
URL	/tickets/:ticket_id/approval_requests
Method	POST
Response	201 Approval request or error list.

Example request:

{
  "approval_request": {
    "user_id": 3871
  }
}

Example response:

{
  "id": 1231,
  "user_id": 5432,
  "status": "sent",
  "comment": nil,
  "created_at": "2018-11-28T15:00:00.000Z",
  "responded_at": nil,
  "ticket_id": 4781,
  "friendly_id": 87981
}

Approving an Approval Request on a Ticket

Thing	Value
URL	/tickets/:ticket_id/approval_requests/:approval_request_friendly_id/approve
Method	PATCH
Response	204 No Content

Example request:

{
  "approval_request": {
    "comment": "Request approved!"
  }
}

Example successful response is 204 No Content.

Disapproving an Approval Request on a Ticket

Thing	Value
URL	/tickets/:ticket_id/approval_requests/:approval_request_friendly_id/disapprove
Method	PATCH
Response	204 No Content

Example request:

{
  "approval_request": {
    "comment": "Request disapproved!"
  }
}

Example successful response is 204 No Content.

Canceling an Approval Request on a Ticket

Thing	Value
URL	/tickets/:ticket_id/approval_requests/:approval_request_friendly_id/cancel
Method	PATCH
Response	204 No Content

Example request:

{
  "approval_request": {
    "comment": "Request cancelled!"
  }
}

Example successful response is 204 No Content.

Sending a reminder for an Approval Request on a Ticket

Thing	Value
URL	/tickets/:ticket_id/approval_requests/:approval_request_friendly_id/send_reminder
Method	PATCH
Response	204 No Content

Example successful response is 204 No Content.

Articles

Retrieving the Article list

Thing	Value
URL	/articles
Method	GET
Response	Array of Articles
Pagination	Yes
Search	Yes

Example response:

[
    {
        "id": 35938,
        "friendly_id": 25,
        "title": "Setting up an email account",
        "updated_at": "2022-09-25T20:05:04.795Z",
        "category": {
            "id": 1329,
            "friendly_id": 3,
            "name": "New Employee Setup"
        }
    }
]

In addition to usual attribute-based filtering, article search also allows usage of these additional filters:

simple_search - this filter does a natural-language search on article title and text. It is an AND-based search, which means it will search for articles that contain all of the provided words. Example usage: /api/v1/articles?q[simple_search]=some+search+words.
wide_search - this filter does a natural-language search on article title and text. It is an OR-based search, which means it will search for articles that contain any of the provided words. Example usage: /api/v1/articles?q[wide_search]=some+search+words.

Retrieving one Article

Thing	Value
URL	/articles/:friendly_id
Method	GET
Successful response	Article

Example response:

{
    "id": 35938,
    "friendly_id": 25,
    "title": "Setting up an email account",
    "text": "<p>Log in to email.example.org. Go to <b>Settings</b> and then add a new email account.</p>",
    "updated_at": "2023-01-03T10:50:27.390Z",
    "category": {
        "id": 1329,
        "friendly_id": 3,
        "name": "New Employee Setup"
    },
    "attachments": [
        {
            "id": 9239332,
            "description": "Detailed instructions for navigating the settings of the email server",
            "size": 1352994,
            "name": "email server instructions.pdf"
        },
    ]
}

Attachments

New Attachment request

Thing	Value
URL	/cis/:friendly_id/attachments/new
URL	/tickets/:friendly_id/attachments/new
URL	/tickets/:friendly_id/comments/:comment_id/attachments/new
Method	GET
Response	Required upload data

Example successful response:

{
  "post_url":  "https://bossdesk-bucket.s3.amazonaws.com",
  "post_fields": {
    "key": "uploads/tmp/attachments/123/342309300/bf5aasdb-a831-3039-ab83-959383846afa8/${filename}",
    "acl": "private",
    "success_action_status": "201",
    "policy": "eyJleHBpcmF0a3MzL2F3czRfcW9uIjoiMjAxOS0wMy...eC1hbXotZGF0ZSI6IjIw",
    "x-amz-credential": "ASDASJDKLSAXSASD/20190307/us-east-1/s3/aws4_request",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-date": "20190307T120423Z",
    "x-amz-signature": "76e402e13a9f107dcc82e09f44deb443b7f0195d3dec2ab00cdbbce0fc4"
  }
}

To direct-upload the Attachment, construct a HTTP POST request to "post_url" and add "post_fields" and the desired file as multipart data. When the request is valid, you'll be responded with an XML document like this:

<?xml version="1.0" encoding="UTF-8"?>
<PostResponse>
  <Location>https://bossdesk-bucket.s3.amazonaws.com/uploads/tmp/attachments/123/342309300/bf5aasdb-a831-3039-ab83-959383846afa8/myfile.pdf</Location>
  <Bucket>bossdesk-bucket</Bucket>
  <Key>uploads/tmp/attachments/123/342309300/bf5aasdb-a831-3039-ab83-959383846afa8/myfile.pdf</Key>
  <ETag>"de7ee7fd70ca589acbacb5cf6531e5820"</ETag>
</PostResponse>

Extract the Key field and use it in the next Attachment creation step.

Creating an Attachment

Thing	Value
URL	/cis/:friendly_id/attachments
URL	/tickets/:friendly_id/attachments
URL	/tickets/:friendly_id/comments/:comment_id/attachments
Method	POST
Response	Attachment or error list

Example parameters (use the Key value as tmp_key:

{
  "attachment": {
    "description": "Uploaded from mobile device",
    "tmp_key": "uploads/tmp/attachments/123/342309300/bf5aasdb-a831-3039-ab83-959383846afa8/myfile.pdf"  // REQUIRED
  }
}

Example successful response:

{
  "id": 2342,
  "name": "myfile.pdf",
  "description": "Uploaded from mobile device",
  "size": 55340,
  "secure_url": "https://bossdesk.s3.amazonaws.com/uploads/attachments/...8e2484/myfile.pdf",
  "created_at": "2018-12-19T12:16:35.368Z",
  "updated_at": "2018-12-19T12:16:35.368Z",
  "created_by": {
    "id":          34222,
    "friendly_id": 15,
    "first_name":  "John",
    "last_name":   "Doe",
    "username":    "doe.john"
  },
  "secure_url_expire_time_in_mins": 10
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "key": ["is invalid"]
  }
}

Retrieving Attachments

Thing	Value
URL	/tickets/:friendly_id/attachments/:id
URL	/tickets/:friendly_id/comments/:comment_id/attachments/:id
URL	/my/tickets/:friendly_id/attachments/:id
URL	/my/tickets/:friendly_id/comments/:comment_id/attachments/:id
URL	/cis/:friendly_id/attachments/:id
URL	/articles/:friendly_id/attachments/:id
Method	GET
Response	Attachment

Example successful response:

{
    "id": 2342,
    "name": "document.odt",
    "description": "Some document that's probably useful",
    "size": 55340,
    "secure_url": "https://bossdesk.s3.amazonaws.com/uploads/attachments/...8e2484",
    "created_at": "2016-12-19T12:16:35.368Z",
    "updated_at": "2016-12-19T12:16:35.368Z",
    "created_by": {
      "id":          34222,
      "friendly_id": 15,
      "first_name":  "John",
      "last_name":   "Doe",
      "username":    "doe.john"
    },
    "secure_url_expire_time_in_mins": 10
}

Retrieving Attachments for Articles

Thing	Value
URL	/articles/:friendly_id/attachments/:id
Method	GET
Response	Attachment

Example successful response:

{
    "id": 2342,
    "name": "document.odt",
    "description": "Some document that's probably useful",
    "size": 55340,
    "secure_url": "https://bossdesk.s3.amazonaws.com/uploads/attachments/...8e2484",
    "secure_url_expire_time_in_mins": 10
}

Updating Attachments

Thing	Value
URL	/cis/:friendly_id/attachments/:id
Method	PATCH
Response	Attachment

Example request:

{
  "attachment": {
    "description": "New description"
  }
}

Example successful response:

{
    "id": 2342,
    "name": "document.odt",
    "description": "New description",
    "size": 55340,
    "secure_url": "https://bossdesk.s3.amazonaws.com/uploads/attachments/...8e2484",
    "created_at": "2016-12-19T12:16:35.368Z",
    "updated_at": "2019-03-07T12:32:52.123Z",
    "created_by": {
      "id":          34222,
      "friendly_id": 15,
      "first_name":  "John",
      "last_name":   "Doe",
      "username":    "doe.john"
    },
    "secure_url_expire_time_in_mins": 10
}

Deleting Attachments

Thing	Value
URL	/cis/:friendly_id/attachments/:id
URL	/tickets/:friendly_id/attachments/:id
Method	DELETE
Response	Attachment

Example successful response:

{
    "id": 2342,
    "name": "document.odt",
    "description": "New description",
    "size": 55340,
    "secure_url": "https://bossdesk.s3.amazonaws.com/uploads/attachments/...8e2484",
    "created_at": "2016-12-19T12:16:35.368Z",
    "updated_at": "2019-03-07T12:32:52.123Z",
    "created_by": {
      "id":          34222,
      "friendly_id": 15,
      "first_name":  "John",
      "last_name":   "Doe",
      "username":    "doe.john"
    },
    "secure_url_expire_time_in_mins": 10
}

CIs

Retrieving the CI list

Thing	Value
URL	/cis
Method	GET
Response	Array of CIs
Pagination	Yes
Search	Yes

Example response:

[
    {
        "id": 185235,
        "friendly_id": 15,
        "name": "BOSS-1000",
        "description": "Boss's computer",
        "online": true,
        "updated_at": "2016-06-23T14:30:54.861Z",
        "archived": false,
        "inventory": {
            "os": {
                "name": "Windows Server 2012 R2 Standard",
                "version": "6.3.9600",
                "service_pack": "1.0",
            }
        },
        "type": {
            "id": 68,
            "name": "Desktop",
            "icon": "fa-bars"
        },
        "status": {
            "id": 94,
            "name": "Active"
        }
    },
    {
        "id": 132523,
        ... // attributes of the other CI
    },
    ...
]

Retrieving one CI

Thing	Value
URL	/cis/:friendly_id
Method	GET
Successful response	CI

Example response:

{
    "id": 185235,
    "friendly_id": 15,
    "name": "BOSS-1000",
    "description": "Boss's computer",
    "model": "Power-X",
    "serial_number": "09384124-2-4124-24s",
    "control_number": "OSIJD-3209-DJOP",
    "type": {
        "id": 68,
        "name": "Desktop",
        "icon": "fa-bars"
    },
    "status": {
        "id": 94,
        "name": "Active"
    },
    "location": {
        "id": 47,
        "name": "Atlanta"
    },
    "manufacturer": {
        "id": 231,
        "name": "Gerlach-Metz Computers"
    },
    "tags": [
        {
            "id": 21,
            "name": "Development"
        }
    ],
    "users": [
        {
            "id": 38923,
            "friendly_id": 28,
            "first_name": "Al",
            "last_name": "Dente",
            "email": "al.dente@example.com",
            "domain_name": "MEGACORP",
            "username": "aldente",
            "group": {
                "id": 39232,
                "name": "Managers"
            },
            "roles": [
                {
                    "id": 23095,
                    "name": "IT"
                },
                {
                    "id": 8533,
                    "name": "Helpdesk"
                }
            ]
        },
        {
            "id": 39239,
            ...
        }
    ],
    "purchase_order": {
        "id": 5,
        "friendly_id": 1,
        "number": "PO12345"
    },
    "custom_fields": {
        "435": "08543-ABF",
        "249": true
    },
    "inventory": {
        "os": {
            "name": "Windows Server 2012 R2 Standard",
            "version": "6.3.9600",
            "service_pack": "1.0",
            "manufacturer_name": "Microsoft Corporation",
            "installation_directory": "C:\\Windows"
        },
        "bios": {
            "name": "PhoenixBIOS 4.0 Release 6.0",
            "version": "INTEL - 6040000",
            "manufacturer": "Phoenix Technologies LTD"
        },
        ...
    },
    "inventory_updated_at": "2016-07-02T19:12:04.985Z",
    "online": true,
    "dns_host_name": "BOSS-1000.int.example.com",
    "distinguished_name": "CN=BOSS-1000,CN=Computers,DC=int,DC=example,DC=com",
    "archived_at": null,
    "created_at": "2016-06-19T10:06:53.350Z",
    "updated_at": "2016-06-23T14:30:54.861Z"
}

Retrieving a CI by barcode

Thing	Value
URL	/cis/by_barcode/:barcode
Method	GET
Successful response	CI

Example response:

{
    "id": 185235,
    "friendly_id": 15,
    "name": "BOSS-1000",
    "description": "Boss's computer",
    "model": "Power-X",
    "serial_number": "09384124-2-4124-24s",
    "control_number": "OSIJD-3209-DJOP",
    "type": {
        "id": 68,
        "name": "Desktop",
        "icon": "fa-bars"
    },
    "status": {
        "id": 94,
        "name": "Active"
    },
    "location": {
        "id": 47,
        "name": "Atlanta"
    },
    "manufacturer": {
        "id": 231,
        "name": "Gerlach-Metz Computers"
    },
    "tags": [
        {
            "id": 21,
            "name": "Development"
        }
    ],
    "purchase_order": {
        "id": 5,
        "friendly_id": 1,
        "number": "PO12345"
    },
    "custom_fields": {
        "435": "08543-ABF",
        "249": true
    },
    "inventory": {
        "os": {
            "name": "Windows Server 2012 R2 Standard",
            "version": "6.3.9600",
            "service_pack": "1.0",
            "manufacturer_name": "Microsoft Corporation",
            "installation_directory": "C:\\Windows"
        },
        "bios": {
            "name": "PhoenixBIOS 4.0 Release 6.0",
            "version": "INTEL - 6040000",
            "manufacturer": "Phoenix Technologies LTD"
        },
        ...
    },
    "inventory_updated_at": "2016-07-02T19:12:04.985Z",
    "online": true,
    "dns_host_name": "BOSS-1000.int.example.com",
    "distinguished_name": "CN=BOSS-1000,CN=Computers,DC=int,DC=example,DC=com",
    "archived_at": null,
    "created_at": "2016-06-19T10:06:53.350Z",
    "updated_at": "2016-06-23T14:30:54.861Z"
}

Creating a CI

Thing	Value
URL	/cis
Method	POST
Response	CI or error list

Example request:

{
    "ci": {
        "name": "TS-21442",                // REQUIRED
        "description": "Marcella",
        "manufacturer_id": 18,
        "model": "Power-X",
        "serial_number": "74-235-5486",
        "control_number": "86-424-0948",
        "status_id": 154,
        "type_id": 44,
        "location_id": 47,
        "tag_ids": [304, 41],
        "user_ids": [932],
        "ticket_ids": [123, 567],
        "custom_fields": {
            "49": true,
            "934": "A-3492-YU"
        }
    }
}

Example successful response:

{
    "id": 1494,
    "friendly_id": 5,
    "name": "TS-21442",
    "description": "Marcella",
    "model": "Power-X",
    "serial_number": "74-235-5486",
    "control_number": "86-424-0948",
    "type": {
        "id": 44,
        "name": "Server"
    },
    "status": {
        "id": 154,
        "name": "Active"
    },
    "location": {
        "id": 47,
        "name": "Atlanta"
    },
    "manufacturer": {
        "id": 18,
        "name": "Treutel-Sanford"
    },
    "tags": [
        {
            "id": 304,
            "name": "Development"
        },
        {
            "id": 41,
            "name": "IT"
        }
    ],
    "users": [
        {
            "id": 932,
            "friendly_id": 28,
            "first_name": "Al",
            "last_name": "Dente",
            "email": "al.dente@example.com",
            "domain_name": "MEGACORP",
            "username": "aldente",
            "roles": []
        }
    ],
    "purchase_order_id": null,
    "custom_fields": {
        "49": true,
        "934": "A-3492-YU"
    },
    "inventory": null,
    "archived_at": null,
    "created_at": "2015-03-07T15:22:04.791Z",
    "updated_at": "2016-03-07T15:22:04.791Z"
}

Example unsuccessful response with validation errors:

{
    "errors": {
        "name": ["can't be blank"]
    }
}

Updating a CI

Thing	Value
URL	/cis/:friendly_id
Method	PATCH
Response	204 No Content

Example request:

{
    "ci": {
        "name": "CI392-R",
        "description": "Boss's laptop",
        "manufacturer_id": 595,
        "model": "Alpha 1",
        "serial_number": "02931-3123-1-23",
        "control_number": "03923-32dg-32rf",
        "status_id": 135,
        "type_id": 864,
        "location_id": 4834,
        "tag_ids": [410],
        "user_ids": [932],
        "ticket_ids": [123],
        "custom_fields": {
            "934": "A-3492-YU"
        }
    }
}

Example successful response is 204 No Content.

Example unsuccessful response with validation errors:

{
    "errors": {
        "name": ["can't be blank"]
    }
}

Deleting a CI

Thing	Value
URL	/cis/:friendly_id
Method	DELETE
Response	204 No Content

Successful response is 204 No Content.

Example unsuccessful response with errors:

{
    "errors": {
        "base": ["can't delete the CI"]
    }
}

CI statuses

Retrieving the CI status list

Thing	Value
URL	/ci_statuses
Method	GET
Response	Array of CI statuses
Pagination	No
Search	No

Example response:

[
    {
        "id": 1,
        "name": "Working",
        "created_at": "2015-06-19T10:04:42.978Z",
        "updated_at": "2015-06-19T10:05:01.566Z"
    },
    {
        "id":6,
        ... // attributes of the other CI status
    },
    ...
]

CI types

Retrieving the CI type list

Thing	Value
URL	/ci_types
Method	GET
Response	Array of CI types
Pagination	No
Search	No

Example response:

[
    {
        "id": 3,
        "parent_id": 1,
        "name": "Computer",
        "created_at": "2015-06-19T10:05:28.549Z",
        "updated_at": "2015-06-19T10:05:28.549Z"
    },
    {
        "id":6,
        ... // attributes of the other CI type
    },
    ...
]

Custom fields

Retrieving the custom field list

Thing	Value
URL	/custom_fields
Method	GET
Response	Array of custom fields
Pagination	No
Search	No

Example response:

[
    {
        "id": 2843,
        "name": "Cost",
        "owner_class": "ci",
        "type_id": 5,
        "option_source": "custom",
        "required": false,
        "position": 0,
        "ci_type": {
            "id": 3923,
            "name": "Hardware"
        },
        "helpdesk_category": null,
        "helpdesk_categories": [],
        "options": [],
        "created_at": "2016-06-19T10:04:42.978Z",
        "updated_at": "2016-06-19T10:05:01.566Z"
    },
    {
        "id": 2845,
        "name": "Incident type",
        "owner_class": "ticket",
        "type_id": 8,
        "option_source": "custom",
        "required": false,
        "position": 1,
        "ci_type": null,
        "helpdesk_category": {
            "id": 3227,
            "name": "Network"
        },
        "helpdesk_categories": [
          {
            "id": 3227,
            "name": "Network"
          },
          {
            "id": 3289,
            "name": "Hardware"
          }          
        ],
        "options": [
            {
                "id": 3932,
                "name": "Broken switch"
            },
            {
                "id": 3933,
                "name": "Broken cable"
            },
            {
                "id": 3934,
                "name": "Other"
            },
        ],
        "created_at": "2016-06-19T10:04:42.978Z",
        "updated_at": "2016-06-19T10:05:01.566Z"
    },
    {
        "id": 2964,
        ... // attributes of the other custom field
    },
    ...
]

Possible owner_class values are: "ci", "ticket", "problem", "change", "vendor", "user" and "contract".

Possible type_id values and corresponding custom field data types are:

1 - string
2 - text
3 - URL
4 - integer
5 - float
6 - date
7 - boolean
8 - dropdown
11 - cascading dropdown
14 - datetime

Possible option_source values are: "custom" and "locations". The options array is only populated when the option source is "custom". In other cases, the options should be populated from a relevant source (locations listing when the source is "locations" etc).

NB! Property "helpdesk_category" is there for backwards-compatibility. There's now one-to-many relationship between Custom Fields and Helpdesk Categories which means there can be multiple per one Custom Field. Applications should use the new "helpdesk_categories" array instead.

Groups

Retrieving the Group list

Thing	Value
URL	/groups
Method	GET
Response	Array of Groups
Pagination	Yes
Search	Yes

Example response:

[
    {
        "id": 7331,
        "name": "Chicago Bulls",
        "created_at": "2019-05-19T18:24:52.921Z",
        "updated_at": "2016-06-09T10:05:01.566Z"
    }
]

Helpdesk categories

Thing	Value
URL	/helpdesk_categories
Method	GET
Response	Array of categories
Pagination	No
Search	No

Example response:

[
    {
        "id": 3,
        "name": "Email",
        "color": "rgb(88, 214, 141)",
        "icon": "fa fa-fw fa-envelope",
        "created_at": "2016-06-14T14:28:08.718Z",
        "updated_at": "2016-06-14T14:28:08.718Z",
        "teams": [
            {
                "id": 129,
                "name": "Database"
            },
            {
                "id": 324,
                "name": "Major Incident"
            }
        ]
    },
    {
        "id":6,
        ... // attributes of the other category
    },
    ...
]

Helpdesk extended statuses

Retrieving the helpdesk extended statuses list

Thing	Value
URL	/helpdesk_extended_statuses
Method	GET
Response	Array of extended statuses
Pagination	No
Search	No

Example response:

[
    {
        "id": 3,
        "name": "On hold",
        "created_at": "2016-05-12T13:20:45.033Z",
        "updated_at": "2016-07-07T09:03:57.028Z"
    },
    {
        "id": 6,
        ... // attributes of the other extended status
    },
    ...
]

Helpdesk priorities

Retrieving the helpdesk priorities list

Thing	Value
URL	/helpdesk_priorities
Method	GET
Response	Array of priorities
Pagination	No
Search	No

Example response:

[
    {
        "id": 3,
        "name": "High",
        "color": "rgb(246, 135, 0)",
        "level": 2,
        "created_at": "2016-05-12T13:20:45.033Z",
        "updated_at": "2016-07-07T09:03:57.028Z"
    },
    {
        "id": 6,
        ... // attributes of the other priority
    },
    ...
]

Locations

Retrieving the location list

Thing	Value
URL	/locations
Method	GET
Response	Array of locations
Pagination	No
Search	No

Example response:

[
    {
        "id": 2843,
        "name": "Europe",
        "parent_id": null,
        "created_at": "2016-06-19T10:04:42.978Z",
        "updated_at": "2016-06-19T10:05:01.566Z"
    },
    {
        "id":6,
        ... // attributes of the other location
    },
    ...
]

Manufacturers

Retrieving the manufacturer list

Thing	Value
URL	/manufacturers
Method	GET
Response	Array of manufacturers
Pagination	Yes
Search	Yes

Example response:

[
    {
        "id": 2843,
        "name": "BOSS Inc.",
        "updated_at": "2016-06-19T10:05:01.566Z"
    },
    {
        "id": 6,
        ... // attributes of the other manufacturer
    },
    ...
]

Notes

Adding a Note to a CI

Thing	Value
URL	/cis/:friendly_id/notes
Method	POST
Response	201 Created

Example parameters:

{
  "note": {
    "text": "Note this!"
  }
}

Example successful response is 201 Created:

{
    "id": 1506,
    "text": "Note this!",
    "created_at": "2019-03-01T12:56:23.623Z",
    "updated_at": "2019-03-01T12:56:23.623Z",
    "created_by": {
        "id": 2634,
        "friendly_id": 65,
        "first_name": "Jack",
        "last_name": "Pot",
        "username": "jackpot"
    }
}

Example unsuccessful response with validation errors:

{
    "errors": {
        "text": ["can't be blank"]
    }
}

Updating a Note on a CI

Thing	Value
URL	/cis/:friendly_id/notes/:id
Method	PATCH
Response	200 OK

Example request:

{
  "note": {
    "text": "Updated note"
  }
}

Example successful response is 200 OK.

{
    "id": 1506,
    "text": "Updated note",
    "created_at": "2019-03-01T12:56:23.623Z",
    "updated_at": "2019-03-05T17:01:43.324Z",
    "created_by": {
        "id": 2634,
        "friendly_id": 65,
        "first_name": "Jack",
        "last_name": "Pot",
        "username": "jackpot"
    }
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "text": ["can't be blank"]
  }
}

Deleting a Note on a CI

Thing	Value
URL	/cis/:friendly_id/notes/:id
Method	DELETE
Response	200 OK

Request should not contain body.

Example successful response is 200 OK.

{
    "id": 1506,
    "text": "Updated note",
    "created_at": "2019-03-01T12:56:23.623Z",
    "updated_at": "2019-03-05T17:01:43.324Z",
    "created_by": {
        "id": 2634,
        "friendly_id": 65,
        "first_name": "Jack",
        "last_name": "Pot",
        "username": "jackpot"
    }
}

Saved searches

Retrieving the search list

Thing	Value
URL	/searches
Method	GET
Response	Array of searches
Pagination	No
Search	No

Example response:

[
    {
        "id": 2843,
        "name": "All printers",
        "created_at": "2016-06-19T10:05:01.566Z",
        "updated_at": "2016-06-19T10:05:01.566Z",
        "owner_class": "ci",
        "my_search": false
    },
    {
        "id": 6,
        ... // attributes of the other search
    },
    ...
]

Applying a search

Thing	Value
URL	/searches/:id
Method	GET
Successful response	Array of objects
Pagination	Yes

Response depends on the search's owner class ("ci", "ticket", etc). Only CI and Ticket searches are currently implemented. When trying to apply a Problem (or any other) search, 501 Not Implemented will be returned.

Example response for a CI search:

[
    {
        "id": 185235,
        "friendly_id": 15,
        "name": "BOSS-1000",
        "alias": "Boss's computer",
        "online": true,
        "updated_at": "2016-06-23T14:30:54.861Z",
        "inventory": {
            "os": {
                "name": "Windows Server 2012 R2 Standard",
                "version": "6.3.9600",
                "service_pack": "1.0",
            }
        },
        "type": {
            "id": 68,
            "name": "Desktop",
            "icon": "fa-bars"
        },
        "status": {
            "id": 94,
            "name": "Active",
            "color": "#34B632"
        }
    },
    {
        "id": 132523,
        ... // attributes of an other CI
    },
    ...
]

Software

Retrieving CI's Software list

Thing	Value
URL	/cis/:friendly_id/softwares
Method	GET
Response	Array of Software
Pagination	Yes
Search	No

Example response:

[
  {
    "id": 39532,
    "name": "Adobe Acrobat Reader",
    "type_id": 1,
    "license_count": 3,
    "created_at": "2017-04-21T15:19:50.000Z",
    "updated_at": "2018-05-19T16:00:12.000Z",
    "authorized": true,
    "version": "17.009.20044",
    "manufacturer": {
      "id": 48348,
      "name": "Adobe"
    }
  }
]

Possible type_id values and their meanings are:

1 - Software
2 - Windows update
3 - Operating System

Thing	Value
URL	/tags
Method	GET
Response	Array of tags
Pagination	No
Search	No

Tasks

Adding Task to Ticket

Thing	Value
URL	/tickets/:friendly_id/tasks
Method	POST
Response	201 Created

Example parameters:

{
  "task": {
    "type_id": 1242,
    "team_id": 2352,
    "agent_id":  34222,
    "title": "Figure out the meaning of this ticket", # REQUIRED
    "note":  "Note this!",
    "due_at": "2018-11-28 15:00:00"
  }
}

Example successful response is 201 Created:

{
    "id":       10755,
    "title":    "Figure out the meaning of this ticket",
    "note":     "Note this!",
    "due_at":   "2018-11-28T15:00:00.000Z",
    "closed_at": null,
    "type": {
      "id":   1001,
      "name": "Sample Task type"
    },
    "team": {
      "id":   1009,
      "name": "A-Team"
    },
    "agent": {
      "id":          34222,
      "friendly_id": 15,
      "first_name":  "John",
      "last_name":   "Doe",
      "username":    "doe.john"
    },
}

Example unsuccessful response with validation errors:

{
    "errors": {
        "title": ["can't be blank"]
    }
}

Updating Task on a Ticket

Thing	Value
URL	/tickets/:friendly_id/tasks/:id
Method	PATCH
Response	204 No Content

Example request:

{
  "task": {
    "note": "Updated note"
  }
}

Example successful response is 204 No Content.

Example unsuccessful response with validation errors:

{
  "errors": {
    "title": ["can't be blank"]
  }
}

Closing a Task on a Ticket

Thing	Value
URL	/tickets/:friendly_id/tasks/:id/close
Method	PATCH
Response	200 OK

Example request:

{
  "task": {
    "note": "Updated note"
  }
}

Example response:

{
    "id":       10755,
    "title":    "Figure out the meaning of this ticket",
    "note":     "Updated note",
    "due_at":   "2018-11-28T15:00:00.000Z",
    "closed_at": "2018-11-27T14:45:75.352Z",
    "type": {
      "id":   1001,
      "name": "Sample Task type"
    },
    "team": {
      "id":   1009,
      "name": "A-Team"
    },
    "agent": {
      "id":          34222,
      "friendly_id": 15,
      "first_name":  "John",
      "last_name":   "Doe",
      "username":    "doe.john"
    },
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "title": ["can't be blank"]
  }
}

Reopening a Task on a Ticket

Thing	Value
URL	/tickets/:friendly_id/tasks/:id/reopen
Method	PATCH
Response	200 OK

Example response:

{
    "id":       10755,
    "title":    "Figure out the meaning of this ticket",
    "note":     "Updated note",
    "due_at":   "2018-11-28T15:00:00.000Z",
    "closed_at": null,
    "type": {
      "id":   1001,
      "name": "Sample Task type"
    },
    "team": {
      "id":   1009,
      "name": "A-Team"
    },
    "agent": {
      "id":          34222,
      "friendly_id": 15,
      "first_name":  "John",
      "last_name":   "Doe",
      "username":    "doe.john"
    },
}

Deleting Task on Ticket

Thing	Value
URL	/tickets/:friendly_id/tasks/:id
Method	DELETE
Response	204 No Content

Request should not contain body. Successful response is 204 No Content.

Task types

Retrieving the Task type list

Thing	Value
URL	/task_types
Method	GET
Response	Array of task types
Pagination	No
Search	No

Example response:

[
    {
        "id": 3,
        "name": "Development",
        "created_at": "2018-06-19T10:05:28.549Z",
        "updated_at": "2018-06-19T10:05:28.549Z"
    }
]

Teams

Retrieving the Team list

Thing	Value
URL	/teams
Method	GET
Response	Array of teams
Pagination	No
Search	No

Example response:

[
    {
        "id": 123,
        "friendly_id": 5,
        "name": "Hardware Team",
        "created_at": "2018-06-19T10:05:28.549Z",
        "updated_at": "2018-06-19T10:05:28.549Z"
    }
]

Retrieving one Team

Thing	Value
URL	/teams/:friendly_id
Method	GET
Successful response	Team

Example response:

{
  "id": 123,
  "friendly_id": 5,
  "name": "Hardware Team",
  "created_at": "2018-06-19T10:05:28.549Z",
  "updated_at": "2018-06-19T10:05:28.549Z",
  "members": [
    {
      "id":          34222,
      "friendly_id": 15,
      "first_name":  "John",
      "last_name":   "Doe",
      "username":    "doe.john"
    }
  ]
}

Tickets

Retrieving the ticket list

Thing	Value
URL	/tickets
Method	GET
Response	Array of Tickets
Pagination	Yes
Search	Yes

Example response:

[
    {
        "id": 185235,
        "friendly_id": 15,
        "title": "My black and white printer started printing colours...",
        "status": "incoming",
        "due_at": "2016-10-23T14:30:54.861Z",
        "type": {
          "id": 21,
          "name": "Bug Reports",
          "shortcut": "BUG"
        },
        "priority": {
          "id": 1,
          "name": "Low",
          "color": "rgb(133, 211, 132)"
        },
        "category": {
          "id": 13,
          "name": "Hardware",
          "color": "rgb(37, 160, 218)",
          "icon": "fa fa-fw fa-desktop"
        },
        "extended_status": {
          "id": 3,
          "name": "Waiting on Customer"
        },
        "requester": {
          "id": 22553,
          "friendly_id": 5094,
          "first_name": "Jack",
          "last_name": "Pot",
          "username": "jackpot"
        },
        "agent": {
          "id": 22571,
          "friendly_id": 5112,
          "first_name": "Al",
          "last_name": "Dente",
          "username": "aldente"
        }
    },
    {
        "id": 132523,
        ... // attributes of the other ticket
    },
    ...
]

Retrieving one ticket

Thing	Value
URL	/tickets/:friendly_id
Method	GET
Successful response	Ticket

Example response:

{
  "id": 100,
  "friendly_id": 75,
  "title": "My harddrive email socket is not responding :(",
  "description": "<p>First paragraph</p><p>Second paragraph</p>",
  "status": "assigned",
  "source": "user_portal",
  "custom_fields": {
    "20": "2016-10-20",
    "29": 12
  },
  "created_at": "2016-10-12T08:50:29.274Z",
  "updated_at": "2016-10-18T09:29:04.178Z",
  "due_at": "2016-10-25T16:15:56.382Z",
  "closed_at": null,
  "lock_version": 2,
  "type": {
    "id": 21,
    "name": "Bug Reports",
    "shortcut": "BUG"
  },
  "priority": {
    "id": 1,
    "name": "Low",
    "color": "rgb(133, 211, 132)"
  },
  "category": {
    "id": 13,
    "name": "Email",
    "color": "rgb(88, 214, 141)",
    "icon": "fa fa-fw fa-envelope"
  },
  "agent": {
    "id": 11905,
    "friendly_id": 1,
    "first_name": "Jack",
    "last_name": "Pot",
    "username": "jackpot"
  },
  "team": {
    "id": 13,
    "name": "Email"
  },
  "extended_status": {
    "id": 3,
    "name": "Waiting on Customer"
  },
  "requester": {
    "id": 2153,
    "friendly_id": 94,
    "first_name": "Al",
    "last_name": "Dente",
    "username": "aldente",
    "is_agent": false,
    "email": "al.dente@example.com",
    "phone": "+23 049 230 584",
    "mobile": "+38 292 823 191",
    "group": {
      "id": 6,
      "name": "Purchasing"
    }
  },
  "comments": [
    {
      "id": 58,
      "body": "<p>Not sure if serious.... hmm...<br></p>",
      "created_at": "2016-10-17T13:10:18.138Z",
      "is_public": false,
      "from_agent": true,
      "source": "web_portal",
      "created_by": {
        "id": 25963,
        "friendly_id": 5123,
        "first_name": "Jack",
        "last_name": "Pot",
        "username": "jackpot"
      },
      "attachments": [
        {
          "id": 21,
          "description": null,
          "name": "image.jpg",
          "created_at": "2016-10-17T13:10:18.140Z",
          "size": 32032
        }
      ]
    }
  ],
  "tags": [
    {
      "id": 54,
      "name": "email"
    },
    {
      "id": 55,
      "name": "software"
    }
  ],
  "attachments": [
    {
      "id": 21,
      "description": null,
      "name": "screenshot.jpg",
      "created_at": "2016-10-17T13:10:18.140Z",
      "size": 832032
    }
  ],
  "time_entries": [
    {
      "id": 13,
      "task_id": 15,
      "date": "2016-10-17",
      "duration": 150,
      "billable": false,
      "agent": {
        "id": 25963,
        "friendly_id": 5123,
        "first_name": "Barry",
        "last_name": "Cade",
        "username": "barrycade"
      },
      "task": {
        "id": 15,
        "title": "An action"
      }
    }
  ],
  "tasks": [
    {
      "id": 15,
      "title": "An action",
      "note": "",
      "created_at": "2016-10-23T12:45:74.234Z",
      "due_at": "2016-10-25T21:00:00.000Z",
      "closed_at": null,
      "type": {
        "id": 2,
        "name": "Communication"
      },
      "team": {
        "id": 13,
        "name": "Email"
      },
      "agent": null,
      "created_by": {
        "id": 2563,
        "friendly_id": 513,
        "first_name": "Barry",
        "last_name": "Cade",
        "username": "barrycade"
      }
    }
  ],
  "problem": {
    "id": 1,
    "friendly_id": 1,
    "title": "People are reporting bugs"
  },
  "change": {
    "id": 1,
    "friendly_id": 1,
    "title": "Disable bug reporting functionality"
  },
  "approval_requests": [
    {
      "id": 92,
      "status": "sent",
      "comment": null,
      "created_at": "2016-10-12T08:50:29.404Z",
      "responded_at": null,
      "user": {
        "id": 22554,
        "friendly_id": 5095,
        "first_name": "Don",
        "last_name": "Key",
        "username": "donkey"
      }
    },
    {
      "id": 93,
      "status": "sent",
      "comment": null,
      "created_at": "2016-10-12T08:50:29.538Z",
      "responded_at": null,
      "user": {
        "id": 18676,
        "friendly_id": 5093,
        "first_name": "Gene",
        "last_name": "Poole",
        "username": "genepoole"
      }
    }
  ],
  "cis": [
    {
      "id": 16673,
      "friendly_id": 4508,
      "name": "COMPUTER-87",
      "online": true,
      "updated_at": "2016-08-12T14:48:29.204Z",
      "inventory_updated_at": "2016-08-13T14:48:29.204Z",
      "archived_at": null,
      "os": "Windows 98 Internet Edition",
      "type": {
        "id": 104,
        "name": "Computer",
        "icon": "zmdi zmdi-hc-fw zmdi-devices"
      },
      "status": {
        "id": 26,
        "name": "Active",
        "color": "#34B632"
      }
    }
  ]
}

Creating a ticket

Thing	Value
URL	/tickets
Method	POST
Response	Ticket or error list

Example request:

{
    "ticket": {
        "title": "How do I turn on my computer mouse?",    // REQUIRED
        "description": "<p>Like the title says...</p>",
        "type_id": 18,                                     // REQUIRED
        "priority_id": 983,                                // REQUIRED
        "extended_status_id": 346,
        "category_id": 154,
        "requester_id": 3852,
        "team_id": 44,
        "agent_id": 47,
        "tag_ids": [304, 41],
        "ci_ids": [493, 391],
        "custom_fields": {
            "49": true,
            "934": "Yes, I tried restarting."
        }
    }
}

Example successful response (same fields as retrieving a single ticket):

{
    "id": 1494,
    "friendly_id": 54,
    "title": "How do I turn on my computer mouse?",
    ...
}

Example unsuccessful response with validation errors:

{
    "errors": {
        "title": ["can't be blank"]
    }
}

Updating a ticket

Thing	Value
URL	/tickets/:friendly_id
Method	PATCH
Response	204 No Content

Example parameters:

{
    "ticket": {
        "title": "How do I turn on my computer mouse?",
        "description": "<p>Like the title says...</p>",
        "type_id": 18,
        "priority_id": 983,
        "extended_status_id": 346,
        "category_id": 154,
        "requester_id": 3852,
        "team_id": 44,
        "agent_id": 47,
        "tag_ids": [304, 41, 42],
        "ci_ids": [493, 391],
        "custom_fields": {
            "49": false,
            "934": "Will have to visit the user."
        },
        "lock_version": 2
    }
}

Example successful response is 204 No Content.

Example unsuccessful response with validation errors:

{
    "errors": {
        "title": ["can't be blank"]
    }
}

Adding a comment to a ticket

Thing	Value
URL	/tickets/:friendly_id/comments
Method	POST
Response	201 Created

Example parameters:

{
    "comment": {
        "body": "<p>Comment, <em>woo</em>!</p>",
        "is_public": true                            // REQUIRED
    }
}

Example successful response is 201 Created:

{
    "id": 1494,
    "body": "<p>Comment, <em>woo</em>!</p>",
    "is_public": true,
    "from_agent": true,
    "source": "mobile_app",
    "created_at": "2016-11-01T14:47:37.168Z",
    "created_by": {
        "id": 2463,
        "friendly_id": 548,
        "first_name": "Al",
        "last_name": "Dente",
        "username": "aldente"
    },
    "attachments": []
}

Example unsuccessful response with validation errors:

{
    "errors": {
        "is_public": ["can't be blank"]
    }
}

Closing a ticket

Thing	Value
URL	/tickets/:friendly_id/close
Method	PATCH
Response	Ticket or error list

Example request:

{}

Example successful response (same fields as retrieving a single ticket):

{
    "id": 1494,
    "friendly_id": 54,
    "title": "How do I turn on my computer mouse?",
    ...
}

Example unsuccessful response with errors:

{
    "errors": {
        "base": ["can't be closed because of this and that"]
    }
}

Reopening a ticket

Thing	Value
URL	/tickets/:friendly_id/reopen
Method	PATCH
Response	Ticket or error list

Example request:

{}

Example successful response (same fields as retrieving a single ticket):

{
    "id": 1494,
    "friendly_id": 54,
    "title": "How do I turn on my computer mouse?",
    ...
}

Example unsuccessful response with errors:

{
    "errors": {
        "base": ["can't be opened because of this and that"]
    }
}

Tickets for end-users

These requests are for end-user side of your application. They return tickets that the User is a requester to.

Retrieving the ticket list

Thing	Value
URL	/my/tickets
Method	GET
Response	Array of Tickets
Pagination	Yes
Search	Yes

Example response:

[
    {
        "id": 185235,
        "friendly_id": 15,
        "title": "My black and white printer started printing colours...",
        "status": "open",
        "due_at": "2016-10-23T14:30:54.861Z",
        "type": {
          "id": 21,
          "name": "Bug Reports",
          "shortcut": "BUG"
        },
        "agent": {
          "id": 22571,
          "friendly_id": 5112,
          "first_name": "Al",
          "last_name": "Dente"
        }
    }
]

Retrieving one ticket

Thing	Value
URL	/my/tickets/:friendly_id
Method	GET
Successful response	Ticket

Example response:

{
  "id": 100,
  "friendly_id": 75,
  "title": "My harddrive email socket is not responding :(",
  "description": "<p>First paragraph</p><p>Second paragraph</p>",
  "status": "open",
  "created_at": "2016-10-12T08:50:29.274Z",
  "updated_at": "2016-10-18T09:29:04.178Z",
  "due_at": "2016-10-25T16:15:56.382Z",
  "closed_at": null,
  "type": {
    "id": 21,
    "name": "Bug Reports",
    "shortcut": "BUG"
  },
  "agent": {
    "id": 11905,
    "friendly_id": 1,
    "first_name": "Jack",
    "last_name": "Pot"
  },
  "comments": [
    {
      "id": 58,
      "body": "<p>Not sure if serious.... hmm...<br></p>",
      "created_at": "2016-10-17T13:10:18.138Z",
      "created_by": {
        "id": 25963,
        "friendly_id": 5123,
        "first_name": "Jack",
        "last_name": "Pot"
      },
      "attachments": [
        {
          "id": 21,
          "description": null,
          "name": "image.jpg",
          "created_at": "2016-10-17T13:10:18.140Z",
          "size": 32032
        }
      ]
    }
  ],
  "attachments": [
    {
      "id": 21,
      "description": null,
      "name": "screenshot.jpg",
      "created_at": "2016-10-17T13:10:18.140Z",
      "size": 832032
    }
  ]
}

Creating a ticket

Thing	Value
URL	/my/tickets
Method	POST
Response	Ticket or error list

Example request:

{
    "ticket": {
        "title": "How do I turn on my computer mouse?",    // REQUIRED
        "description": "<p>Like the title says...</p>",
        "type_id": 18,                                     // REQUIRED
    }
}

Example successful response (same fields as retrieving a single ticket):

{
    "id": 1494,
    "friendly_id": 54,
    "title": "How do I turn on my computer mouse?",
    ...
}

Example unsuccessful response with validation errors:

{
    "errors": {
        "title": ["can't be blank"]
    }
}

Adding a comment to a ticket

Thing	Value
URL	/my/tickets/:friendly_id/comments
Method	POST
Response	201 Created

Example parameters:

{
    "comment": {
        "body": "<p>Comment, <em>woo</em>!</p>"   // REQUIRED
    }
}

Example successful response is 201 Created:

{
    "id": 1494,
    "body": "<p>Comment, <em>woo</em>!</p>",
    "created_at": "2016-11-01T14:47:37.168Z",
    "created_by": {
        "id": 2463,
        "friendly_id": 548,
        "first_name": "Al",
        "last_name": "Dente"
    },
    "attachments": []
}

Example unsuccessful response with validation errors:

{
    "errors": {
        "body": ["can't be blank"]
    }
}

Reopening a ticket

Thing	Value
URL	/my/tickets/:friendly_id/reopen
Method	PATCH
Response	Ticket or error list

Example request:

{}

Example successful response (same fields as retrieving a single ticket):

{
    "id": 1494,
    "friendly_id": 54,
    "title": "How do I turn on my computer mouse?",
    ...
}

Example unsuccessful response with errors:

{
    "errors": {
        "base": ["can't be opened because of this and that"]
    }
}

Ticket types

Retrieving the ticket type list

Thing	Value
URL	/ticket_types
Method	GET
Response	Array of ticket types
Pagination	No
Search	No

Example response:

[
    {
        "id": 3,
        "name": "Incident",
        "shortcut": "IN",
        "created_at": "2015-06-19T10:05:28.549Z",
        "updated_at": "2015-06-19T10:05:28.549Z"
    },
    {
        "id":6,
        ... // attributes of the other ticket type
    },
    ...
]

Time Entries

Adding Time Entry to Ticket

Thing	Value
URL	/tickets/:friendly_id/time_entries
Method	POST
Response	201 Created

Example parameters:

{
  "time_entry": {
    "agent_id":  34222,        # OPTIONAL, DEFAULTS TO CURRENT USER ID
    "date":      "31-12-2017", # REQUIRED
    "duration":  60,           # REQUIRED
    "billable":  true,         # OPTIONAL, DEFAULTS TO FALSE
    "task_id":   1001,
    "note": "herp-derp"
  }
}

Example successful response is 201 Created:

{
    "id":      10755,
    "date":    "2017-12-31",
    "duration": 60,
    "task_id": 1001,
    "billable": true,
    "agent": {
        "id":          34222,
        "friendly_id": 15,
        "first_name":  "John",
        "last_name":   "Doe",
        "username":    "doe.john"
    },
    "task": {
        "id":    1001,
        "title": "Sample Task"
    }
}

Example unsuccessful response with validation errors:

{
    "errors": {
        "duration": ["can't be blank"]
    }
}

Updating Time Entry on Ticket

Thing	Value
URL	/tickets/:friendly_id/time_entries/:id
Method	PATCH
Response	204 No Content

Example request:

{
  "time_entry": {
    "duration": 120
  }
}

Example successful response is 204 No Content.

Example unsuccessful response with validation errors:

{
    "errors": {
        "duration": ["can't be blank"]
    }
}

Deleting Time Entry on Ticket

Thing	Value
URL	/tickets/:friendly_id/time_entries/:id
Method	DELETE
Response	204 No Content

Request should not contain body. Successful response is 204 No Content.

Users

Retrieving the user list

Thing	Value
URL	/users
Method	GET
Response	Array of users
Pagination	Yes
Search	Yes

Example response:

[
    {
        "id": 8428,
        "friendly_id": 24,
        "first_name": "Nia",
        "last_name": "Feeney",
        "username": "nfeeney",
        "email": "nfeeney@example.com",
        "is_agent": false,
        "archived_at": null,
        "updated_at": "2016-06-19T10:05:01.566Z"
    },
    {
        "id": 8429,
        ... // attributes of the other user
    },
    ...
]

Retrieving one user

Thing	Value
URL	/users/:friendly_id
Method	GET
Successful response	User

Example response:

{
    "id": 834,
    "friendly_id": 30,
    "email": "jack.pot@example.com",
    "first_name": "Jack",
    "last_name": "Pot",
    "username": "jackpot",
    "domain_name": "SOMECORP",
    "designation": "IT technician",
    "phone": "+139 2349 93294",
    "mobile": "+842 239 2039",
    "other_email": "jackp@example.com",
    "time_zone": "Eastern Time (US & Canada)",
    "is_agent": true,
    "archived_at": null,
    "created_at": "2015-06-25T11:50:09.067Z",
    "updated_at": "2015-06-25T11:50:09.067Z",
    "location": {
        "id": 24,
        "name": "Atlanta"
    },
    "tags": [
        {
            "id": 9,
            "name": "Intern"
        }
    ],
    "groups": [
        {
            "id": 32,
            "name": "Interns"
        }
    ],
    "roles": [
        {
            "id": 2,
            "name": "Technician"
        },
        {
            "id": 3,
            "name": "Manager"
        }
    ],
    "teams": [
        {
            "id": 253,
            "name": "Sales"
        }
    ],
    "custom_fields": {
        "484": "Room 109",
        "872": 399
    }
}

Creating a user

Thing	Value
URL	/users
Method	POST
Response	User or error list

Example parameters:

{
    "user": {
        "username": "whilpert",                   // REQUIRED FIELD
        "email": "whilpert@example.com",
        "first_name": "Westley",
        "last_name": "Hilpert",
        "domain_name": "",
        "designation": "",
        "location_id": null,
        "phone": "",
        "mobile": "",
        "other_email": "",
        "time_zone": "",
        "tag_ids": [],
        "group_ids": [],
        "custom_fields": {}
    }
}

Example successful response:

{
    "id": 835,
    "friendly_id": 31,
    "email":"whilpert@example.com",
    "first_name":"Westley",
    "last_name":"Hilpert",
    "username": "whilpert",
    "domain_name": "",
    "designation": "",
    "phone": "",
    "mobile": "",
    "other_email": "",
    "time_zone": "Eastern Time (US & Canada)",
    "is_agent": false,
    "archived_at": null,
    "created_at": "2015-06-25T11:50:09.067Z",
    "updated_at": "2015-06-25T11:50:09.067Z",
    "location": null,
    "tags": [],
    "groups": [],
    "roles": [],
    "custom_fields": {}
}

Example unsuccessful response with validation errors:

{
    "errors": {
        "email": ["is invalid"],
        "username": ["can't be blank"]
    }
}

Updating a user

Thing	Value
URL	/users/:friendly_id
Method	PATCH
Response	204 No Content

Example parameters:

{
    "user": {
        "email": "rdurgan@example.com",
        "first_name": "Raoul",
        "last_name": "Durgan",
        "username": "rdurgan",
        "domain_name": "",
        "designation": "International Accountability Analyst",
        "location_id": 24,
        "phone": "522-319-4205 x158",
        "mobile": "",
        "other_email": "",
        "time_zone": "Santiago",
        "role_ids": [3, 5],
        "tag_ids": [9, 14],
        "group_ids": [15],
        "custom_fields": {
            "484": "Room 109",
            "872": 399
        }
    }
}

Example successful response is 204 No Content.

Example unsuccessful response with validation errors:

{
    "errors": {
        "email": ["is invalid"]
    }
}

Pagination

By default 15 items are returned. Here is how you can traverse the pages.

Page

You can specify the next page by including the page parameter like this:

https://domain/api/v1/users?page=2

The page param is 1-based.

Per page

To specify how many items per page you want use the per_page parameter like this:

https://domain/api/v1/users?per_page=20

The default is 15 with a minimum of 1 and a maximum of 30.

Search

You may want to filter results on certain listings that support it (users, manufacturers, etc). You can use Ransack and its predicates to achieve that.

For example, if you want to search for users whose last name is Foley, you append the "q" parameter and the "eq" predicate to the query:

https://domain/api/v1/users?q[last_name_eq]=Foley

You can also search using multiple filters:

https://domain/api/v1/users?q[last_name_eq]=Foley&q[first_name_eq]=Axel

General information

API URL

Request headers

Response codes

Other things to keep in mind

Using the API

"Logging in" or retrieving user's API key and permissions info

Account

Retrieving account info and settings

Approval Requests

Creating a new Ticket Approval Request

Approving an Approval Request on a Ticket

Disapproving an Approval Request on a Ticket

Canceling an Approval Request on a Ticket

Sending a reminder for an Approval Request on a Ticket

Articles

Retrieving the Article list

Retrieving one Article

Attachments

New Attachment request

Creating an Attachment

Retrieving Attachments

Retrieving Attachments for Articles

Updating Attachments

Deleting Attachments

CIs

Retrieving the CI list

Retrieving one CI

Retrieving a CI by barcode

Creating a CI

Updating a CI

Deleting a CI

CI statuses

Retrieving the CI status list

CI types

Retrieving the CI type list

Custom fields

Retrieving the custom field list

Groups

Retrieving the Group list

Helpdesk categories

Retrieving the helpdesk categories list

Helpdesk extended statuses

Retrieving the helpdesk extended statuses list

Helpdesk priorities

Retrieving the helpdesk priorities list

Locations

Retrieving the location list

Manufacturers

Retrieving the manufacturer list

Notes

Adding a Note to a CI

Updating a Note on a CI

Deleting a Note on a CI

Saved searches

Retrieving the search list

Applying a search

Software

Retrieving CI's Software list

Tags

Retrieving the tag list

Tasks

Adding Task to Ticket

Updating Task on a Ticket

Closing a Task on a Ticket

Reopening a Task on a Ticket

Deleting Task on Ticket

Task types

Retrieving the Task type list

Teams

Retrieving the Team list

Retrieving one Team

Tickets

Retrieving the ticket list

Retrieving one ticket

Creating a ticket

Updating a ticket

Adding a comment to a ticket

Closing a ticket

Reopening a ticket