API V2 Documentation

This document is the documentation for using your BOSS811 account through the API version 2.

General information

API URL

The API URL is https://[your-account-subdomain].boss811.com/api/v2 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.boss811.com/api/v2/users.

NB! Always use HTTPS as the protocol.

Request headers

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

Content-Type: application/json
Authorization: Bearer {{your-api-key}}
Example: Authorization: Bearer d8e9a8d91442eba00afcb0ea427ba8aec3b830ab995a0bc8ca

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	API access is disabled for the Account or failed resource creation due to Account reaching a plan limit (e.g User limit)
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
422 Unprocessable Entity	Request was valid but failed because of validation errors (e.g the request tried to update a Ticket with invalid data)

Other things to keep in mind

When a parameter is required, it is marked as "REQUIRED FIELD". All other fields are optional.
Request parameters must be encoded in UTF-8.

Using the API

Retrieving User profile info (including API key)

Thing	Value
URL	/profile
Method	GET
Successful response	User

The request must set the following basic auth header:

Authorization: Basic [email:password encoded in Base64]

Example response:

{
  "id": 8,
  "email": "jackpot@example.com",
  "first_name": "Jack",
  "last_name": "Pot",
  "api_key": "ae93e8...c23bcf2",
  "created_at": "2015-06-25T11:50:09.067Z",
  "updated_at": "2015-06-25T11:50:09.067Z",
  "active": true,
  "time_zone": "America/New_York",
  "tracking_interval": 300,
  "permissions": {
    "ticket": ["index", "update", "close", "reopen"],
    "audit": ["access"],
    "broadcast": ["access"]
  ],
  "roles": [
    {
      "id": 1,
      "name": "Admin"
    },
    {
      "id": 3,
      "name": "Locators"
    }
  ]
}

Account

Retrieving information about the current Account

Thing	Value
URL	/account
Method	GET
Response	Account

Example response:

{
    "name": "BOSS811 - New York",
    "full_domain": "new-york.boss811.com",
    "max_attachment_size_in_bytes": 104857600,
    "allowed_attachment_file_extensions": [
        "png",
        "jpeg",
        "jpg",
        "pdf"
    ],
    "max_attachment_resolution": "large",
    "time_zone": "America/New_York",
    "logo": "https://s3.amazonaws.com/boss811/accounts/logos/003/500/701/medium/71747bd2.png",
}

Call Centers

Retrieving information about Account Call Centers

Thing	Value
URL	/call_centers
Method	GET
Response	List of Call Centers

Example response:

[
  {
    "id": 123,
    "name": "Georgia 811",
    "state": "Georgia",
    "enabled": true,
    "service_areas": [
      "FOR01",
      "FOR02",
      "FOR03"
    ],
    "facilities": ["Gas", "Water"],
    "response_codes": [
      {
        "code": "1A",
        "description": "Marked.",
        "ticket_types": null,
        "comment_required": false
      },
      {
        "code": "1B",
        "description": "Marked: High profile utility in conflict.",
        "ticket_types": null,
        "comment_required": false
      },
      {
        "code": "10A",
        "description": "Large Projects: Meeting Date/Time Accepted.",
        "ticket_types": ['Large Project'],
        "comment_required": true
      }
    ],
    "ticket_types": [
      {
        "name": "Normal",
        "color": "#4ac68e"
      },
      {
        "name": "Damage",
        "color": "#ffc870"
      },
      {
        "name": "Design",
        "color": "#23c6c8"
      },
    ]
  }
]

Teams

Retrieving information about Account Teams

Thing	Value
URL	/teams
Method	GET
Response	List of Teams

Example response:

[
  {
    "id": 1,
    "name": "Team A",
    "call_centers": [
      {
        "id": 458,
        "name": "SD811"
      }
    ]
  },
  {
    "id": 2,
    "name": "Team B",
    "call_centers": [
      {
        "id": 11,
        "name": "Georgia 811"
      }
    ]
  }
]

Time Entry Tasks

Retrieving information about Account Time Entry Tasks

Thing	Value
URL	/time_entry_tasks
Method	GET
Response	List of Time Entry Tasks

Tasks without a Call Center are common Tasks that can be used on any Time Entry. Tasks with a Call Center are meant to be applied only to a Time Entry whose Ticket is of the same Call Center.

Example response:

[
  {
    "id": 5,
    "name": "Locating",
    "call_center": null,
    "service_a
  },
  {
    "id": 3,
    "name": "Travel",
    "call_center": {
      "id": 123,
      "name": "Georgia 811"
    }
  }
]

Custom Fields

Retrieving information about Account Custom Fields

Thing	Value
URL	/custom_fields
Method	GET
Response	List of Custom Fields

Custom Fields without a Call Center are common fields that are fields for all Tickets. Custom Fields with a Call Center are meant to be used only on a Ticket of the same Call Center.

Example response:

[
  {
    "id": 1,
    "type_id": 7,
    "name": "Site visit",
    "required": false,
    "call_center": null,
    "position": 0
  },
  {
    "id": 9,
    "type_id": 8,
    "name": "Select something",
    "required": true,
    "call_center": {
      "id": 123,
      "name": "Georgia 811"
    },
    "position": 1,
    "options": [
      {
        "id": 1243,
        "name": "Option 1",
        "parent_id": null
      }
    ]
  }
]

Field types:

Single line string
Multi line text
URL
Integer
Float
Date
Boolean
Dropdown
Cascading dropdown
Multiselect dropdown
Cascading multiselect dropdown

Map Services

Retrieving Map Services list

Thing	Value
URL	/map_services
Method	GET
Response	Array of map services

Example response:

[
  {
    "id": 33,
    "name": "Example ArcGIS service",
    "service_type": "arcgis",
    "map_url": "http://example.com/map",
    "token_url": "http://example.com/map/arcgis/tokens/generateToken",
    "username": "james",
    "password": "password",
    "call_center": {
      "id": 124,
      "name": "Louisiana 811"
    }
  },
  {
    "id": 40,
    "name": "Example KML file service",
    "service_type": "kml_file",
    "map_url": "https://s3.amazonaws.com/bigBoss/MapService/23/cc9dd1fsdfsdfcb0adc4b2fb96fsdfsh6702f9c27ce5/jrmysyr7.kml",
    "call_center": {
      "id": 123,
      "name": "Georgia 811"
    }
  }
]

Users

Retrieving the User list

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

Example response:

[
  {
    "id": 11,
    "email": "jackpot@example.com",
    "first_name": "Jack",
    "last_name": "Pot",
    "active": true,
    "created_at": "2015-12-18T22:47:24.610Z",
    "updated_at": "2016-04-04T17:07:52.659Z",
    "roles": [
      {
        "id": 1,
        "name": "Locators"
      }
    ],
    "call_centers": [
      {
        "id": 39,
        "name": "Georgia 811"
      }
    ]
  }
]

Retrieving the possible assignees list for a Call Center

Thing	Value
URL	/users/possible_assignees[?call_center_id=:call_center_id]
Method	GET
Response	Array of possible assignees
Pagination	No
Search	No

