OTS Integration API Documentation
This document is the documentation for using your BOSS811 account via the OTS Integration.
General information
API URL
The API URL is https://[your-account-subdomain].boss811.com/api/integrations/ots and all the request URLs must be appended to this URL.
NB! Always use HTTPS as the protocol.
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 | 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.
Tickets
Retrieving one Ticket
| Thing | Value |
|---|---|
| URL | /tickets/by_center/:call_center_id/by_number/:ticket_number |
| URL by Call Center, Ticket number and SA | /tickets/by_center/:call_center_id/by_number/:ticket_number/by_sa/:service_area |
| 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",
"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": 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
}
Closing a Ticket
| Thing | Value |
|---|---|
| URL | /tickets/by_center/:call_center_id/by_number/:ticket_number/close |
| URL by Call Center, Ticket number and SA | /tickets/by_center/:call_center_id/by_number/:ticket_number/by_sa/:service_area/close |
| Method | PATCH |
| Response | Ticket or error list |
Example parameters (you can also omit these and call close without params):
{
"ticket": {
"custom_fields": {
"1": "1",
"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": "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"]
}
}
Reopen a Ticket
| Thing | Value |
|---|---|
| URL | /tickets/by_center/:call_center_id/by_number/:ticket_number/reopen |
| URL by Call Center, Ticket number and SA | /tickets/by_center/:call_center_id/by_number/:ticket_number/by_sa/:service_area/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
}
Ticket Notifications
High Profile notification
| Thing | Value |
|---|---|
| URL | /tickets/by_center/:call_center_id/by_number/:ticket_number/high_profile |
| URL by Call Center, Ticket number and SA | /tickets/by_center/:call_center_id/by_number/:ticket_number/by_sa/:service_area/high_profile |
| Method | PATCH |
| Response | 201:Created or 422:Unprocessable entity |
Example request body:
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<TicketResponse>
<CallCenter>IN811</CallCenter>
<TicketNum>1911065838</TicketNum>
<CDC>ID123</CDC>
<Response>Marked</Response>
<Complete>Done</Complete>
<HighProfile>1</HighProfile>
<Tech>Al Dente</Tech>
<Phone>9238523953</Phone>
<Notes></Notes>
<WorkTime>2019-10-07 02:32:03.000</WorkTime>
</TicketResponse>
</soapenv:Body>
</soapenv:Envelope>
Unlocatable notification
| Thing | Value |
|---|---|
| URL | /tickets/by_center/:call_center_id/by_number/:ticket_number/unlocatable |
| URL by Call Center, Ticket number and SA | /tickets/by_center/:call_center_id/by_number/:ticket_number/by_sa/:service_area/unlocatable |
| Method | PATCH |
| Response | 201:Created or 422:Unprocessable entity |
Example request body:
<soapenv:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<TicketResponse>
<CallCenter>OUPS</CallCenter>
<TicketNum>A123456789</TicketNum>
<CDC>ASD</CDC>
<Response>Unlocatable Verified</Response>
<Complete>1</Complete>
<HighProfile>0</HighProfile>
<Tech>Jack Pot</Tech>
<Phone>555555555</Phone>
<Notes></Notes>
<WorkTime>2019-10-16 16:12:07.383</WorkTime>
</TicketResponse>
</soapenv:Body>
</soapenv:Envelope>
Rescheduled notification
| Thing | Value |
|---|---|
| URL | /tickets/by_center/:call_center_id/by_number/:ticket_number/rescheduled |
| URL by Call Center, Ticket number and SA | /tickets/by_center/:call_center_id/by_number/:ticket_number/by_sa/:service_area/rescheduled |
| Method | PATCH |
| Response | 201:Created or 422:Unprocessable entity |
Example request body:
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<Rescheduling>
<NewDueDate>2019-11-15 11:00:00.000</NewDueDate>
<Tech>John Toe</Tech>
<TechPhone>4045551234</TechPhone>
<RescheduledAt>2019-12-08 12:35:01.000</RescheduledAt>
<Notes>Talked to Roger and he recommended rescheduling</Notes>
</Rescheduling>
</soapenv:Body>
</soapenv:Envelope>
Ticket Responses
Creating a Ticket Response
| Thing | Value |
|---|---|
| URL | /tickets/by_center/:call_center_id/by_number/:ticket_number/ticket_responses |
| URL by Call Center, Ticket number and SA | /tickets/by_center/:call_center_id/by_number/:ticket_number/by_sa/:service_area/ticket_responses |
| Method | POST |
| Response | 201:Created or 422:Unprocessable entity |
Example parameters:
{
"ticket_response": {
"service_area": "FOR01", // REQUIRED (also known as Member Code)
"code": "1A", // REQUIRED (also known as status)
"facility": "Water", // REQUIRED ONLY WHEN the call center requires it, otherwise keep it blank
"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.
Notes
Creating a Note for a Ticket
| Thing | Value |
|---|---|
| URL | /tickets/by_center/:call_center_id/by_number/:ticket_number/notes |
| URL by Call Center, Ticket number and SA | /tickets/by_center/:call_center_id/by_number/:ticket_number/by_sa/:service_area/notes |
| Method | POST |
| Response | Note or error list |
Example parameters:
{
"note": {
"text": "A new Note!" // REQUIRED
}
}
Example successful response:
{
"id": 712,
"text": "A new Note!",
"created_at": "2017-07-21T10:21:57.275Z",
"updated_at": "2017-07-21T10:21:57.275Z",
"user": null
}
Example unsuccessful response with validation errors:
{
"errors": {
"text": ["can't be blank"]
}
}