USIC API Documentation
This document is the documentation for USIC integration.
General information
API URL
The API URL is https://[your-account-subdomain].boss811.com/api/integrations/usic and all the request URLs must be appended to this URL. For example to get a Ticket list make a GET request to https://mycompany.boss811.com/api/integrations/usic/tickets.
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.
Using the API
Workaround for retrieving the API key
| Thing | Value |
|---|---|
| URL | /profile |
| Method | GET |
| Successful response | API key |
The request must set the following basic auth header where username is "apikey" and password is the API key itself:
Authorization: Basic [username:password encoded in Base64]
Example response:
{
"api_key": "ae93e8...c23bcf2",
}
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
},
{
"code": "1B",
"description": "Marked: High profile utility in conflict.",
"ticket_types": null
},
{
"code": "10A",
"description": "Large Projects: Meeting Date/Time Accepted.",
"ticket_types": ['Large Project']
}
]
}
]
Tags
Retrieving information about Account Tags
| Thing | Value |
|---|---|
| URL | /tags |
| Method | GET |
| Response | List of Tags |
Tags without a Call Center are common Tags that can be used on any Ticket. Tags with a Call Center are meant to be applied only to a Ticket of the same Call Center.
Example response:
[
{
"id": 5,
"name": "Site visit",
"call_center": null
},
{
"id": 3,
"name": "Water",
"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"
}
]
}
]
Field types:
- Single line string
- Multi line text
- URL
- Integer
- Float
- Date
- Boolean
- Dropdown
- Cascading dropdown
- Multiselect dropdown
- Cascading multiselect dropdown
Tickets
Retrieving one Ticket
| Thing | Value |
|---|---|
| URL by Ticket ID | /tickets/:id |
| 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"
}
],
"call_center": {
"id": 8493,
"name": "Georgia 811"
},
"lat": 48.992424,
"lng": -82.49301288
}
Updating a Ticket
| Thing | Value |
|---|---|
| URL by Ticket ID | /tickets/:id |
| Method | PATCH |
| Response | Ticket or error list |
Example parameters:
{
"ticket": {
"custom_fields": {
"1": "1",
"5": "7"
},
"tag_ids": ["34", "838"]
}
}
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": 123,
"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": 2383,
"name": "Damaged Sewer"
}
],
"call_center": {
"id": 8493,
"name": "Georgia 811"
},
"lat": 48.992424,
"lng": -82.49301288
}
Example unsuccessful response with validation errors:
{
"errors": {
"custom_fields[5]": ["is invalid"]
}
}
Closing a Ticket
| Thing | Value |
|---|---|
| URL by Ticket ID | /tickets/:id/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"
},
"tag_ids": ["473", "942"]
}
}
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": 2383,
"name": "Damaged Sewer"
}
],
"call_center": {
"id": 8493,
"name": "Georgia 811"
},
"lat": 48.992424,
"lng": -82.49301288
}
Example unsuccessful response with validation errors:
{
"errors": {
"custom_fields[5]": ["is invalid"]
}
}
Reopen a Ticket
| Thing | Value |
|---|---|
| URL by Ticket ID | /tickets/:id/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"
}
}
],
"call_center": {
"id": 8493,
"name": "Georgia 811"
},
"lat": 48.992424,
"lng": -82.49301288
}
Ticket Responses
Creating a Ticket Response
| Thing | Value |
|---|---|
| URL by Ticket ID | /tickets/:id/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"
}
}
Ticket Responses with a code of "$NO_RESPONSE" will be discarded and are not created.
After successful creation of a Ticket Response, the response will also be sent to the Call Center when it's enabled in the settings.
Updating a Ticket Response
| Thing | Value |
|---|---|
| URL by Ticket ID | /tickets/:ticket_id/ticket_responses/:id |
| Method | PATCH |
| Response | 200:OK or 422:Unprocessable entity |
Example parameters:
{
"ticket_response": {
"code": "1A",
"comment": "Resolved... again"
}
}
Example response:
{
"id": 39131,
"service_area": "FOR01",
"facility": "Water",
"code": "1A",
"comment": "Resolved... again",
"status": "success",
"created_at": "2016-10-11T18:42:16.202Z",
"updated_at": "2016-10-11T18:42:16.202Z",
"responded_at": "2016-10-11T18:43:38.983Z",
"respondent": {
"id": 12492,
"name": "Jack Pot"
}
}
After successful update of a Ticket Response, the response will also be sent to the Call Center if the response code changed and when it's enabled in the settings.
Deleting a Ticket Response
| Thing | Value |
|---|---|
| URL by Ticket ID | /tickets/:ticket_id/ticket_responses/:id |
| Method | DELETE |
| Response | 200:OK or 422:Unprocessable entity |
Example response:
{
"id": 39131,
"service_area": "FOR01",
"facility": "Water",
"code": "1A",
"comment": "Resolved",
"status": "success",
"created_at": "2016-10-11T18:42:16.202Z",
"updated_at": "2016-10-11T18:42:16.202Z",
"responded_at": "2016-10-11T18:43:38.983Z",
"respondent": {
"id": 12492,
"name": "Jack Pot"
}
}
After successful deletion of a Ticket Response, no information will be sent to the Call Center.
Replacing all Ticket Responses
| Thing | Value |
|---|---|
| URL by Ticket ID | /tickets/:ticket_id/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"]
}
}
Ticket Responses with a code of "$NO_RESPONSE" will be discarded/ignored.
It will also send responses (when responses changed) to the Call Center when it's enabled in the settings.
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": null
}
Example unsuccessful response with validation errors:
{
"errors": {
"text": ["can't be blank"]
}
}