Example response when providing a call_center_id:

[
  {
    "id": 11,
    "name": "Jack Pot"
  },
  {
    "id": 5,
    "name": "Al Dente"
  }
]

Example response when not providing a call_center_id:

[
  {
    "id": 11,
    "name": "Jack Pot",
    "call_centers": [
      {
        "id": 234,
        "name": "North Carolina 811"
      }
    ],
    "teams": []
  },
  {
    "id": 5,
    "name": "Al Dente",
    "call_centers": [
      {
        "id": 435,
        "name": "Georgia 811"
      }
    ],
    "teams": [
      {
        "id": 1,
        "name": "Team A"
      }
    ]
  }
]

User Locations

Creating a User Location

Thing	Value
URL	/user_locations
Method	POST
Response	201 Created or 422 Unprocessable Entity

Example parameters:

{
  "user_location": {
    "lat": "-84.1379025",
    "lat": "34.2071681"
  }
}

Example successful response is 201 Created.

Example unsuccessful response is 422 Unprocessable Entity.

Tickets

Retrieving Tickets list

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

Example response:

[
  {
    "id": 8224,
    "ticket_number": "06196-832-534",
    "ticket_type": "Normal",
    "ticket_action": "Update",
    "version_number": 1,
    "service_area": "EXMPL01",
    "additional_service_areas": ["EXMPL02", "ABC03", "DFG01"],
    "status": "assigned",
    "response_status": "pending",
    "work_type": "road widening and relocation",
    "work_address": "Mountain Hill Rd, Town, County, GA",
    "work_coordinates": {
      "type": "Point",
      "coordinates": [
        -79.46409442425468,
        37.76757527143578
      ]
    },
    "created_at": "2016-06-29T15:33:42.588Z",
    "updated_at": "2016-10-11T18:42:11.822Z",
    "closed_at": null,
    "response_due_at": "2016-07-02T06:59:59.000Z",
    "meet": false,
    "assignee": {
      "id": 432,
      "name": "Al Dente"
    },
    "call_center": {
      "id": 8493,
      "name": "Georgia 811"
    },
    "pin_color": "#EC4D08",
    "ticket_type_color": "#4ac68e",
    "due_group": "overdue"
  }
]

Retrieving one Ticket

Thing	Value
URL by Ticket ID	/tickets/:id
URL by Call Center and Ticket number	/tickets/by_center/:call_center_id/by_number/:ticket_number
Method	GET
Response	Ticket

Example response:

{
  "id": 8915,
  "ticket_number": "06191-285-085",
  "reference_ticket_number": "06191-281-082",
  "version_number": 0,
  "sequence_number": 84,
  "ticket_type": "Normal",
  "ticket_action": "NEW",
  "ticket_source": null,
  "service_area": "EXMPL01",
  "additional_service_areas": ["EXMPL02", "FOR02", "ATL03"],
  "status": "assigned",
  "created_at": "2016-06-29T15:29:36.947Z",
  "updated_at": "2016-10-11T18:42:16.202Z",
  "closed_at": null,
  "taken_at": "2016-06-29T15:26:47.000Z",
  "work_start_at": "2016-07-03T09:00:00.000Z",
  "response_due_at": "2016-07-02T06:59:59.000Z",
  "remarks": "Re-mark this remark pls",
  "response_status": "not_available",
  "due_group": "overdue",
  "excavator": {
    "type": "Contractor",
    "name": "SHOVEL INC",
    "address": "12 OAK RD, NORCROSS, GA 31235",
    "phone": "9382 23092 33",
    "contact": {
      "name": "JACK POT",
      "phone": "7911927565 | Alternate: 89419284",
      "email": "JACKPOT@EXAMPLE.COM"
    },
    "alt_contact": {
      "name": "Bill Ding",
      "phone": "4129 2142 1922"
    },
    "caller": {
      "name": "Corey Ander",
      "phone": "0981 209 323",
      "email": "coreyander@example.com"
    }
  },
  "work": {
    "type": "replacing damaged handholes",
    "address": "Street Rd, Town, County, GA",
    "nearby_street": "Kings Way",
    "subdivision": "Central Park",
    "done_for": "CITY OF NEW YORK",
    "duration": "3 Days",
    "driving_directions": null,
    "locate_instructions": "locate the left quadrant.",
    "explosives": false,
    "white_painted": false,
    "deeper_than_16_inches": null,
    "overhead": false,
    "tunneling_or_boring": true,
    "area": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -85.23813450364261,
            35.10312553767414
          ],
          [
            -85.23647418873756,
            35.09899153385927
          ],
          [
            -85.23295488325576,
            35.10088867290039
          ],
          [
            -85.23813450364261,
            35.10312553767414
          ]
        ]
      ]
    }
  },
  "one_call_format": "",
  "assignee": {
    "id": 42,
    "name": "Al Dente"
  },
  "custom_fields": [
    {
      "id": 132,
      "type_id": 7,
      "name": "Site visit",
      "value": true
    },
    {
      "id": 95,
      "type_id": 6,
      "name": "Some date",
      "value": null
    }
  ],
  "ticket_responses": [
    {
      "id": 34,
      "service_area": "EXMPL01",
      "facility": null,
      "code": "1A",
      "comment": "",
      "status": "pending",
      "created_at": "2016-10-11T18:42:16.202Z",
      "updated_at": "2016-10-11T18:42:16.202Z",
      "responded_at": null,
      "respondent": {
        "id": 12492,
        "name": "Jack Pot"
      }
    }
  ],
  "tags": [
    {
      "id": 2383,
      "name": "Damaged Sewer"
    }
  ],
  "attachments": [
    {
      "id": 2183,
      "key": "Ticket/8915/230480ad8ads-4452-bf82-309823abfe323/34923_923082.jpg",
      "name": "34923_923082.jpg",
      "description": "South side of sewer",
      "size": 1075725,
      "lat": 40.781438,
      "lng": -73.96215,
      "updated_at": "2016-07-11T22:22:47.758Z",
      "created_at": "2016-07-11T22:22:47.758Z",
      "public_url": "https://bucket.s3.amazonaws.com/Ticket/8915/230480ad8ads-4452-bf82-309823abfe323/34923_923082.jpg",
      "public_thumbnail_url": "https://bucket-resized.s3.amazonaws.com/Ticket/8915/230480ad8ads-4452-bf82-309823abfe323/34923_923082.jpg",
      "created_by": {
        "id": 2393,
        "name": "Jo King"
      }
    }
  ],
  "notes": [
    {
      "id": 30233,
      "text": "What a cool note this is! Or is it...?",
      "created_at": "2016-12-29T13:55:17.485Z",
      "updated_at": "2016-12-29T13:55:17.485Z",
      "user": {
        "id": 42,
        "name": "Al Dente"
      }
    }
  ],
  "time_entries": [
    {
      "id": 3942,
      "billable": true,
      "date": "2017-12-15",
      "duration": 120,
      "note": "Some text describing this entry",
      "created_at": "2017-12-29T13:55:17.485Z",
      "updated_at": "2017-12-29T14:21:16.139Z",
      "task": {
        "id": 83233,
        "name": "Marking"
      },
      "user": {
        "id": 94135,
        "name": "Lou Pole"
      }
    }
  ],
  "call_center": {
    "id": 8493,
    "name": "Georgia 811"
  },
  "lat": 48.992424,
  "lng": -82.49301288
}

