Northern Lights Integration API Documentation
This document is the documentation for using your BOSS811 account via the Northern Lights Integration.
General information
API URL
The API URL is https://[your-account-subdomain].boss811.com/api/integrations/northern_lights 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 by Call Center and Ticket number | /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 by Call Center and Ticket number | /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": {
"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"]
}
}
Reopen a Ticket
| Thing | Value |
|---|---|
| URL by Call Center and Ticket number | /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 Responses
Creating a Ticket Response
| Thing | Value |
|---|---|
| URL by Call Center and Ticket number | /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
"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"
}
}
After successful creation of a Ticket Response, the response will also be sent to the Call Center when it's enabled in the settings.