Currently Available
Delivery Method(s): Web Hook, Inline Email, Email attachment
Updated: 8/23/2022
Version: 22.8.23a
Effective: August 1st 2022
XML 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. XML is available via REST Web hook or via email delivery.
The XML 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.
NOTE
We recommend members use JSON for web hooks unless they are currently using XML already.
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: text/xml" allowed
- The length of the URL for the API endpoint (not including the http:// or https://) must not exceed 60 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”
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.
XML Sample
New ticket
<?xml version="1.0"?>
<NewDataSet>
<delivery>
<format_version>1.05.01.8</format_version>
<center>USASA</center>
<recipient>MBRCD01</recipient>
<transmission_type>TKT</transmission_type>
<transmitted>2022-08-09T11:01:27-07:00</transmitted>
<seq_num>20</seq_num>
<ticket>A121231234</ticket>
<revision>00A</revision>
</delivery>
<tickets>
<ticket>A121231234</ticket>
<revision>00A</revision>
<created>2022-08-02T10:53:53-07:00</created>
<account>CSR01</account>
<channel>200</channel>
<work_date>2022-08-04T17:01:00-07:00</work_date>
<response_required></response_required>
<response_due>2022-08-04T17:01:00-07:00</response_due>
<replace_by_date>2022-08-30T23:59:59-07:00</replace_by_date>
<expires>2022-08-30T23:59:59-07:00</expires>
<one_year>N</one_year>
<priority>NORM</priority>
<type>NEW</type>
<category>LREQ</category>
<lookup>POLY</lookup>
<state>CA</state>
<county>LOS ANGELES</county>
<place>CARSON</place>
<work_area_zip_codes>90745</work_area_zip_codes>
<st_from_address>12345</st_from_address>
<st_to_address>12345</st_to_address>
<street>MAIN ST</street>
<cross1>1ST ST</cross1>
<polygon>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
<coordinate>
<latitude>12.123456</latitude>
<longitude>-123.123456</longitude>
</coordinate>
</polygon>
<how_delineated>WHITEPAINT</how_delineated>
<excav_st_walk>Y</excav_st_walk>
<work_type>REPAIR AND REPLACE SOMETHING</work_type>
<boring>N</boring>
<explosives>Y</explosives>
<vacuum>Y</vacuum>
<permit>123456789ABC</permit>
<work_order>AB123456</work_order>
<done_for>JOES RESTAURANT</done_for>
<name>ABC COMPANY</name>
<address1>123 MAIN ST</address1>
<city>SOMEWHERE</city>
<cstate>NY</cstate>
<zip>12345</zip>
<phone>1231231234</phone>
<phone_ext>12345</phone_ext>
<caller>JIM SCHWILK</caller>
<caller_language>ENGLISH</caller_language>
<cell>1231231234</cell>
<email>JIM@DOMAIN.COM</email>
<contact>JAMES WINGATE</contact>
<contact_phone>1231231234</contact_phone>
<contact_cell>1231231234</contact_cell>
<contact_email>JAMES@DOMAIN.COM</contact_email>
<location xml:space="preserve" >DOG IN YARD</location>
<comments xml:space="preserve" ></comments>
<memberlist>
<member>MBR001</member>
<member>MBR020</member>
<member>MBR039</member>
<member>LONGMBR058</member>
<member>MBR153</member>
<member>MBR172</member>
<member>MBR191</member>
<member>LONGMBR210</member>
<member>MBR324</member>
<member>MBR343</member>
<member>LONGMBR362</member>
<member>MBR077</member>
<member>MBR096</member>
<member>MBR115</member>
<member>LONGMBR134</member>
<member>MBR229</member>
<member>MBR248</member>
<member>MBR267</member>
<member>LONGMBR286</member>
<member>WBMWD</member>
</memberlist>
<map_url>https://somelink.doamin.com/linkinformationhereandthiscouldbealongstring</map_url>
<response_url>https://somelink.domain.com/eprlinkwithinformationthatislong</response_url>
<printable_text xml:space="preserve" >
MBRCD01 00020Y USAS 08/09/22 11:01:27 A121231234-00A NEW NORM POLY LREQ
Ticket: A121231234 Rev: 00A Created: 08/02/22 10:53 User: CSR01 Chan: 200
Work Start: 08/04/22 17:01 Legal Start: 08/04/22 17:01 Expires: 08/30/22 23:59 Response required: Y Priority: 2
Excavator Information
Company: ABC COMPANY
Co Addr: 123 MAIN ST
City : SOMEWHERE State: NY Zip: 12345
Created By: JIM SCHWILK Language: ENGLISH
Office Phone: 123-123-1234 x12345 SMS/Cell: 123-123-1234 Office Email: JIM@DOMAIN.COM
Site Contact: JAMES WINGATE
Site Phone: 123-123-1234 Site SMS/Cell: 123-123-1234
Site Email: JAMES@DOMAIN.COM
Excavation Area
State: CA County: LOS ANGELES Place: CARSON
Zip: 90745
Location: Address/Street: 12345 MAIN ST
: X/ST1: 1ST ST
:
: DOG IN YARD
Delineated Method: WHITEPAINT
Work Type: REPAIR AND REPLACE SOMETHING
Work For : JOES RESTAURANT
Permit: 123456789ABC Job/Work order: AB123456
1 Year: N Boring: N Street/Sidewalk: Y Vacuum: Y Explosives: Y
Lat/Long
Center Generated (NAD83): 12.123456/-118.280453 33.844393/-118.279476
: 12.123456/-123.123456 12.123456/-123.123456 Excavator Provided:
Map link:
https://somelink.doamin.com/linkinformationhereandthiscouldbealongstring
Post a response to this ticket at:
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 WBMWD
(c) Copyright 2018 Underground Service Alert of Southern California.
All rights reserved.
</printable_text>
</tickets>
</NewDataSet>
NOTE
Broadcast messages deliver as plain text for XML format users.
End of Day (EOD)
<?xml version="1.0"?>
<NewDataSet>
<delivery>
<format_version>1.04.01.9</format_version>
<center>USASa</center>
<recipient>MBRCODE</recipient>
<transmission_type>SUM</transmission_type>
<transmitted>2022-08-02T16:03:08</transmitted>
</delivery>
<audit id="1">
<member>MBRCODE</member>
<seq_num>1</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T05:29:08</delivered>
</audit>
<audit id="2">
<member>MBRCODE</member>
<seq_num>2</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T05:53:47</delivered>
</audit>
<audit id="3">
<member>MBRCODE</member>
<seq_num>3</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T05:55:06</delivered>
</audit>
<audit id="4">
<member>MBRCODE</member>
<seq_num>4</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T05:56:26</delivered>
</audit>
<audit id="5">
<member>MBRCODE</member>
<seq_num>5</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:05:33</delivered>
</audit>
<audit id="6">
<member>MBRCODE</member>
<seq_num>6</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:06:06</delivered>
</audit>
<audit id="7">
<member>MBRCODE</member>
<seq_num>7</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:13:07</delivered>
</audit>
<audit id="8">
<member>MBRCODE</member>
<seq_num>8</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:27:52</delivered>
</audit>
<audit id="9">
<member>MBRCODE</member>
<seq_num>9</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:28:38</delivered>
</audit>
<audit id="10">
<member>MBRCODE</member>
<seq_num>10</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:29:46</delivered>
</audit>
<audit id="11">
<member>MBRCODE</member>
<seq_num>11</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:29:57</delivered>
</audit>
<audit id="12">
<member>MBRCODE</member>
<seq_num>12</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:32:13</delivered>
</audit>
<audit id="13">
<member>MBRCODE</member>
<seq_num>13</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:32:25</delivered>
</audit>
<audit id="14">
<member>MBRCODE</member>
<seq_num>14</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:34:07</delivered>
</audit>
<audit id="15">
<member>MBRCODE</member>
<seq_num>15</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:35:38</delivered>
</audit>
<audit id="16">
<member>MBRCODE</member>
<seq_num>16</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:37:21</delivered>
</audit>
<audit id="17">
<member>MBRCODE</member>
<seq_num>17</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:53:38</delivered>
</audit>
<audit id="18">
<member>MBRCODE</member>
<seq_num>18</seq_num>
<ticket>A123456789</ticket>
<revision>00A</revision>
<delivered>2022-08-01T06:54:36</delivered>
</audit>
<audit id="19">
<member>MBRCODE</member>
<seq_num>19</seq_num>
<ticket>A123456789</ticket>
<revision>02A</revision>
<delivered>2022-08-01T06:55:43</delivered>
</audit>
<audit id="20">
<member>MBRCODE</member>
<seq_num>20</seq_num>
<ticket>A123456789</ticket>
<revision>01A</revision>
<delivered>2022-08-01T07:00:41</delivered>
</audit>
<printable_text xml:space="preserve" >
MBRCODE *SUM*A USAS 08/02/22 16:03:08
*****************************************************************************
THIS IS YOUR DAILY AUDIT FOR 08/01/22. IF THERE ARE ANY DISCREPANCIES PLEASE
CALL 951-808-8100 AFTER 7AM AND PRESS # THEN 1 ONCE
THE MESSAGE STARTS. THANK YOU AND GOOD NIGHT.
*****************************************************************************
00001 A123456789-00A 05:29 EN 00002 A123456789-00A 05:53 SN
00003 A123456789-00A 05:55 N 00004 A123456789-00A 05:56 N
00005 A123456789-00A 06:05 EN 00006 A123456789-00A 06:06 N
00007 A123456789-00A 06:13 N 00008 A123456789-00A 06:27 N
00009 A123456789-00A 06:28 SN 00010 A123456789-00A 06:29 N
00011 A123456789-00A 06:29 N 00012 A123456789-00A 06:32 N
00013 A123456789-00A 06:32 EN 00014 A123456789-00A 06:34 EN
00015 A123456789-00A 06:35 EN 00016 A123456789-00A 06:37 EN
00017 A123456789-00A 06:53 N 00018 A123456789-00A 06:54 SN
00019 A123456789-02A 06:55 W 00020 A123456789-01A 07:00 A
------------------------
( ) NORMAL - 00014
(S) SHORT - 00002
(H) RUSH - 00003
(E) EMERGENCY - 00001
TOTAL - 00020
------------------------
(N) NEW - 00018
(A) AMENDMENT - 00001
(C) CANCEL - 00000
(X) DAMAGE/EXPOSE- 00000
(D) DESIGN - 00000
(K) RE-MARK - 00000
(W) RENEWAL - 00001
(P) NO RESPONSE - 00000
(*) RESENT - 00000
------------------------
</printable_text>
</NewDataSet>