Creating a Ticket

Thing	Value
URL	/tickets?call_center_id=:call_center_id
Method	POST
Response	Ticket ID or error list

Ticket data should be sent as request body. The accepted Ticket data formats are described below.

Call Centers and accepted Ticket formats:

Call Center	Accepted Ticket format
Colorado	XML
Georgia (via Web Service)	XML
Georgia (via e-mail)	XML
Indiana	XML
Kansas	XML
Kentucky	XML
Louisiana	XML
Maryland	XML
Northern California and Nevada (USA North)	XML
North Carolina	XML
South Carolina	XML
Texas	XML
Texas (Lone Star)	XML
Wyoming	TelDig

Example successful response:

{
  "id": 3095832
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "call_center_id": ["not found for Service Area \"SA05\""]
  }
}

Updating a Ticket

Thing	Value
URL by Ticket ID	/tickets/:id
URL by Call Center and Ticket number	/tickets/by_center/:call_center_id/by_number/:ticket_number
Method	PATCH
Response	Ticket or error list

Example parameters:

{
  "ticket": {
    "assignee_id": "1",
    "custom_fields": {
      "1": "1",
      "5": "7"
    },
    "tag_ids": ["4", "1"]
  }
}

Example successful response:

{
  "id": 8915,
  "ticket_number": "06191-285-085",
  "reference_ticket_number": null,
  "version_number": 0,
  "sequence_number": 84,
  "ticket_type": "Normal",
  "ticket_action": "NEW",
  "ticket_source": null,
  "service_area": "EXMPL01",
  "additional_service_areas": ["EXMPL02", "FOR02", "ATL03"],
  "status": "assigned",
  "created_at": "2016-06-29T15:29:36.947Z",
  "updated_at": "2016-10-11T18:42:16.202Z",
  "closed_at": null,
  "taken_at": "2016-06-29T15:26:47.000Z",
  "work_start_at": "2016-07-03T09:00:00.000Z",
  "response_due_at": "2016-07-02T06:59:59.000Z",
  "remarks": "Re-mark this remark pls",
  "response_status": "not_available",
  "excavator": {
    "type": "Contractor",
    "name": "SHOVEL INC",
    "address": "12 OAK RD, NORCROSS, GA 31235",
    "phone": "9382 23092 33",
    "contact": {
      "name": "JACK POT",
      "phone": "7911927565 | Alternate: 89419284",
      "email": "JACKPOT@EXAMPLE.COM"
    },
    "alt_contact": {
      "name": "Bill Ding",
      "phone": "4129 2142 1922"
    },
    "caller": {
      "name": "Corey Ander",
      "phone": "0981 209 323",
      "email": "coreyander@example.com"
    }
  },
  "work": {
    "type": "replacing damaged handholes",
    "address": "Street Rd, Town, County, GA",
    "nearby_street": "Kings Way",
    "subdivision": "Central Park",
    "done_for": "CITY OF NEW YORK",
    "duration": "3 Days",
    "driving_directions": null,
    "locate_instructions": "locate the left quadrant.",
    "explosives": false,
    "white_painted": false,
    "deeper_than_16_inches": null,
    "overhead": false,
    "tunneling_or_boring": true,
    "area": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -85.23813450364261,
            35.10312553767414
          ],
          [
            -85.23647418873756,
            35.09899153385927
          ],
          [
            -85.23295488325576,
            35.10088867290039
          ],
          [
            -85.23813450364261,
            35.10312553767414
          ]
        ]
      ]
    }
  },
  "assignee": {
    "id": 1,
    "name": "Al Dente"
  },
  "custom_fields": [
    {
      "id": 1,
      "type_id": 7,
      "name": "Site visit",
      "value": true
    },
    {
      "id": 5,
      "type_id": 6,
      "name": "Some date",
      "value": null
    }
  ],
  "ticket_responses": [
    {
      "id": 34,
      "service_area": "EXMPL01",
      "facility": "Water",
      "code": "1A",
      "comment": "",
      "status": "pending",
      "created_at": "2016-10-11T18:42:16.202Z",
      "updated_at": "2016-10-11T18:42:16.202Z",
      "responded_at": null,
      "respondent": {
        "id": 12492,
        "name": "Jack Pot"
      }
    }
  ],
  "tags": [
    {
      "id": 4,
      "name": "Damaged Sewer"
    },
    {
      "id": 1,
      "name": "Water"
    }
  ],
  "attachments": [],
  "notes": [],
  "time_entries": [],
  "call_center": {
    "id": 8493,
    "name": "Georgia 811"
  },
  "lat": 48.992424,
  "lng": -82.49301288,
  "watchers": [
    {
      "id": 4472,
      "name": "Marc Lou",
      "call_centers": [
        {
          "id": 8493,
          "name": "Georgia 811"
        }
      ]
    }
  ]
}

Example unsuccessful response with validation errors:

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

Updating a Ticket with Ticket Responses

Thing	Value
URL by Ticket ID	/tickets/:id
URL by Call Center and Ticket number	/tickets/by_center/:call_center_id/by_number/:ticket_number
Method	PATCH
Response	Ticket or error list

Example parameters:

{
  "ticket_responses": [{
    "service_area": "EXMPL01",
    "facility": "Water",
    "code": "1A",
    "comment": ""
  }]
}

Example successful response:

