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

Requirements

• X Dispatch 21.0 or newer.
• TLS 1.2
  • When calling the web services for CXT hosted 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

1. Navigate to URL: https://<domain>/CxtWebService/CXTWCF.svc/api-docs

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

3. If getting an authorization token, place token in the Authorization Token box at the top. 

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

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: /v1/Authentication/Drivers 

  Valid duration of an authentication token: 30 days  

• Internet User endpoint: /v1/Authentication/InetUser 

  Valid duration of an authentication token: 20 minutes

• Human Resources endpoint: /v1/Authentication/Worker  

  Valid duration of an authentication token: 30 days

• X Dispatch User endpoint: /v1/Authentication/XdUser 

  Valid duration of an authentication token: 60 minutes 

Token expiration is automatically extended with each call. 

Authenticate Driver Example

Including Tokens in Subsequent Requests

After generating a token, include it in subsequent requests as a value for the Authorization header, in the form 'Token 12345'.

Basic Authentication

Basic authentication credentials must be sent with every request, base64 encoded and the username must be prefixed with 1 or 4 values to distinguish user type:

• Driver prefix: DRIVER
• Internet User prefix: INET
• Human Resources prefix: WORKER
• X Dispatch User prefix: XDISPATCH

An example of an internet user with the username "cxtsupport" is "INET-cxtsupport".

Basic Auth Example

Examples

The following are examples to help you get started and is not an inclusive list. Use the endpoint URL examples to find documentation in the Swagger UI for details and testing.

Creating a New Order without known order type(s)

Creating a new order creates a new on demand order in X Dispatch and requires an internet user authorization token. Before creating an order you will need a list of order types if a static order type is not provided. Order types in X Dispatch define the timing and level of service for on demand orders. 

How to Retrieve An Order Type

To get a list of available order types, use the  /v1/Orders/RatesWithTimeWindows endpoint.

Endpoint URL: https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/index.html?url=/CxtWebService/CXTWCF.svc/v2/swagger.json#!/Ratings/CxtSoftware_MiddleTier_WebService_CXTWCF_GetBaseRateAndTimeWindowsV2 

Section: Ratings

Endpoint: /v2/Orders/RatesWithTimeWindows

Implementation Notes: Allowed requestors: [INet user, XDispatch user]

Once you have retrieved a list of order types you can use the /v1/Orders endpoint to create new on demand order. See How to Create an Order.

Creating a New Order with known order type(s)

Creating a new order creates a new on demand order in X Dispatch and requires an internet user authorization token. Use this endpoint if a static order type is provided. Order types in X Dispatch define the timing and level of service for on demand orders. 

How to Create an Order

You can use the /v1/Orders endpoint to create new on demand order in X Dispatch.

Endpoint URL: https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/index.html?url=/CxtWebService/CXTWCF.svc/v2/swagger.json#!/Orders/CxtSoftware_MiddleTier_WebService_CXTWCF_OnDemandOrder_CreateV2 

Section: Orders

Endpoint: /v2/Orders

Implementation Notes: Allowed requestors: [INet User]

Creating a New Route Stop

Creating a new route stop creates a new route stop in X Dispatch and requires an X Dispatch user authentication token.

How to Create a Route Stop

You can use the /v2/RouteStops endpoint to create new route stops in X Dispatch.

Endpoint URL: https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/index.html?url=/CxtWebService/CXTWCF.svc/v2/swagger.json#!/Route_Stops/CxtSoftware_MiddleTier_WebService_CXTWCF_PostRouteStopV2

Section: Route Stops

Endpoint: /v2/RouteStops

Implementation Notes: Allowed requestors: [XD User]

 Order Status

Internet and X Dispatch users can get order status data. Including, but not limited to, confirmation, pickup, delivery, and POD details.

For Internet Users

Endpoint URL: https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/index.html?url=/CxtWebService/CXTWCF.svc/v2/swagger.json#!/Orders/CxtSoftware_MiddleTier_WebService_CXTWCF_GetOnDemandOrderV2

Section: Orders

Endpoint: v2/Orders/{orderId}/{includeItemizedCharges}

Implementation Notes: Allowed requestors: [INet User]

For Dispatch Users

Endpoint URL: https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/index.html?url=/CxtWebService/CXTWCF.svc/v2/swagger.json#!/Orders/CxtSoftware_MiddleTier_WebService_CXTWCF_GetOnDemandOrderWithItemizedChargesV2

Section: Orders

Endpoint: /v2/Dispatch/Orders/{onDemandOrderId} 

Implementation Notes: Allowed requestors: [XD User]

 Track an Order

Get order tracking information based on matching tracking numbers, reference1 values, and unique identifiers of orders and route stops with paging. No authorization token is required, however, the information returned will be limited. For more detailed tracking information to be returned, you must have an internet user authorization token.

Endpoint URL: https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/index.html?url=/CxtWebService/CXTWCF.svc/v2/swagger.json#!/Shipments/CxtSoftware_MiddleTier_WebService_CXTWCF_GetShipmentSummariesV2 

Section: Shipments

Endpoint: /v2/Shipments/Summaries

Implementation Notes: Allowed requestors: [INet user, anonymous user]

 Add Signature to Work Order

Upload a signature image for a work order. 

Endpoint URL: https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/index.html?url=/CxtWebService/CXTWCF.svc/v2/swagger.json#!/Work_Orders/CxtSoftware_MiddleTier_WebService_CXTWCF_uploadSignatureV2 

Section: Work Orders

Endpoint: /v1/WorkOrders/Signatures

Implementation Notes: Allowed requestors: [Mobile User]

 Update Status/Change Timestamp

Mark a work order as picked up, completed, or add a POD.

Endpoint URL: https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/index.html?url=/CxtWebService/CXTWCF.svc//v2/swagger.json#!/Orders/CxtSoftware_MiddleTier_WebService_CXTWCF_PutOnDemandOrderStatusesV2 

Section: Orders

Endpoint:  v2/Dispatch/Orders/<onDemandOrderId>/Status

Implementation Notes: Allowed requestors: [XD User]

Troubleshooting

If you are experiencing connection issues and need CXT Software to help troubleshoot, add the following to the Web.config file, within the <configuration> tag and adjust the log name/location in the 'initializeData' attribute of the snippet below. Make the problematic call. Then include the resulting log as part of the information provided to CXT for troubleshooting.