GENERAL

DigTix provides a RESTful web service endpoint for issuing positive response for tickets as their status changes. The service is based on submitting an HTTPS request using the POST verb and a set of named parameter values. The DigTix positive response service will authenticate the request, validate and process the input parameters, and provide a synchronous response with the result of the request.

ENDPOINT

The DigTix API endpoint for issuing positive response is:

https://<subdomain>.digtix.com/api/positiveresponse/respond

Where <subdomain> is determined by the company operating DigTix. Requests to the service require a specific set of parameters to be considered a valid request. Optional parameters may be provided at the responder’s discretion. These required and optional paramters are listed in the “Request Parameters” section below.

Before the positive response parameters are processed, the request must be authenticated via secure username and password digest. If an incorrect password is provided ten (10) consecutive times, the specified account will be locked. This is to prevent brute force password guessing. A locked account must be unlocked by a DigTix administrator to continue issuing positive response. If authentication fails for either reason, the response will indicate it via the proper response code, listed in the “Response Format” section below.

REQUEST PARAMETERS

The DigTix web service endpoint accepts the input fields listed below via the HTTPS request body, formatted as URL encoded form data i.e. HTTP request header “Content-Type: application/x-www-form-urlencoded”.

The endpoint accepts the following input fields:

• username: required, 30 characters or less.
  • The username should be supplied as the same username used to login to the DigTix web application and/or DigTix Augmented Reality app.

• password: required, 30 characters or less.
  • The password should be supplied as the same password used to login to the DigTix web application and/or DigTix Augmented Reality app.
• state: required, 2 characters.
  • The state code from which the request was received.
• ticketID: required, 30 characters or less.
  • The ID of the ticket as determined by the call center. In the case of tickets originating from DigTix, the DigTix “Ticket ID”.
• revision: required, 10 characters or less.
  • The revision of the ticket as determined by the call center. In the case of tickets originating from DigTix, the DigTix “Ticket ID Suffix”.
• memberCode: required, 30 characters or less.
  • The member code as determined by the call center. In the case of tickets originating from DigTix, the DigTix “contract code” or “CDC”.
• responseStatus: required, 100 characters or less.
  • The response status to apply to the locate request, as specified by the ticketID, revision, and memberCode. The list of statuses available for responding is determined and maintained by your DigTix operator.
• user: optional, 30 characters or less.
  • The first and last name of the user which is submitted the response.
• date: optional, formatted as yyyy-mm-dd H:i:s.
  • The date and time that the responseStatus was applied to the specified locate in UTC. If omitted, defaults to the date and time the request was processed.
• notes: conditionally required, 1024 characters or less.
  • Notes to apply to the locate request, as specified by the ticketID, revision, and memberCode.
  • This field may be required depending on the responseStatus being applied. Such requirements are defined by the organization operating DigTix.
• startDate: conditionally required, formatted as yyyy-mm-dd H:i:s.
  • The date and time that the work on this locate request began in UTC.
  • This field may be required depending on the responseStatus being applied. Such requirements are defined by the organization operating DigTix.
  • If the startDate field is required, the endDate field will also be required. 
  • The startDate must be prior to the endDate.
• endDate: conditionally required, formatted as yyyy-mm-dd H:i:s.
  • The date and time that the work on this locate request was completed in UTC.
  • This field may be required depending on the responseStatus being applied. Such requirements are defined by the organization operating DigTix.
  • If the endDate field is required, the startDate field will also be required. 
  • The endDate must be after the startDate.
• footage: conditionally required, positive integer.
  • The amount of footage marked for the locate request.
  • This field may be required depending on the responseStatus being applied. Such requirements are defined by the organization operating DigTix.

RESPONSE FORMAT

Once the request has been processed by the DigTix API, a response will be returned in JSON format. The JSON object will contain three properties, detailed below.

• success: boolean.
  • Whether or not the positive response was successfully applied.
• data: integer. A non-zero value indicates response failure:
  • -1 = unknown error
  • 0 = success
  • 1 = invalid request
  • 2 = authentication failure
  • 3 = user locked out due to ten consecutive authentication failures
  • 4 = response permission not granted to specified user
  • 5 = ticket not found
  • 6 = response status not found
  • 7 = ticket is already completed
  • 8 = operator qualification has expired for the specified user
  • 9 = ticket is not assigned to the responding user
  • 10 = requirements not met
    • See the "message" output field for more information.
• message: string.
  • An informational message. If no additional information needs to be communicated, this will be an empty string.

EXAMPLE

cURL Request:

curl -k  -L -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'username=myusername&password=mypassword&ticketID=1234567890&revision=001&memberCode=MYCDC&responseStatus=Electric Marked, Gas Cleared&notes=These are some optional notes&user=Jim Bob McGee&date=2021-06-02 13:24:56' 'https://dev.digtix.com/api/positiveresponse/respond'

DigTix Response (positive response successful): 

{"success":true,"message":"","data":0}