{
  "id": 8915,
  "ticket_number": "06191-285-085",
  "reference_ticket_number": null,
  "version_number": 0,
  "sequence_number": 84,
  "ticket_type": "Normal",
  "ticket_action": "NEW",
  "ticket_source": null,
  "service_area": "EXMPL01",
  "additional_service_areas": ["EXMPL02", "FOR02", "ATL03"],
  "status": "assigned",
  "created_at": "2016-06-29T15:29:36.947Z",
  "updated_at": "2016-10-11T18:42:16.202Z",
  "closed_at": null,
  "taken_at": "2016-06-29T15:26:47.000Z",
  "work_start_at": "2016-07-03T09:00:00.000Z",
  "response_due_at": "2016-07-02T06:59:59.000Z",
  "remarks": "Re-mark this remark pls",
  "response_status": "not_available",
  "excavator": {
    "type": "Contractor",
    "name": "SHOVEL INC",
    "address": "12 OAK RD, NORCROSS, GA 31235",
    "phone": "9382 23092 33",
    "contact": {
      "name": "JACK POT",
      "phone": "7911927565 | Alternate: 89419284",
      "email": "JACKPOT@EXAMPLE.COM"
    },
    "alt_contact": {
      "name": "Bill Ding",
      "phone": "4129 2142 1922"
    },
    "caller": {
      "name": "Corey Ander",
      "phone": "0981 209 323",
      "email": "coreyander@example.com"
    }
  },
  "work": {
    "type": "replacing damaged handholes",
    "address": "Street Rd, Town, County, GA",
    "nearby_street": "Kings Way",
    "subdivision": "Central Park",
    "done_for": "CITY OF NEW YORK",
    "duration": "3 Days",
    "driving_directions": null,
    "locate_instructions": "locate the left quadrant.",
    "explosives": false,
    "white_painted": false,
    "deeper_than_16_inches": null,
    "overhead": false,
    "tunneling_or_boring": true,
    "area": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -85.23813450364261,
            35.10312553767414
          ],
          [
            -85.23647418873756,
            35.09899153385927
          ],
          [
            -85.23295488325576,
            35.10088867290039
          ],
          [
            -85.23813450364261,
            35.10312553767414
          ]
        ]
      ]
    }
  },
  "assignee": {
    "id": 1,
    "name": "Al Dente"
  },
  "custom_fields": [
    {
      "id": 1,
      "type_id": 7,
      "name": "Site visit",
      "value": true
    },
    {
      "id": 5,
      "type_id": 6,
      "name": "Some date",
      "value": null
    }
  ],
  "ticket_responses": [
    {
      "id": 34,
      "service_area": "EXMPL01",
      "facility": "Water",
      "code": "1A",
      "comment": "",
      "status": "pending",
      "created_at": "2016-10-11T18:42:16.202Z",
      "updated_at": "2016-10-11T18:42:16.202Z",
      "responded_at": null,
      "respondent": {
        "id": 12492,
        "name": "Jack Pot"
      }
    }
  ],
  "tags": [
    {
      "id": 4,
      "name": "Damaged Sewer"
    },
    {
      "id": 1,
      "name": "Water"
    }
  ],
  "attachments": [],
  "notes": [],
  "time_entries": [],
  "call_center": {
    "id": 8493,
    "name": "Georgia 811"
  },
  "lat": 48.992424,
  "lng": -82.49301288
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "base": [
      "At least 1 Attachment is required"
    ]
  }
}

Append tags and custom fields to Ticket

Thing	Value
URL by Ticket ID	/tickets/:id
URL by Call Center and Ticket number	/tickets/by_center/:call_center_id/by_number/:ticket_number
Method	PATCH
Response	Ticket or error list

Example parameters:

{
  "ticket": {
    "assignee_id": "1",
    "add_tag_ids": ["1"],
    "add_custom_fields": {
      "5": "7"
    }
  }
}

Example successful response:

{
  "id": 8915,
  "ticket_number": "06191-285-085",
  "reference_ticket_number": null,
  "version_number": 0,
  "sequence_number": 84,
  "ticket_type": "Normal",
  "ticket_action": "NEW",
  "ticket_source": null,
  "service_area": "EXMPL01",
  "additional_service_areas": ["EXMPL02", "FOR02", "ATL03"],
  "status": "assigned",
  "created_at": "2016-06-29T15:29:36.947Z",
  "updated_at": "2016-10-11T18:42:16.202Z",
  "closed_at": null,
  "taken_at": "2016-06-29T15:26:47.000Z",
  "work_start_at": "2016-07-03T09:00:00.000Z",
  "response_due_at": "2016-07-02T06:59:59.000Z",
  "remarks": "Re-mark this remark pls",
  "response_status": "not_available",
  "excavator": {
    "type": "Contractor",
    "name": "SHOVEL INC",
    "address": "12 OAK RD, NORCROSS, GA 31235",
    "phone": "9382 23092 33",
    "contact": {
      "name": "JACK POT",
      "phone": "7911927565 | Alternate: 89419284",
      "email": "JACKPOT@EXAMPLE.COM"
    },
    "alt_contact": {
      "name": "Bill Ding",
      "phone": "4129 2142 1922"
    },
    "caller": {
      "name": "Corey Ander",
      "phone": "0981 209 323",
      "email": "coreyander@example.com"
    }
  },
  "work": {
    "type": "replacing damaged handholes",
    "address": "Street Rd, Town, County, GA",
    "nearby_street": "Kings Way",
    "subdivision": "Central Park",
    "done_for": "CITY OF NEW YORK",
    "duration": "3 Days",
    "driving_directions": null,
    "locate_instructions": "locate the left quadrant.",
    "explosives": false,
    "white_painted": false,
    "deeper_than_16_inches": null,
    "overhead": false,
    "tunneling_or_boring": true,
    "area": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -85.23813450364261,
            35.10312553767414
          ],
          [
            -85.23647418873756,
            35.09899153385927
          ],
          [
            -85.23295488325576,
            35.10088867290039
          ],
          [
            -85.23813450364261,
            35.10312553767414
          ]
        ]
      ]
    }
  },
  "assignee": {
    "id": 1,
    "name": "Al Dente"
  },
  "custom_fields": [
    {
      "id": 1,
      "type_id": 7,
      "name": "Site visit",
      "value": true
    },
    {
      "id": 5,
      "type_id": 6,
      "name": "Some date",
      "value": null
    }
  ],
  "ticket_responses": [
    {
      "id": 34,
      "service_area": "EXMPL01",
      "facility": "Water",
      "code": "1A",
      "comment": "",
      "status": "pending",
      "created_at": "2016-10-11T18:42:16.202Z",
      "updated_at": "2016-10-11T18:42:16.202Z",
      "responded_at": null,
      "respondent": {
        "id": 12492,
        "name": "Jack Pot"
      }
    }
  ],
  "tags": [
    {
      "id": 4,
      "name": "Damaged Sewer"
    },
    {
      "id": 1,
      "name": "Water"
    }
  ],
  "attachments": [],
  "notes": [],
  "time_entries": [],
  "call_center": {
    "id": 8493,
    "name": "Georgia 811"
  },
  "lat": 48.992424,
  "lng": -82.49301288
}

NOTE: Ticket has had Tag#4 and CustomField#1 before the request

Example unsuccessful response with validation errors:

{
  "errors": {
    "base": [
      "At least 1 Attachment is required"
    ]
  }
}

Closing a Ticket

Thing	Value
URL by Ticket ID	/tickets/:id/close
URL by Call Center and Ticket number	/tickets/by_center/:call_center_id/by_number/:ticket_number/close
Method	PATCH
Response	Ticket or error list

Example parameters (you can also omit these and call close without params):

{
  "ticket": {
    "assignee_id": "1",
    "custom_fields": {
      "1": "1",
      "5": "7"
    },
    "tag_ids": ["4", "1"]
  }
}

Example successful response:

