JSON Format Details
3/28/24 Update:
JSON sample was updated with the 2023 format. Was missing fields.
JSON format is a computer readable format that works great with inserting the ticket data into a database or ticket management system but is not at all human readable. JSON is available via REST Web hook or via email delivery.
The JSON format contains all the fields of the current plain text format plus all of the additional lat/long coordinates for the actual location of the job site. For a complete list of fields please make sure to see the current plain text documentation.
What is a Web Hook?
A web hook is an Application Programming Interface (API) that servers use to make a connection to a remote server and pass either commands or data. Our web hook will connect to your servers and deliver the ticket data when the ticket is issued.
What are the requirements to use the Web Hook?
The member receiving the ticket must set up an API endpoint that will accept a request from DigAlert's servers with the "Content-Type: application/json" allowed
The length of the URL for the API endpoint (not including the http:// or https://) must not exceed 255 characters
The API endpoint MUST provide a response within 3 seconds, otherwise the request will be treated as failed and will be retried again
In order for the DigAlert ticket, message, end of day, etc to be marked as received by the API endpoint (delivered), it MUST return a 200 level HTTP status code. All other codes or incomplete responses will be treated as failed and will be retried again.
The response should follow HTTP specification RFC 2616 and must be in the following format "HTTP/1.1 SSS description CR-LF" where SSS is the 3 digit status code and CF-LF is a line break consisting of the ASCII carriage return and line dees characters. There is no white space before the "CR-LF" but it is shown that way for readability only in this documentation.
After the status line any headers should be sent. If no headers are sent another CR-LF must be sent after the status line. The headers must end with two CR-LF pairs.
A response body is not required. However, if there is an error in the receiving API. it should send back an error message either as plain text or as a JSON object with a “message” property. Alternatively, a custom description can be used following the status code on the first response line.
For plain text, there should be a header of “Content-Type: text/plain” or no content-type header.
For JSON, there must be a header of “Content-Type: application/json”.
What are the differences between inline email and email attachments?
Inline emails displays the text (XML) within the body of the email directly and the email doesn't contain any attachments. Whereas with email attachments the body of the email is empty and the email will show an attachment.
NOTE
The JSON object (ticket data) won't necessarily always contain the same properties (ticket fields). Certain ones may be suppressed depending on ticket type or conditions the center has already stated previously.
Options
Members can request custom HTTP header and/or a custom JSON property to be sent with the web request. This information must be supplied to the center when requesting JSON Web Hook delivery.
WARNING
Some End of day audit, depending on your ticket load for that day could result in larger amount of data. Be sure to allow large requests in your API end point.
JSON Sample
The body of the request will contain a JSON object
NOTE
JSON samples below are shown in format 1 which includes the optional EPR link field
New Ticket
{
"delivery": {
"format_version": "1.05.01.8",
"center": "USAS",
"sys_id": "A",
"member": "MBRCD01",
"transmitted": "2022-08-09T10:58:13-0700",
"transmission_type": "TKT",
"sequence": 13
},
"ticket": {
"ticket": "A121231234",
"revision": "00A",
"created": "2022-08-02T10:53:53-0700",
"type": "NEW",
"priority": "NORM",
"category": "LREQ",
"lookup": "POLY",
"expires": "2022-08-30T23:59:59-0700",
"account": "CSR01",
"channel": "200",
"work_date": "2022-08-04T17:01:00-0700",
"response_due": "2022-08-04T17:01:00-0700",
"work_type": "REPAIR AND REPLACE SOMETHING",
"done_for": "JOES RESTAURANT",
"permit": "123456789ABC",
"work_order": "AB123456",
"project_id": "",
"project_name": "",
"explosives": true,
"vacuum": true,
"how_delineated": [
"WHITEPAINT"
],
"boring": false,
"excav_st_walk": true,
"response_required": true,
"one_year": false,
"pavement_only": false,
"searchable_tags": [],
"comments": "",
"caller": {
"name": "JIM SCHWILK",
"language": "ENGLISH",
"phone": "1231231234",
"phone_ext": "12345",
"cell": "1231231234",
"email": "JIM@DOMAIN.COM"
},
"excavator": {
"name": "ABC COMPANY",
"type": "CONT",
"address": "123 MAIN ST",
"city": "SOMEWHERE",
"state": "NY",
"zip": "12345"
},
"site_contact": {
"name": "JAMES WINGATE",
"phone": "1231231234",
"email": "JAMES@DOMAIN.COM",
"cell": "1231231234"
},
"excavation_area": {
"state": "CA",
"county": "LOS ANGELES",
"place": "CARSON",
"work_area_zip_codes": "90745",
"st_from_address": "12345",
"st_to_address": "12345",
"street": "MAIN ST",
"cross1": "1ST ST",
"cross2": "",
"location": "DOG IN YARD",
"job_size": {
"area_in_sqft": 137100,
"area_in_miles": 0.004918
},
"work_area": {
"type": "Feature",
"properties": null,
"geometry": {
"type": "Polygon",
"coordinates": [[
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456],
[-123.123456, 12.123456]
]]
}
}
},
"links": {
"map": "https://somelink.doamin.com/linkinformationhereandthiscouldbealongstring",
"epr": "https://somelink.domain.com/eprlinkwithinformationthatislong"
},
"members": [
"MBR001",
"MBR020",
"MBR039",
"LONGMBR058",
"MBR153",
"MBR172",
"MBR191",
"LONGMBR210",
"MBR324",
"MBR343",
"LONGMBR362",
"MBR077",
"MBR096",
"MBR115",
"LONGMBR134",
"MBR229",
"MBR248",
"MBR267",
"LONGMBR286"
]
}
}Broadcast Message
{
"delivery": {
"center": "USAS",
"member": "JWD01",
"format_version": "version J1",
"transmission_type": "FIL",
"transmitted": "2022-08-02T11:44:29-0700"
},
"message": "This is a test broadcast message. Please dig safe and make sure to contact DigAlert!"
}NOTE
End of day (EOD) in the web hook will contain ticket summaries shown below instead of only counts of ticket types
WARNING
Some End of day audit, depending on your ticket load for that day could result in larger amount of data. Be sure to allow large requests in your API end point.
End of Day (EOD)
{
"delivery": {
"center": "USAS",
"member": "MBRCODE01",
"format_version": "version J1",
"transmission_type": "SUM",
"transmitted": "2022-08-10T11:49:55-0700"
},
"audit": [
{
"ticket": "0000000000",
"revision": "000",
"delivered": "2022-08-09T08:28:18-0700",
"sequence": 1,
"type": "TEST",
"category": "TEST",
"priority": "NORM"
},
{
"ticket": "A123456789",
"revision": "00A",
"delivered": "2022-08-09T08:34:31-0700",
"sequence": 2,
"type": "NEW",
"category": "LREQ",
"priority": "NORM"
},
{
"ticket": "A234567891",
"revision": "00A",
"delivered": "2022-08-09T08:39:26-0700",
"sequence": 3,
"type": "NEW",
"category": "LREQ",
"priority": "EMER"
},
{
"ticket": "A345678912",
"revision": "00A",
"delivered": "2022-08-09T10:48:58-0700",
"sequence": 4,
"type": "NEW",
"category": "LREQ",
"priority": "NORM"
},
{
"ticket": "A456789123",
"revision": "01A",
"delivered": "2022-08-09T10:48:59-0700",
"sequence": 5,
"type": "CNCL",
"category": "LREQ",
"priority": "RUSH"
},
{
"ticket": "A567891234",
"revision": "00A",
"delivered": "2022-08-09T10:50:10-0700",
"sequence": 6,
"type": "NEW",
"category": "LREQ",
"priority": "SHRT"
},
{
"ticket": "A678912345",
"revision": "01A",
"delivered": "2022-08-09T10:50:11-0700",
"sequence": 7,
"type": "RSND",
"category": "LREQ",
"priority": "NORM"
}
],
"statistics": {
"priority": {
"norm": 4,
"shrt": 1,
"rush": 1,
"dsgn": 0,
"emer": 1
},
"type": {
"new": 5,
"amnd": 0,
"cncl": 1,
"dmex": 0,
"dsgn": 0,
"remk": 0,
"rnew": 0,
"nrsp": 0,
"rsnd": 1
},
"total_transmissions": 7
}
}