Our web service allows for consistent integrations and services, making it easier for third parties to integrate with the CXT Software suite. It is accessible by both REST and SOAP and accepts both XML and JSON requests.

Integrations are a billable service, with a monthly recurring cost. Please contact Technical Support for more information.

Important Items to Note

Authentication is needed for most endpoints. You will need to send an authorization token or do a basic authentication with the call.
Dates entered should be in milliseconds in UTC for JSON requests (e.g. 1559651878000) and ISO-8601 standard for XML requests (e.g. 2019-06-04T07:36:53).
Dates returned are formatted according to X Dispatch global options settings and localized to where the order was picked up/delivered with the timezone noted.
When entering the workOrderId parameter it must be in the following format:
- route stop: r<stopID>
- on demand pickup: p<orderID>
- on demand delivery: d<orderID>

How will versioning be handled?

CXT Software will support the latest version, plus one previously published version. Response and Request objects, in addition to URLs, may have properties added with new releases. Business logic within the endpoints may change, and/or permission hardening may be applicable to existing endpoints with new releases

Requirements

X Dispatch 21.0 or newer.
TLS 1.2
- When calling the web services for CXT Cloud customers (designated by a domain in the format <CXTID>0.cxtsoftware.net), the calling system must connect with TLS 1.2
- TLS 1.2 is not supported on Windows 2008 R2 or below. The calling system can run Windows 7, 8.1 or 2012 or newer, all of which support TLS 1.2

Throttling API Calls

By default, API calls are throttled based on individual users and collectively to all users per the following default intervals:

5 per second
300 per minute
18,000 per hour
432,000 per day

If you need to adjust the default values please contact Technical Support.

Getting Started

Our web service is documented with Swagger UI and you can find a list of field definitions to help explain certain API fields. All customers can view this by going to https://<domain>/CxtWebService/CXTWCF.svc/api-docs/. For cloud customers, <domain> would be <CXTID>0.cxtsoftware.net, where <CXTID> is the 4 digit CXT Software account id. For example, if the CXT Software account id is 987, then the endpoint documentation is https://09870.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/

To view the property name, its type, and a brief description of its purpose, click on the 'Model' link for either the request or response object.

How to Use Swagger

Navigate to URL: https://<domain>/CxtWebService/CXTWCF.svc/api-docs
Authenticate by either getting an authentication token or using basic authentication. See Authenticate. Depending on the user type allowed to access the endpoint, you may need different tokens.
If getting an authorization token, place token in the Authorization Token box at the top.
Make endpoint requests in JSON or XML

Address Validation

If the "Enforce Address Validation" global option is checked inside X Dispatch, an order/stop will be successfully placed only if the address is validated; the order will fail if the address cannot be validated. If "Enforce Address Validation" is unchecked, the order placement will succeed regardless of validation.
Only the geocode (lat/lon) is updated when the addresses can be validated.

Attachments

Requirements for uploading a file (attachment creation/update):

When creating a new Attachment, do not send in an id.
When updating an Attachment, the id must be provided.

Attachment Permissions > Maintenance > Permissions.

Type	List/View	Add	Edit	Delete

Type	List/View	Add	Edit	Delete
Order	Must have permissions enabled for X Dispatch Functions > Orders	If the order is Invoiced Must have X Dispatch Functions > Orders > Edit Invoiced Orders > Edit Invoiced Attachments permission enabled If an order is Settled Must have X Dispatch Functions > Orders > Edit Settled Orders > Edit Settled Attachments permission enabled For uninvoiced and unsettled orders Must have X Dispatch Functions > Orders > Edit Orders permission enabled	Same as Add permission	Same as Add permission
Customer	Must have permissions enabled for X Dispatch Functions > Customers	Must have X Dispatch Functions > Customers > Edit Customers permission enabled	Same as Add permission	Must have X Dispatch Functions > Customers > Delete Customers permission enabled
Human Resource	Must have permission enabled for Maintenance Functions > Human Resources > View Contractor Maintenance Functions > Human Resources > View Employees Maintenance Functions > Human Resources > View HR Advanced Information	Must have Maintenance Functions' -> Human Resources > Edit Human Resources permissions enabled	Same as Add permission	Same as Add permission
Customer Contract	Must have X Route Functions > Contracts	Must have Contracts > Add Contracts permission enabled	Must have Contracts > Edit Contracts permission enabled	Same as Edit permission

Authenticate

Most endpoints require authentication from the following user types:

Driver
Internet User
Human Resource
X Dispatch User

You can see which user type(s) are required for an endpoint under "Implementation Notes". For example, "Allowed requestors: [Inet user]" requires an authenticated internet user and "Allowed requestors: [Mobile Users]" requires an authenticated driver user.

To authenticate, select sending an authorization token or doing a basic authentication with the call.

Token Based Authentication

Token based authentication uses one of the following endpoints to get the authorization token for the user:

Driver endpoint: /v2/Authentication/Drivers
Internet User endpoint: /v2/Authentication/InetUser
Human Resources endpoint: /v2/Authentication/Worker
X Dispatch User endpoint: /v2/Authentication/XdUser

Token expiration is automatically extended with each call.

Authenticate Driver Example

Better Code Block

Web Services/API Information (v2)