{
  "id": 8915,
  "ticket_number": "06191-285-085",
  "reference_ticket_number": null,
  "version_number": 0,
  "sequence_number": 84,
  "ticket_type": "Normal",
  "ticket_action": "NEW",
  "ticket_source": null,
  "service_area": "EXMPL01",
  "additional_service_areas": ["EXMPL02", "FOR02", "ATL03"],
  "status": "closed",
  "created_at": "2016-06-29T15:29:36.947Z",
  "updated_at": "2016-10-11T18:42:16.202Z",
  "closed_at": "2016-10-11T18:42:17.498Z",
  "taken_at": "2016-06-29T15:26:47.000Z",
  "work_start_at": "2016-07-03T09:00:00.000Z",
  "response_due_at": "2016-07-02T06:59:59.000Z",
  "remarks": "Re-mark this remark pls",
  "response_status": "not_available",
  "excavator": {
    "type": "Contractor",
    "name": "SHOVEL INC",
    "address": "12 OAK RD, NORCROSS, GA 31235",
    "phone": "9382 23092 33",
    "contact": {
      "name": "JACK POT",
      "phone": "7911927565 | Alternate: 89419284",
      "email": "JACKPOT@EXAMPLE.COM"
    },
    "alt_contact": {
      "name": "Bill Ding",
      "phone": "4129 2142 1922"
    },
    "caller": {
      "name": "Corey Ander",
      "phone": "0981 209 323",
      "email": "coreyander@example.com"
    }
  },
  "work": {
    "type": "replacing damaged handholes",
    "address": "Street Rd, Town, County, GA",
    "nearby_street": "Kings Way",
    "subdivision": "Central Park",
    "done_for": "CITY OF NEW YORK",
    "duration": "3 Days",
    "driving_directions": null,
    "locate_instructions": "locate the left quadrant.",
    "explosives": false,
    "white_painted": false,
    "deeper_than_16_inches": null,
    "overhead": false,
    "tunneling_or_boring": true,
    "area": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -85.23813450364261,
            35.10312553767414
          ],
          [
            -85.23647418873756,
            35.09899153385927
          ],
          [
            -85.23295488325576,
            35.10088867290039
          ],
          [
            -85.23813450364261,
            35.10312553767414
          ]
        ]
      ]
    }
  },
  "assignee": {
    "id": 1,
    "name": "Al Dente"
  },
  "custom_fields": [
    {
      "id": 1,
      "type_id": 7,
      "name": "Site visit",
      "value": true
    },
    {
      "id": 5,
      "type_id": 6,
      "name": "Some date",
      "value": null
    }
  ],
  "ticket_responses": [
    {
      "id": 391,
      "service_area": "FOR01",
      "facility": "Water",
      "code": "1A",
      "comment": "Resolved",
      "status": "pending",
      "created_at": "2016-10-11T18:42:16.202Z",
      "updated_at": "2016-10-11T18:42:16.202Z",
      "responded_at": null,
      "respondent": {
        "id": 12492,
        "name": "Jack Pot"
      }
    }
  ],
  "tags": [
    {
      "id": 4,
      "name": "Damaged Sewer"
    },
    {
      "id": 1,
      "name": "Water"
    }
  ],
  "attachments": [],
  "notes": [],
  "time_entries": [],
  "call_center": {
    "id": 8493,
    "name": "Georgia 811"
  },
  "lat": 48.992424,
  "lng": -82.49301288
}

Example unsuccessful response with validation errors:

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

Closing a Ticket with TicketResponses

Thing	Value
URL by Ticket ID	/tickets/:id/close
URL by Call Center and Ticket number	/tickets/by_center/:call_center_id/by_number/:ticket_number/close
Method	PATCH
Response	Ticket or error list

Example parameters (you can also omit these and call close without params):

{
  "ticket_responses": [{
    "service_area": "FOR01",
    "facility": "Water",
    "code": "1A",
    "comment": "Resolved"
  }]
}

Example successful response:

{
  "id": 8915,
  "ticket_number": "06191-285-085",
  "reference_ticket_number": null,
  "version_number": 0,
  "sequence_number": 84,
  "ticket_type": "Normal",
  "ticket_action": "NEW",
  "ticket_source": null,
  "service_area": "EXMPL01",
  "additional_service_areas": ["EXMPL02", "FOR02", "ATL03"],
  "status": "closed",
  "created_at": "2016-06-29T15:29:36.947Z",
  "updated_at": "2016-10-11T18:42:16.202Z",
  "closed_at": "2016-10-11T18:42:17.498Z",
  "taken_at": "2016-06-29T15:26:47.000Z",
  "work_start_at": "2016-07-03T09:00:00.000Z",
  "response_due_at": "2016-07-02T06:59:59.000Z",
  "remarks": "Re-mark this remark pls",
  "response_status": "not_available",
  "excavator": {
    "type": "Contractor",
    "name": "SHOVEL INC",
    "address": "12 OAK RD, NORCROSS, GA 31235",
    "phone": "9382 23092 33",
    "contact": {
      "name": "JACK POT",
      "phone": "7911927565 | Alternate: 89419284",
      "email": "JACKPOT@EXAMPLE.COM"
    },
    "alt_contact": {
      "name": "Bill Ding",
      "phone": "4129 2142 1922"
    },
    "caller": {
      "name": "Corey Ander",
      "phone": "0981 209 323",
      "email": "coreyander@example.com"
    }
  },
  "work": {
    "type": "replacing damaged handholes",
    "address": "Street Rd, Town, County, GA",
    "nearby_street": "Kings Way",
    "subdivision": "Central Park",
    "done_for": "CITY OF NEW YORK",
    "duration": "3 Days",
    "driving_directions": null,
    "locate_instructions": "locate the left quadrant.",
    "explosives": false,
    "white_painted": false,
    "deeper_than_16_inches": null,
    "overhead": false,
    "tunneling_or_boring": true,
    "area": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -85.23813450364261,
            35.10312553767414
          ],
          [
            -85.23647418873756,
            35.09899153385927
          ],
          [
            -85.23295488325576,
            35.10088867290039
          ],
          [
            -85.23813450364261,
            35.10312553767414
          ]
        ]
      ]
    }
  },
  "assignee": {
    "id": 1,
    "name": "Al Dente"
  },
  "custom_fields": [
    {
      "id": 1,
      "type_id": 7,
      "name": "Site visit",
      "value": true
    },
    {
      "id": 5,
      "type_id": 6,
      "name": "Some date",
      "value": null
    }
  ],
  "ticket_responses": [
    {
      "id": 391,
      "service_area": "FOR01",
      "facility": "Water",
      "code": "1A",
      "comment": "Resolved",
      "status": "pending",
      "created_at": "2016-10-11T18:42:16.202Z",
      "updated_at": "2016-10-11T18:42:16.202Z",
      "responded_at": null,
      "respondent": {
        "id": 12492,
        "name": "Jack Pot"
      }
    }
  ],
  "tags": [
    {
      "id": 4,
      "name": "Damaged Sewer"
    },
    {
      "id": 1,
      "name": "Water"
    }
  ],
  "attachments": [],
  "notes": [],
  "time_entries": [],
  "call_center": {
    "id": 8493,
    "name": "Georgia 811"
  },
  "lat": 48.992424,
  "lng": -82.49301288
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "base": [
      "At least 1 Note is required"
    ]
  }
}

Reopen a Ticket

Thing	Value
URL by Ticket ID	/tickets/:id/reopen
URL by Call Center and Ticket number	/tickets/by_center/:call_center_id/by_number/:ticket_number/reopen
Method	PATCH
Response	Ticket or error list

