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.
Integrations are a billable service, with a monthly recurring cost. Please contact Technical Support for more information. |
How will versioning be handled?CXT Software will support the latest version, plus one previous 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 |
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.
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.
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.
Requirements for uploading a file (attachment creation/update):
Type | List/View | Add | Edit | Delete |
---|---|---|---|---|
Order | Must have permissions enabled for X Dispatch Functions > Orders | If the order is Invoiced
If an order is Settled
For uninvoiced and unsettled orders
| 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 |
Most endpoints require authentication from the following user types:
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 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.
curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{ \"driverId\": 123, \"password\": \"password\", }" "https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/v1/Authentication/Drivers" |
After generating a token, include it in subsequent requests as a value for the Authorization header, in the form 'Token 12345'.
curl -X GET --header "Accept: application/json" --header "Authorization: Token b1661ab49e5d42139b99a4a0ee741f0a" "https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/v1/Orders/9876" |
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:
An example of an internet user with the username "cxtsupport" is "INET-cxtsupport".
System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12 | (SecurityProtocolType)3072; //TLS1.2 for for Windows 2012+, and 3072 is for Windows 2008 R2; Both can be left in place here without problem string url = "url" var request = System.Net.WebRequest.Create(url); request.Method = HttpMethod.Get.ToString(); string username = "username"; string password = "password"; string encoded = System.Convert.ToBase64String(System.Text.Encoding.ASCII.GetBytes(username + ":" + password)); request.Headers.Add("Authorization", "Basic " + encoded); ((System.Net.HttpWebRequest)request).Accept = "application/json"; return request; |
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 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.
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] The following permissions need to be enabled in X Dispatch on the internet user record in the Options tab, Show Rates to see the initialBaseRate and Show Deliver By Time to see the deliveryTime. To see the initialBaseRate the Global Options in X Dispatch also needs to have Total Charges enabled in the Internet Options tab.
Parameter | Description | Parameter Type | Data Type |
---|---|---|---|
interval | The object containing the necessary properties to get a timewindow and baserate | body | JSON/XML |
includeInvalid | Flag to include invalid order types. This can be useful for debugging. | query | boolean |
Once you have retrieved a list of order types you can use the /v2/Orders endpoint to create new on demand order. See How to Create an Order.
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.
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]
Parameter | Description | Parameter Type | Data Type |
---|---|---|---|
orderRequest | The on demand order to be created. | body | JSON/XML |
Creating a new route stop creates a new route stop in X Dispatch and requires an X Dispatch user authentication token.
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]
Parameter | Description | Parameter Type | Data Type |
---|---|---|---|
request | The data for the new route stop to be created | body | JSON/XML |
creditLimitBypas | Boolean indicating whether or not to create the route stop if the customer credit limit is exceeded | query | boolean |
Internet and X Dispatch users can get order status data. Including, but not limited to, confirmation, pickup, delivery, and POD details.
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]
Parameter | Description | Parameter Type | Data Type |
---|---|---|---|
orderId | The ID of the order to retrieve. | path | string |
includeItemizedCharges | Boolean indicating whether or not to include itemized charges for order. | path | string |
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]
Parameter | Description | Parameter Type | Data Type |
---|---|---|---|
onDemandOrderId | The ID of the on demand order to be retrieved. | path | string |
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]
Parameter | Description | Parameter Type | Data Type |
---|---|---|---|
searchCriteria | String containing comma-separated search criteria (i.e. Tracking Numbers, Locations, Addresses, Cities, States, Postal codes) - ignored for DateOnly search | query | string |
trackingType | Specify what fields the trackingNumberList represents (e.g. Tracking(Number, Barcode or Reference), Location, Address, City, State, Postal, or DateOnly) | query | string |
includePartialMatch | Specify 'true' if partial matches should be included in the search results (default is 'false') | query | boolean |
beginDate | Optionally specify a begin date to limit the search results | query | string |
endDate | Optionally specify an end date to limit the search results | query | string |
numRecentOrders | Set number of recent orders to view for the current user (Note: if this is used, no other search criteria will apply) | query | integer |
pageNum | The offset for the records to return (Default value is 0) | query | integer |
pageSize | The number of records to return (Default and Maximum value is 1000) | query | integer |
Upload a signature image for a work order.
"Q1hUIFNvZnR3YXJl" is "CXT Software" encoded as a base64 encoded string. |
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]
Parameter | Description | Parameter Type | Data Type |
---|---|---|---|
workOrderSignature | The signature to be persisted. | body | JSON/XML |
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]
Parameter | Description | Parameter Type | Data Type |
---|---|---|---|
onDemandOrderId | The ID of the on demand order to be updated | path | string |
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.
<system.diagnostics> <trace autoflush="true" /> <sources> <source name="System.Net" maxdatasize="1024"> <listeners> <add name="MyTraceFile"/> <add name="MyConsole"/> <add name="MyText"/> </listeners> </source> </sources> <sharedListeners> <add name="MyTraceFile" type="System.Diagnostics.TextWriterTraceListener" initializeData="System.Net.trace.log" /> <add name="MyConsole" type="System.Diagnostics.ConsoleTraceListener" /> <add name="MyText" type="System.Diagnostics.TextWriterTraceListener" initializeData="C:\Temp\RequestTrace.log"></add> </sharedListeners> <switches> <add name="System.Net" value="Verbose" /> </switches> </system.diagnostics> |