Skip to main content

Ticket Formats & Delivery Options

Released: 12/20/23

Effective: Varies - see dates below


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 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 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

2023.1.1d_DigAlertFormatDocs.zip

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.