Example successful response:

{
  "id": 8915,
  "ticket_number": "06191-285-085",
  "reference_ticket_number": null,
  "version_number": 0,
  "sequence_number": 84,
  "ticket_type": "Normal",
  "ticket_action": "NEW",
  "ticket_source": null,
  "service_area": "EXMPL01",
  "additional_service_areas": ["EXMPL02", "FOR02", "ATL03"],
  "status": "assigned",
  "created_at": "2016-06-29T15:29:36.947Z",
  "updated_at": "2016-10-11T18:42:16.202Z",
  "closed_at": null,
  "taken_at": "2016-06-29T15:26:47.000Z",
  "work_start_at": "2016-07-03T09:00:00.000Z",
  "response_due_at": "2016-07-02T06:59:59.000Z",
  "remarks": "Re-mark this remark pls",
  "response_status": "not_available",
  "excavator": {
    "type": "Contractor",
    "name": "SHOVEL INC",
    "address": "12 OAK RD, NORCROSS, GA 31235",
    "phone": "9382 23092 33",
    "contact": {
      "name": "JACK POT",
      "phone": "7911927565 | Alternate: 89419284",
      "email": "JACKPOT@EXAMPLE.COM"
    },
    "alt_contact": {
      "name": "Bill Ding",
      "phone": "4129 2142 1922"
    },
    "caller": {
      "name": "Corey Ander",
      "phone": "0981 209 323",
      "email": "coreyander@example.com"
    }
  },
  "work": {
    "type": "replacing damaged handholes",
    "address": "Street Rd, Town, County, GA",
    "nearby_street": "Kings Way",
    "subdivision": "Central Park",
    "done_for": "CITY OF NEW YORK",
    "duration": "3 Days",
    "driving_directions": null,
    "locate_instructions": "locate the left quadrant.",
    "explosives": false,
    "white_painted": false,
    "deeper_than_16_inches": null,
    "overhead": false,
    "tunneling_or_boring": true,
    "area": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -85.23813450364261,
            35.10312553767414
          ],
          [
            -85.23647418873756,
            35.09899153385927
          ],
          [
            -85.23295488325576,
            35.10088867290039
          ],
          [
            -85.23813450364261,
            35.10312553767414
          ]
        ]
      ]
    }
  },
  "assignee": {
    "id": 1,
    "name": "Al Dente"
  },
  "custom_fields": [
    {
      "id": 1,
      "type_id": 7,
      "name": "Site visit",
      "value": true
    },
    {
      "id": 5,
      "type_id": 6,
      "name": "Some date",
      "value": null
    }
  ],
  "ticket_responses": [
    {
      "id": 34,
      "service_area": "EXMPL01",
      "facility": "Water",
      "code": "1A",
      "comment": "",
      "status": "pending",
      "created_at": "2016-10-11T18:42:16.202Z",
      "updated_at": "2016-10-11T18:42:16.202Z",
      "responded_at": null,
      "respondent": {
        "id": 12492,
        "name": "Jack Pot"
      }
    }
  ],
  "tags": [
    {
      "id": 4,
      "name": "Damaged Sewer"
    },
    {
      "id": 1,
      "name": "Water"
    }
  ],
  "attachments": [],
  "notes": [],
  "time_entries": [],
  "call_center": {
    "id": 8493,
    "name": "Georgia 811"
  },
  "lat": 48.992424,
  "lng": -82.49301288
}

Resend failed Ticket Responses

Thing	Value
URL	/tickets/bulk_resend_ticket_responses
Method	PATCH
Response	200:OK or 404:Not Found

Example parameters:

{
  "ticket_ids": [656, 657]
}

Fetch possible watchers for a Ticket

Thing	Value
URL	/tickets/:id/possible_watchers
Method	GET
Response	200:OK or 404:Not Found

Example responses:

[
  {
    "id": 321,
    "name": "Marc Lou"
  }
]

Ticket Settings

Retrieving a Ticket settings

Thing	Value
URL	/ticket_settings
Method	GET
Response	Ticket Settings

Example response:

{
  "columns": [                       // An array of strings, each representing a possible column name for the ticket
    "ticket_number",
    "revision",
    "received_at"
  ],
  "default_order_by": {              // An object that specifies the default sorting order for tickets for the current user
    "column": "received_at",         // A string that must be one of the values listed in the 'columns' array
    "direction": "DESC"              // A string that indicates the sort direction, either 'ASC' for ascending order or 'DESC' for descending order
  }
}

Updating a Ticket Settings

Thing	Value
URL	/ticket_settings
Method	PATCH
Response	200:OK or 422:Unprocessable entity

Example parameters:

{
  "default_order_by": {
    "column": "ticket_number",
    direction: "ASC"
  }
}

Example of a successful response:

{
  "message": "User tickets settings updated"
}

Example of a failed response:

{
  "error": "Failed to update tickets settings"
}

Ticket Responses

Creating a Ticket Response

Thing	Value
URL by Ticket ID	/tickets/:id/ticket_responses
URL by Call Center and Ticket number	/tickets/by_center/:call_center_id/by_number/:ticket_number/ticket_responses
Method	POST
Response	201:Created or 422:Unprocessable entity

Example parameters:

{
  "ticket_response": {
    "service_area": "FOR01",             // REQUIRED
    "code": "1A",                        // REQUIRED
    "facility": "Water",                 // REQUIRED ONLY WHEN the call center requires it (currently South Carolina and Texas)
    "comment": "Resolved",               // REQUIRED ONLY WHEN used for Indiana call center 3C, 3F positive response codes 
    "attempted_contact_name": "Jack Pot" // REQUIRED ONLY WHEN used for Indiana call center 3C, 3F, 3G positive response codes 
    "additional_properties": {
      "description_of_marked_area": "Area description" // REQUIRED ONLY WHEN used for Indiana call center 3G positive response code 
    }
  }
}

Example response:

{
  "id": 39131,
  "service_area": "FOR01",
  "facility": "Water",
  "code": "1A",
  "comment": "Resolved",
  "status": "pending",
  "created_at": "2016-10-11T18:42:16.202Z",
  "updated_at": "2016-10-11T18:42:16.202Z",
  "responded_at": null,
  "respondent": {
    "id": 12492,
    "name": "Jack Pot"
  }
}

After successful creation of a Ticket Response, the response will also be sent to the Call Center when it's enabled in the settings.

Setting all Ticket Responses

Thing	Value
URL by Ticket ID	/tickets/:ticket_id/ticket_responses
URL by Call Center and Ticket number	/tickets/by_center/:call_center_id/by_number/:number/ticket_responses
Method	PUT
Response	200:OK or 422:Unprocessable entity

Example parameters:

{
  "ticket_responses": [
    {
      "service_area": "FOR01",     // REQUIRED
      "code": "1A",                // REQUIRED
      "facility": "Water",         // REQUIRED ONLY WHEN the call center requires it (currently South Carolina and Texas)
      "comment": "Resolved"
    },
    {
      "service_area": "FOR02",
      "code": "1B"
    }
  ]
}

Example response:

