Integrity API Documentation
This document is the documentation for Integrity integration.
General information
API URL
The API URL is https://[your-account-subdomain].boss811.com/api/integrations/integrity and all the request URLs must be appended to this URL. For example to get a Call Center list make a GET request to https://mycompany.boss811.com/api/integrations/integrity/call_centers.
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.
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']
}
]
}
]
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/by_center/:call_center_id/by_number/: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",
"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"
}
}
],
"call_center": {
"id": 8493,
"name": "Georgia 811"
},
"lat": 48.992424,
"lng": -82.49301288
}
Updating a Ticket
| Thing | Value |
|---|---|
| URL by Ticket ID | /tickets/by_center/:call_center_id/by_number/:number |
| Method | PATCH |
| Response | Ticket or error list |
Example parameters:
{
"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": "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"
}
}
],
"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/by_center/:call_center_id/by_number/:number/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"
}
}
],
"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/by_center/:call_center_id/by_number/: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"
}
}
],
"call_center": {
"id": 8493,
"name": "Georgia 811"
},
"lat": 48.992424,
"lng": -82.49301288
}
Ticket Responses
Adding and updating Ticket Responses
| Thing | Value |
|---|---|
| URL | /tickets/by_center/:call_center_id/by_number/:number/ticket_responses |
| Method | POST |
| Response | 200:OK 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"
}
}
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"
}
}
Example unsuccessful response with validation errors:
{
"errors": {
"code": ["can't be blank"]
}
}
This method will create or update a response depending on if a response for the Service Area-Facility pair already exists or not.
It will also send responses (when responses changed) to the Call Center when it's enabled in the settings.
When the Ticket has all the required responses set and all codes are considered "completed", the Ticket will be auto-closed.
Setting/replacing all Ticket Responses
| Thing | Value |
|---|---|
| URL by Ticket ID | /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.
When the Ticket has all the required responses set and all codes are considered "completed" (10, 20, 70, 90, 92, 94 and 98), the Ticket will be auto-closed.