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

With every request you must set the following Authorization and Content-Type headers:

  • 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"
  }
}

Attachments

New Attachment request

Thing Value
URL /cis/:friendly_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
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
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
}

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
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],
        "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],
        "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,
        "required": false,
        "position": 0,
        "ci_type": {
            "id": 3923,
            "name": "Hardware"
        },
        "helpdesk_category": null,
        "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,
        "required": false,
        "position": 1,
        "ci_type": null,
        "helpdesk_category": {
            "id": 3227,
            "name": "Network"
        },
        "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" and "release".

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

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

Retrieving the helpdesk categories list

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
    },
    ...
]
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
    },
    ...
]

Tags

Retrieving the tag list

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

Example response:

[
    {
        "id": 2843,
        "name": "Development",
        "owner_class": "ci",
        "created_at": "2016-06-19T10:04:42.978Z",
        "updated_at": "2016-06-19T10:05:01.566Z"
    },
    {
        "id": 2964,
        ... // attributes of the other tag
    },
    ...
]

Possible owner_class values are: "ci", "user" and "ticket".

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": 3,
        "name": "Hardware Team",
        "created_at": "2018-06-19T10:05:28.549Z",
        "updated_at": "2018-06-19T10:05:28.549Z"
    }
]

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],
        "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],
        "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"
        }
    ],
    "group": {
        "id": 32,
        "name": "Interns"
    },
    "roles": [
        {
            "id": 2,
            "name": "Technician"
        },
        {
            "id": 3,
            "name": "Manager"
        }
    ]
}

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,
        "group_id"; null,
        "phone": "",
        "mobile": "",
        "other_email": "",
        "time_zone": "",
        "tag_ids": []
    }
}

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": [],
    "group": null,
    "roles": []
}

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,
        "group_id": 15,
        "phone": "522-319-4205 x158",
        "mobile": "",
        "other_email": "",
        "time_zone": "Santiago",
        "role_ids": [3, 5],
        "tag_ids": [9, 14]
    }
}

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.

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