[
  {
    "id": 39131,
    "service_area": "FOR01",
    "facility": "Water",
    "code": "1A",
    "comment": "Resolved",
    "status": "pending",
    "created_at": "2016-10-11T18:42:16.202Z",
    "updated_at": "2016-10-11T18:42:16.202Z",
    "responded_at": null,
    "respondent": {
      "id": 12492,
      "name": "Jack Pot"
    }
  },
  {
    "id": 39132,
    "service_area": "FOR02",
    "facility": null,
    "code": "1B",
    "comment": "",
    "status": "pending",
    "created_at": "2016-10-11T18:42:16.202Z",
    "updated_at": "2016-10-11T18:42:16.202Z",
    "responded_at": null,
    "respondent": {
      "id": 12492,
      "name": "Jack Pot"
    }
  }
]

Example unsuccessful response with validation errors:

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

It will also send responses (when responses changed) to the Call Center when it's enabled in the settings.

Attachments

New Attachment request for a Ticket

Thing	Value
URL	/tickets/:ticket_id/attachments/new
Method	GET
Response	Attachment

Example successful response:

{
  "key": "tmp/Ticket/894218/68023f36-bbb3-44a7-8f4c-dc6d3a069cb3/file",
  "upload_url": "https://bucket.s3.amazonaws.com/tmp/Ticket/894218/68023f36-bbb3-44a7-8f4c-dc6d3a069cb3/file?X-Amz-Algorithm=...0da0b3cae2"
}

Creating an Attachment for a Ticket

Thing	Value
URL	/tickets/:ticket_id/attachments
Method	POST
Response	Attachment or error list

Example parameters:

{
  "attachment": {
    "name": "example.txt",
    "description": "Uploaded from mobile device",
    "lng": "-84.1379025",
    "lat": "34.2071681",
    "key": "tmp/Ticket/894218/68023f36-bbb3-44a7-8f4c-dc6d3a069cb3/file"    // REQUIRED
  }
}

Example successful response:

{
  "id": 1,
  "key": "Ticket/894218/68023f36-bbb3-44a7-8f4c-dc6d3a069cb3/file",
  "name": "example.txt",
  "description": "Uploaded from mobile device",
  "size": 243,
  "lng": "-84.1379025",
  "lat": "34.2071681",
  "updated_at": "2016-07-11T22:22:47.758Z",
  "created_at": "2016-07-11T22:22:47.758Z",
  "public_url": "https://bucket.s3.amazonaws.com/tests/example.txt",
  "public_thumbnail_url": nil,
  "created_by": {
    "id": 30203,
    "name": "Lou Pole"
  }
}

Example unsuccessful response with validation errors:

{
    "errors": {
        "key": ["doesn't exist"]
    }
}

Deleting an Attachment

Thing	Value
URL by Ticket ID	/tickets/:ticket_id/attachments/:id
Method	DELETE
Response	200:OK or 422:Unprocessable entity

Example response:

{
  "id": 1,
  "key": "Ticket/894218/68023f36-bbb3-44a7-8f4c-dc6d3a069cb3/file",
  "name": "example.txt",
  "description": "Uploaded from mobile device",
  "size": 243,
  "lng": "-84.1379025",
  "lat": "34.2071681",
  "updated_at": "2016-07-11T22:22:47.758Z",
  "created_at": "2016-07-11T22:22:47.758Z",
  "public_url": "https://bucket.s3.amazonaws.com/tests/example.txt",
  "public_thumbnail_url": nil,
  "created_by": {
    "id": 30203,
    "name": "Lou Pole"
  }
}

Notes

Creating a Note for a Ticket

Thing	Value
URL	/tickets/:ticket_id/notes
Method	POST
Response	Note or error list

Example parameters:

{
  "note": {
    "text": "A <b>new</b> Note!"          // REQUIRED
  }
}

Example successful response:

{
  "id": 712,
  "text": "A <b>new</b> Note!",
  "created_at": "2017-07-21T10:21:57.275Z",
  "updated_at": "2017-07-21T10:21:57.275Z",
  "user": {
    "id": 432,
    "name": "Al Dente"
  }
}

Example unsuccessful response with validation errors:

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

Watchers

Adding a watcher to a ticket

Thing	Value
URL by Ticket ID	/tickets/:ticket_id/watchers
Method	POST
Response	201:Created or 422:Unprocessable entity

Example parameters:

{
  "watcher": {
    "id": 33 // REQUIRED
  }
}

Example response:

{
  "id": 33,
  "name": "Lou Pole"
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "date": ["Could not add watcher, likely provided ID belongs to a different account"]
  }
}

Removing a watcher from a ticket

Thing	Value
URL	/tickets/:ticket_id/watchers/:id
Method	DELETE
Response	200:OK or 422:Unprocessable entity

Example response:

{
  "id": 33,
  "name": "Lou Pole"
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "date": ["Something has gone wrong. Please contact support for assistance"]
  }
}

Time Entries

Creating a Time Entry

Thing	Value
URL by Ticket ID	/tickets/:ticket_id/time_entries
Method	POST
Response	201:Created or 422:Unprocessable entity

Example parameters:

{
  "time_entry": {
    "user_id": 34534,            // REQUIRED
    "time_entry_task_id": 5224,
    "billable": false,           // REQUIRED
    "date": "2017-12-22",        // REQUIRED
    "duration": 120,             // REQUIRED (in minutes)
    "note": "Marked the place"
  },
  "service_areas": ["TEST01", "TEST02"]
}

Example response:

{
  "id": 409334,
  "billable": false,
  "date": "2017-12-22",
  "duration": 120,
  "service_area": null,
  "note": "Marked the place",
  "created_at": "2017-12-22T18:42:16.202Z",
  "updated_at": "2017-12-22T18:42:16.202Z",
  "task": {
    "id": 5224,
    "name": "Marking"
  },
  "user": {
    "id": 34534,
    "name": "Lou Pole"
  }
}

Example response (multiple service areas):

[
  {
    "id": 409335,
    "billable": false,
    "date": "2017-12-22",
    "duration": 120,
    "service_area": "TEST01",
    "note": "Marked the place",
    "created_at": "2017-12-22T18:42:16.202Z",
    "updated_at": "2017-12-22T18:42:16.202Z",
    "task": {
      "id": 5224,
      "name": "Marking"
    },
    "user": {
      "id": 34534,
      "name": "Lou Pole"
    }
  },
    {
    "id": 409336,
    "billable": false,
    "date": "2017-12-22",
    "duration": 120,
    "service_area": "TEST02",
    "note": "Marked the place",
    "created_at": "2017-12-22T18:42:16.202Z",
    "updated_at": "2017-12-22T18:42:16.202Z",
    "task": {
      "id": 5224,
      "name": "Marking"
    },
    "user": {
      "id": 34534,
      "name": "Lou Pole"
    }
  }
]

Example unsuccessful response with validation errors:

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

Updating a Time Entry

Thing	Value
URL by Ticket ID	/tickets/:ticket_id/time_entries/:id
Method	PATCH
Response	200:OK or 422:Unprocessable entity

