In this article, you’ll learn the recommended and validated approach for synchronizing ticket data using the Utilisphere SOAP-based integration endpoint. This feature is designed for integration developers and technical teams who need a reliable, incremental, and scalable way to keep external systems in sync with Utilisphere ticket data. By using a consistent SOAP endpoint and controlling behavior through a JSON payload, this approach supports efficient change detection, accurate detail retrieval, and predictable data synchronization outcomes.

Navigation Path:

All requests are made to the following SOAP endpoint and invoke the QueryData method:

https://www.irth.com/Irthnet/webservices/IRTHNetWOIntegration.asmx

https://cl.irth.com/Irthnet/webservices/IRTHNetWOIntegration.asmx

• Permissions & Access

  • An authorized AuthCode (provided by Irth) is required for all requests.
  • This integration is intended for technical users managing system integrations.

• Platform Considerations

  • The integration is SOAP-based and uses a single method: QueryData.
  • Request behavior is fully controlled by the JSON payload passed to the method.

• Key Behaviors & Limitations

  • ItemType is always set to "Ticket".
  • The same SOAP endpoint and method are used for both Summary and Details requests.
  • Tickets are filtered based on their most recent (LAST) action time, not all actions within a time window.
  • Tickets updated again after a queried window will no longer qualify for that window.

• Incremental Ticket Synchronization: Keep external systems up to date by efficiently identifying only tickets that have changed within a short time window, reducing unnecessary data transfers.

• Reliable Change Detection: Use Summary queries to accurately identify which tickets need to be refreshed, ensuring downstream systems reflect the latest ticket state.

• Scalable Historical Data Loads: Support one-time backfills or data warehouse population by querying warehouse-backed data for large historical datasets.

Follow these steps to set up and execute ticket synchronization:

Retrieve Updated Ticket IDs (Summary)

Send a QueryData request with:

• ItemType set to Ticket
• ResultType set to Summary
• A time-based filter using LastActionDateTime

This request returns a list of UtilisphereIDs for tickets whose most recent action occurred within the specified time window.

Example QuerData JSON (Summary):

 {

    "QueryData_V1": {

    "AuthCode": "<YOUR_AUTH_CODE>",

    "ItemType": "Ticket",

    "ResultType": "Summary",

    "ResultFormat": "<YOUR_RESULT_FORMAT>",

    "UseWarehouse": false,

    "Filters": [

      {

      "Field": "LastActionDateTime",

      "Operation: "TIME_BETWEEN",

      "Value": "YYY?MM?DD HH:MM-YYY/MM/DD HH:MM"

    }

For each UtilisphereID returned in the Summary response:

• Call the same QueryData method
• Set ResultType to Details
• Filter by the specific UtilisphereID

This returns the full ticket detail payload for each ticket.

Example QueryData JSON (Details):

    {

    "QueryData_V1": {

    "AuthCode": "<YOUR_AUTH_CODE>",

    "ItemType": "Ticket",

    "ResultType": "Details",

    "ResultFormat": "<YOUR_RESULT_FORMAT>",

    "UseWarehouse": false,

    "Filters": [

      {

      "Field": "UtilisphereID",

      "Operation: "EQUALS",

      "Value": "<UTILISPHERE_ID>"

    }

Manage Time Windows and Polling

• Use short, incremental time windows (recommended: ~5 minutes or less).
• Allow slight overlap between windows to account for processing delays.
• Design integrations to expect occasional reprocessing of tickets.

Time Window Semantics and Best Practices

• Querying Historical Windows
  • Fully supported, but only tickets whose most recent update falls within the window will be returned.
  • Earlier updates outside the window are ignored.
• Incremental Synchronization (Recommended)
  • End the window at or near the current time.
  • Use overlapping windows to ensure reliability and completeness.
• Large Gaps or Initial Loads
  • Tickets updated multiple times may appear only in windows that include their latest update.
  • Repeated or overlapping queries may be required.

Historical Data Loads Using the Warehouse

For large historical or warehouse-driven use cases:

• Set UseWarehouse to true
• Filter on CreateDate instead of LastActionDateTime
• Expect larger response sizes and longer processing times

NOTE: Warehouse queries are intended for bulk or historical access only and are not recommended for near-real-time synchronization.

Customers planning large historical loads should coordinate with Utilisphere to ensure optimal system performance.

Q: Why doesn’t a ticket appear in a historical time window even though it was updated during that time?
A: The Summary query evaluates only the ticket’s most recent action. If the ticket was updated again after the window, it no longer qualifies for that earlier window.

Q: Should I use large time windows to reduce API calls?
A: Smaller windows (around five minutes) are recommended. They produce smaller result sets and make retries and error recovery easier, especially in high-volume environments.

Q: When should I use the warehouse option?
A: Use UseWarehouse = true only for bulk historical loads or data warehousing scenarios—not for near-real-time integrations.