Ticket Formats & Delivery Options
What are Delivery Methods?
Delivery options are how the member elect to receive the ticket. Most members receive their tickets by email. Below are options along with any associated costs.
Email
Web Hook
NOTICE
Due to spam issues that arise from sending DigAlert tickets to certain domains, mostly free email providers, we DO NOT allow tickets to be sent to any of these email domains. Below is a list of known email domains that can be issues and are not allowed. This is not a complete list and is subject to change as we learn about more. So far, gmail.com addresses seem to not be an issue at this time.
yahoo.com
msn.com
hotmail.com
outlook.com
aol.com
live.com
What are Ticket Formats?
Ticket Formats are the exact specification that a ticket is delivered to utility members. As a utility member you have the choice to choose the format that you would like to have delivered. Any changes to formats must be approved by the Board of Directors and members are given as much notice as possible of any and all changes to Ticket Formats before changes go into effect.
Plain text format (Email only)
Plain text with EPR link (Email only)
HTML (default for new members) (Email only)
JSON (Email, Web Hook)
XML with arrays for members and shape points (Email, Web hook)
XML with XSD and flat lists for members and shape points (Email, Web hook)
Web Hook Requirements
The member receiving the ticket must set up an API endpoint that will accept a request from DigAlert's servers with the "Content-Type: text/xml" allowed
The length of the URL for the API endpoint (not including the http:// or https://) must not exceed 1024 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 XML 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 XML, there must be a header of “Content-Type: text/xml”
Format change log
1/1/2023 - new mandatory format. This format will be live starting January 1st, 2023. Test tickets will be available for members no later than 11/1/2022.
Ticket type of DMGE (damage) will be added and used for tickets that are reporting a damage
Ticket type of EXPD (exposed) will be added and used for tickets that are reporting an exposed line
Ticket type of DMEX (damage/exposed) will be removed and no longer used
Ticket type of RTRN (return trip) will be added and used for any reason the excavator is requesting any or all members to respond to the job site for any reason other than requesting re-marks, no response, damage or exposed. This new ticket type will reset the legal notice requirement for the members to respond giving members time to respond back to the job site. For example, “gate is now unlocked”.
New field used to identify the type of excavator requesting the ticket called “Type” will be added. Please see Ticket Types, Headers & Explanations for complete list of possibilities.
New field called “Job Size” will be added and used to show how many square feet and square miles the job site contains
The Address, Street, Cross 1 and Cross 2 fields will be removed from the Location field and placed back into dedicated fields for each
New field called “Project ID” will be added for future use
New field called “Project Name” will be added for future use
New field called “Pavement Only” will be added and used to identify jobs that are doing pavement grinding only
New field called “Searchable tags” will be added and used to store system generated hashtags for faster searching, indexing and parsing of ticket information. Please see Ticket Types, Headers & Explanations for complete list of possibilities.
3/1/2019 - new mandatory format. This format will be live starting March 1st, 2019. Testing will be available for members on 1/1/2019
Complete re-format of entire output
Common format for all of California - DigAlert and USANorth811
11/1/2017 - new mandatory format to comply with the new GC 4216. This format will be the only format available after 11/1/17.
Added a new field named Work Order "Wrk Order:" to the ticket
Added a new priority of "EMER" or "9" for emergency tickets
Added a category field to the header
Added a new field named "1Year:" for continual excavation tickets
Added a new field named "Response Required:" to indicate if the member is required to respond to the excavator
Added a new field named "Legal Date:" representing the date the ticket must be responded to by members that are required to respond to the excavator
Added a new field named "Legal Time:" representing the time the ticket must be responded to by members that are required to respond to the excavator
Added a new field named "View map at:" which will have a link to DigAlert's system allowing the members to view the map that DigAlert sent
Changed the "FAX:" field to "SMS:" which will be used for cell phone numbers instead of fax numbers
Removed the field "Grids:"
Expanded the field "Caller GPS" to a text field that will allow multiple lat/long points for use with Electronic Whitelining
1/1/2016 - new fields were added under an optional format for members that choose to receive them
Added a new field named Work Order "Wrk Order:" to the ticket
Added a new priority of "EMER" or "9" for emergency tickets
Downloadable Format Documents & Samples
January 1st 2023 mandatory format change documents & plain text samples