Example parameters:

{
  "time_entry": {
    "user_id": 34535,
    "time_entry_task_id": 5222,
    "billable": true,
    "date": "2017-12-21",
    "duration": 95,
    "note": "Changed some attributes"
  }
}

Example response:

{
  "id": 409334,
  "billable": true,
  "date": "2017-12-21",
  "duration": 95,
  "note": "Changed some attributes",
  "created_at": "2017-12-22T18:42:16.202Z",
  "updated_at": "2017-12-22T18:45:52.981Z",
  "task": {
    "id": 5222,
    "name": "Driving to the location"
  },
  "user": {
    "id": 34535,
    "name": "Al Dente"
  }
}

Example unsuccessful response with validation errors:

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

Deleting a Time Entry

Thing	Value
URL by Ticket ID	/tickets/:ticket_id/time_entries/:id
Method	DELETE
Response	200:OK or 422:Unprocessable entity

Example response:

{
  "id": 409334,
  "billable": true,
  "date": "2017-12-21",
  "duration": 95,
  "note": "Changed some attributes",
  "created_at": "2017-12-22T18:42:16.202Z",
  "updated_at": "2017-12-22T18:45:52.981Z",
  "task": {
    "id": 5222,
    "name": "Driving to the location"
  },
  "user": {
    "id": 34535,
    "name": "Al Dente"
  }
}

Ticket Due At Revisions

Creating a Ticket Due At Revision

Thing	Value
URL by Ticket ID	/api/v2/tickets/:ticket_id/ticket_due_at_revisions
URL by Call Center and Ticket number	/api/v2/tickets/by_center/:call_center_id/by_number/:ticket_number/ticket_due_at_revisions
Method	POST
Response	201:Created or 422:Unprocessable entity

Example parameters:

{
  "rescheduled": {
    "new_due_at": "2021-09-08 12:00",  // REQUIRED
    "contact_name": "John Doe",
    "contact_phone": "+123456789",
    "reason": "Resolved",
    "notes": "Marked the place",
    "technician": "Al Dente",
    "leftamessage": "locate the left quadrant."
  }
}

Example response:

{
  "id": 409334,
  "previous_due_at": "2017-12-22T18:42:16.202Z",
  "new_due_at": "2017-12-23T18:42:16.202Z"
}

Saved Searches

Retrieving the Search list

Thing	Value
URL	/searches
Method	GET
Response	Array of Searches

Example response:

[
    {
        "id": 2843,
        "name": "Open revised Tickets",
        "my_search": false
    }
]

Applying a Search

Thing	Value
URL	/searches/:id
Method	GET
Successful response	Array of Tickets

Example response for a search:

[
  {
    "id": 8224,
    "ticket_number": "06196-832-534",
    "ticket_type": "Normal",
    "service_area": "EXMPL01",
    "status": "assigned",
    "work_type": "road widening and relocation",
    "work_address": "Mountain Hill Rd, Town, County, GA",
    "created_at": "2016-06-29T15:33:42.588Z",
    "updated_at": "2016-10-11T18:42:11.822Z",
    "closed_at": null,
    "response_due_at": "2016-07-02T06:59:59.000Z",
    "assignee": {
      "id": 432,
      "name": "Al Dente"
    },
    "call_center": {
      "id": 8493,
      "name": "Georgia 811"
    }
  }
]

Mobile Apps

Retrieving information about current Mobile App version

Thing	Value
URL	/mobile_app?version=:version&platform=:platform
Method	GET
Response	Latest mobile app version

Example response:

{
  "latest_version": "0.0.10",
  "update_required": true,
  "title": "BOSS811 mobile application v2.0.68 beta has been released.",
  "body": "Features/Improvements: upgraded node, ionic, angular, capacitor and all the plugins to the latest versions, enabled near me tickets filtering on tickets list and tickets map view"
}

Pagination

By default 15 items are returned by the index actions. 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/v2/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/v2/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 (Tickets, Users). 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/v2/users?q[last_name_eq]=Foley

You can also search using multiple filters:

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

Search by nearby

Thing	Value
URL	/tickets?q[lng_lat_near][]=:longitude&q[lng_lat_near][]=:latitude&q[lng_lat_near][]=:distance_in_miles
Method	GET
Successful response	Array of Tickets

Example response for a search:

[
  {
    "id": 8224,
    "ticket_number": "06196-832-534",
    "ticket_type": "Normal",
    "ticket_action": "Update",
    "version_number": 1,
    "service_area": "EXMPL01",
    "additional_service_areas": ["EXMPL02", "ABC03", "DFG01"],
    "status": "assigned",
    "response_status": "pending",
    "work_type": "road widening and relocation",
    "work_address": "Mountain Hill Rd, Town, County, GA",
    "work_coordinates": {
      "type": "Point",
      "coordinates": [
        -79.46409442425468,
        37.76757527143578
      ]
    },
    "created_at": "2016-06-29T15:33:42.588Z",
    "updated_at": "2016-10-11T18:42:11.822Z",
    "closed_at": null,
    "response_due_at": "2016-07-02T06:59:59.000Z",
    "meet": false,
    "assignee": {
      "id": 432,
      "name": "Al Dente"
    },
    "call_center": {
      "id": 8493,
      "name": "Georgia 811"
    },
    "pin_color": "#EC4D08",
    "ticket_type_color": "#4ac68e",
    "due_group": "overdue"
  }
]

API V2 Documentation

General information

API URL

Request headers

Response codes

Other things to keep in mind

Using the API

Retrieving User profile info (including API key)

Account

Retrieving information about the current Account

Call Centers

Retrieving information about Account Call Centers

Teams

Retrieving information about Account Teams

Tags

Retrieving information about Account Tags

Time Entry Tasks

Retrieving information about Account Time Entry Tasks

Custom Fields

Retrieving information about Account Custom Fields

Map Services

Retrieving Map Services list

Users

Retrieving the User list

Retrieving the possible assignees list for a Call Center

User Locations

Creating a User Location

Tickets

Retrieving Tickets list

Retrieving one Ticket

Creating a Ticket

Updating a Ticket

Updating a Ticket with Ticket Responses

Append tags and custom fields to Ticket

Closing a Ticket

Closing a Ticket with TicketResponses

Reopen a Ticket

Resend failed Ticket Responses

Fetch possible watchers for a Ticket

Ticket Settings

Retrieving a Ticket settings

Updating a Ticket Settings

Ticket Responses

Creating a Ticket Response

Setting all Ticket Responses

Attachments

New Attachment request for a Ticket

Creating an Attachment for a Ticket

Deleting an Attachment

Notes

Creating a Note for a Ticket

Watchers

Adding a watcher to a ticket

Removing a watcher from a ticket

Time Entries

Creating a Time Entry

Updating a Time Entry

Deleting a Time Entry

Ticket Due At Revisions

Creating a Ticket Due At Revision

Saved Searches

Retrieving the Search list

Applying a Search

Mobile Apps

Retrieving information about current Mobile App version

Pagination

Page

Per page

Search

Search by nearby