National Courier Delivery

1-800 Courier JSON Endpoints

The endpoints listed here are specified with an example base URL. Each 1-800 Courier customer has a designated base URL that will be provided when the system is initially enabled for API processing.

Post URL:
http://post.1800courier.e-courier.com/1800courier/software/xml/ecJsonPost.asmx/Login

This endpoint generates a UserGUID access token from a username and password. This can be used to generate a new UserGUID if a previous token has expired. UserGUID access tokens are refreshed each time they are used, but if they are not used for over 20 days, then they may expire. In some cases a UserGUID may be provided directly to trading partners. If this is the case, then use of the Login endpoint may not be required. Instead, the RefreshGUID endpoint may be used to ensure an access token does not expire.

Example Post:
{
“website”: “1800courier”,
“username”: “dev800user”,
“password”: “dev800pw”
}

Example Response:
{
“status”: “0”,
“UserGUID”: “{3CE5DA83-77CD-4402-A8E5-012EA8B3D5B7}”
}

Post URL:
http://post.1800courier.e-courier.com/1800courier/software/xml/ecJsonPost.asmx/SaveOrder

This endpoint allows trading partners to create orders or update orders in the 1-800 Courier system. Please review the Order object model below to determine which fields are required and which fields are available. Once an order has been created, it can then be retrieved via the GetOrder endpoint, or updated by calling the SaveOrder endpoint again.

Example Post:
{
“Order”: {
   “CustomerCode”: “Alpha”,
   “Service”: “Route”,
   “Auth”: “1234779”,
   “Pieces”: {
     “Piece”: {
     “Sequence”: “1”,
     “Reference”: “test1234barcode”,
     “Pieces”: “1”
     }
},
“Stops”: {
   “Stop”: {
     “Sequence”: “1”,
     “StopType”: “P”,
     “ScheduledDateTime”: “11/13/2019 6:00:00 AM”,
     “Name”: “James Madison”,
     “Address”: “2251 Orange Blossom Trail”,
     “City”: “Orlando”,
     “State”: “FL”,
     “Zip”: “32804”,
     “Country”: “USA”,
     “Phone”: “3015551212”,
     “ScheduledDateTimeTZ”: “EST”,
     “OrderStopPieces”: {
          “OrderStopPiece”: {
               “PieceAction”: “P”,
               “Sequence”: “1”
     }
   }
},
“Stop”: {
     “Sequence”: “2”,
     “StopType”: “D”,
     “ScheduledDateTime”: “11/13/2019 5:00:00 PM”,
     “Name”: “Bryan Moore”,
     “Address”: “2253 Orange Blossom Trail”,
     “City”: “Orlando”,
     “State”: “FL”,
     “Zip”: “32804”,
     “Country”: “USA”,
     “Phone”: “3015551212”,
     “ScheduledDateTimeTZ”: “EST”,
     “OrderStopPieces”: {
          “OrderStopPiece”: {
               “PieceAction”: “D”,
               “Sequence”: “1”
     }
    }
   }
  }
}

Example Response:
{
“status”: “0”,
“UserGUID”: “JSON Post Recieved”
}

Post URL:
http://post.1800courier.e-courier.com/1800courier/software/xml/ecJsonPost.asmx/GetOrder

The GetOrder endpoint allows a trading party to get an entire order JSON object. This object will include all of the data pertaining to that order as described below in the Order object description. This data can be parsed to evaluated events and milestones on the order and determine the status of each stop and piece. Additionally, signature information will be returned as base64 encoded objects.

Example Post:
{
“OrderNumber”: “5648172”
}

Example Response:
{
{
“Order”: {
“UserGUID”: “{00000000-0000-0000-0000-000000000000}”,
“OrderID”: “5648172”,
“SiteID”: “1”,
“SiteCode”: “SiteCodeOne”,
“OrderNumber”: “5648172”,
“OrderStatus”: “N”,
“CustomerID”: “689”,
“CreateDate”: “12/1/2017 3:48:00 PM”,
}

The order response is truncated for readability.

Post URL:
http://post.1800courier.e-courier.com/1800courier/software/xml/ecJsonPost.asmx/RefreshGUID

This endpoint refreshes a UserGUID access token. A UserGUID will expire after 20 days if it is not used. If you are calling 1-800 Courier endpoints more frequently than once every 20 days, then the UserGUID will never need to be refeshed. Once refreshed, a UserGUID will remain active again for another 20 days. Alternatively, a new UserGUID can be generated using the Login endpoint with the assigned username and password. The UserGUID to refresh is read from the HTTP host header “UserGUID” and the actual post body is ignored.

Example Post:
{
“UserGUID”: “011114A4-5391-46E0-B576-9835485F5731”
}

Example Response:
{
“status”: “0”,
"UserGUID": "{011114A4-5391-46E0-B576-9835485F5731}"
}

Post URL:
http://post.1800courier.e-courier.com/1800courier/software/xml/ecJsonPost.asmx/QuoteOrder

This endpoint allows trading partners to query an 1-800 Courier system for pricing an availability. The body of this post is identical to the SaveOrder submission, but instead of actually creating the order, a quote is returned.

Example Post:
{
  “Order”: {
    “CustomerCode”: “Alpha”,
    “Service”: “Route”,
    “Auth”: “1234779”,
    “Pieces”: {
      “Piece”: {
       “Sequence”: “1”,
       “Reference”: “test1234barcode”,
       “Pieces”: “1”
  }
},
“Stops”: {
   “Stop”: {
    “Sequence”: “1”,
    “StopType”: “P”,
    “ScheduledDateTime”: “11/13/2019 6:00:00 AM”,
    “Name”: “James Madison”,
    “Address”: “2251 Orange Blossom Trail”,
    “City”: “Orlando”,
    “State”: “FL”,
    “Zip”: “32804”,
    “Country”: “USA”,
    “Phone”: “3015551212”,
    “ScheduledDateTimeTZ”: “EST”,
    “OrderStopPieces”: {
        “OrderStopPiece”: {
         “PieceAction”: “P”,
         “Sequence”: “1”
   }
    }
},
“Stop”: {
    “Sequence”: “2”,
    “StopType”: “D”,
    “ScheduledDateTime”: “11/13/2019 5:00:00 PM”,
    “Name”: “Bryan Moore”,
    “Address”: “2253 Orange Blossom Trail”,
    “City”: “Orlando”,
    “State”: “FL”,
    “Zip”: “32804”,
    “Country”: “USA”,
    “Phone”: “3015551212”,
    “ScheduledDateTimeTZ”: “EST”,
    “OrderStopPieces”: {
      “OrderStopPiece”: {
        “PieceAction”: “D”,
        “Sequence”: “1”
     }
    }
   }
  }
}
}

Example Response:
{
“Order”: {
    “CustomerID”: “1900”,
    “Service”: “Route”,
    “Caller”: “ECAPI”,
    “CallerPhone”: “7708802337”,
    “Notes”: “Test Order Notes.”,
    “CallerEmail”: “[email protected]”,
    “TaskID”: “1”,
    “CompleteOrder”: “1”,
    “Description”: “Order Description”,
    “ReadyDateTime”: “12/05/2020 09:00”,
    “DueDateTime”: “12/05/20 11:00”,
    “AmountCharged”: “$40.00”,
    “DriverCode”: “”,
      “Pieces”: {
        “Piece”: {
          “Sequence”: “1”,
          “Reference”: “test1234barcode”,
           “Pieces”: “1”
        }

OBJECT DESCRIPTIONS

The XML schema definition (XSD) file of the full order schema is available here. This xsd defines all the attributes for the entire order schema including the links to the other xsd definitions for the sub-schemas for Stops, Jobs, OrderFees, OrderNotifiers, OrderEvents, and Customer. The JSON representation of the order follows the same conventions defined in the XSD definition.

Most fields defined in the schema are not required. The Save Order endpoint documentation above presents a simplified order JSON example with a minimal set of fields defined.

The Order Element is the top level of the JSON document. Each element contained in the order element is considered an order level attribute applies to the order as whole.

Each order has at least a pickup stop and a destination stop, but may contain many stops. The stop elements contain a sequence, stop type, name, address, and may contain OrderStopPieces elements. OrderStopPiece elements associate a piece with a stop.

Piece elements represent the individual parcels associated with an order. Pieces are not required, but can be used to list each item that is part of the order. Piece attributes include a piece reference, weight, height, width, quantity, and description.

The OrderStopPieces/OrderStopPiece is a child of the Stop element and generally associates a piece with a given stop. The OrderStopPiece consists of a PieceAction and Sequence element. PieceAction may be “P” for Pickup, or “D” for destination. The sequence of the OrderStopPiece matches the sequence of the corresponding piece in the Order/Pieces/Piece element.

FIELD DEFINITIONS

ORDER

A single instance of a delivery.
Each order may have other elements most are optional:
“Stops”
“Jobs” (optional)
“OrderFees” (optional)
“OrderNotifiers” (optional)
“OrderEvents” (optional)
“Customer” (optional)

ORDER ATTRIBUTES:

“OrderID” Type (integer) May not be set via API
“SiteID” Type (integer) May not be set via API
“SiteCode” Type (integer) May not be set via API
“OrderNumber” Type (string)
“OrderStatus” Type (string)
Available Values: “N” New, “A” Assigned, “I”, “P”, “X” Deleted, “T” Template
“OrderAlias” Type (string) (optional)

“TransferID” Type (integer) May not be set via API

“CustomerID” Type (integer) (optional)
“CustomerCode” Type (string) (optional)
“CreateDate” Type (Date) use=”optional” />
“CreateUserID” Type (integer) (optional)
“OrderDate” Type (Date) (optional)
“Service” Type (string) (optional)
“VehicleTypeID” Type (integer) (optional)
“VehicleType” Type (string) (optional)
“Pieces” Type (Double) (optional)
“Weight” Type (Double) (optional)
“PodRequired” Type (Boolean) (optional)
“PodSendType” Type (integer) (optional)
“AmountQuote” Type (Double) (optional)
“Caller” Type (string) (optional)
“CallerPhone” Type (string) (optional)
“AmountCharged” Type (Double) (optional)
“AmountReceived” Type (Double) (optional)
“QualityFlag” Type (Boolean) (optional)
“AutoVerify” Type (Boolean) (optional)
“UserName” Type (string) (optional)
“SiteCode” Type (string) (optional)
“PackageType” Type (string) (optional)
“CarrierTypeID” Type (integer) (optional)
“PriorityGroup” Type (string) (optional)
“TotalMiles” Type (Double) (optional)
“HolidayNameID” Type (integer) (optional)
“IncludeHolidayNameID” Type (integer) (optional)
“DueTimeHolidayNameID” Type (integer) (optional)
“FeeMisc1” Type (Boolean) (optional)
“FeeMisc2” Type (Boolean) (optional)
“FeeMisc3” Type (Boolean) (optional)
“FeeMisc4” Type (Boolean) (optional)
“Description” Type (string) (optional)
“OtherReference” Type (string) (optional)
“InvoiceReference” Type (string) (optional)
“Auth” Type (string) (optional)
“PodName” Type (string) (optional)
“PodDateTime” Type (Date) (optional)
“PodSign” Type (string) (optional)
“CodAmount” Type (Double) (optional)
“DeclaredValue” Type (Double) (optional)

STOPS

All Customer stops pickup/destination on a delivery

STOP (optional)

A single stop specfied by customer on the delivery

OrderStopPieces (optional) All Pieces on an order stop.

OrderStopPiece

“Sequence” Type (integer) (required)
“StopType” (optional)
Available Values: “P” Pickup, “D” Destination, “B” Both

“ScheduledDateTime” Type (DateTime) (optional)
“EarlyDateTime” Type (DateTime) (optional)
“LateDateTime” Type (DateTime) (optional)
“TimeOfServiceCode” Type (string) (optional)
“Zone” Type (string) (optional)
“DispatchZone” Type (string) (optional)
“Name” Type (string) (optional)
“Address” Type (string) (optional)
“City” Type (string) (optional)
“State” Type (string) (optional)
“Zip” Type (string) (optional)
“Country” Type (string) (optional)
“Phone” Type (string) (optional)
“See” Type (string) (optional)
“Room” Type (string) (optional)
“Note” Type (string) (optional)
“CustomerShipToCode” Type (string) (optional)
“LocationTypeID” Type (integer) (optional)
“DispatchGroupID” Type (integer) (optional)
“StopMiles” Type (Double) (optional)
“ZLatitude” Type (Double) (optional)
“ZLongitude” Type (Double) (optional)
“Latitude” Type (Double) (optional)
“Longitude” Type (Double) (optional)
“StopID” Type (integer) (optional)
“AVSQuality” Type (integer) (optional)
“ScheduledDateTimeTZ” Type (string) (optional)
“Pieces” Type (integer) (optional)
“Weight” Type (integer) (optional)
“Service” Type (string) (optional)
“Description” Type (string) (optional)
“ContractNumber” Type (string) (optional)
“RouteNumber” Type (string) (optional)
“Frequency” Type (string) (optional)
“DriverPay” Type (Double) (optional)
“AmountCharged” Type (Double) (optional)
“StopClassID” Type (integer) (optional)
“DriverCode” Type (string) (optional)

JOBS (optional)

All jobs on a delivery performed by all drivers.

JOBS (optional)

A unit of work on a delivery performed by a single driver.

Each Job may have other elements:

“Drivers”
“JobStops”
“Sequence” Type (integer) (required) AutoNumber field generated in ascending order for each job.

“JobNumber” Type (string) (optional)
“DeliverySequence” Type (integer) (optional)
“JobID” Type (integer) (optional)
“JobStatus” Type (string) (optional)
“JobDate” Type (Date) (optional)
“SiteID” Type (integer) (optional)
“Service” Type (string) (required)
“VehicleTypeID” Type (integer) (optional)
“Pieces” Type (Double) (optional)
“Weight” Type (Double) (optional)
“DispatchGroupID” Type (integer) (optional)
“DispatchGroupOverride” Type (integer) (optional)
“ManifestDriverID” Type (integer) (optional)
“SplitPercentage” Type (integer) (optional)
“RouteNumber” Type (string) (required)
“JobModeID” Type (integer) (optional)

DRIVERS

All drivers on a delivery for each JobStop.

Driver A single instance of a Driver

“Sequence” Type (integer) (required)
AutoNumber field generated in acending order for each job stop
“DriverID” Type (integer)
“DriverCode” Type (string)
“DriverPay” Type (Decimal)
“DriverBaseAmount” Type (Decimal)
“DriverCommissionPercent” Type (Decimal)
“DriverBaseAmountOverride” Type (Boolean)

JOBSTOPS

All stops on a delivery performed by all drivers.

JobStop (optional)

JobStopPieces (optional) All piece on a job stop.

JobStopPiece (optional) A single instance of a piece on an order stop.

“Sequence” Type (integer) (optional)
“JobStopPieceID” Type (integer) (optional)
“PieceID” Type (integer) (optional)
“PieceAction” Type (string) (optional)
“PieceActionStatus” Type (string) (optional)
“ArriveDateTime” Type (DateTime) (optional)
“EnteredDateTime” Type (DateTime) (optional)
“EnteredUserID” Type (integer) (optional)
“EnteredUserName” Type (string) (optional)
“EnteredSource” Type (string) (optional)
“PieceActionStatusSource” Type (string) (optional)
“Color” Type (string) (optional)

“StopType” A category of stop eg…Pickup, Delivery or Both
Available Values: “P” Pickup, “D”, Destination, “B” Both

“ScheduledDateTime” Type (DateTime)
The scheduled time a pickup on a stop can be made.
“EarlyDateTime” Type (DateTime)
The earliest time a pickup on a stop can be made.
“LateDateTime” Type (DateTime)
The latest time a pickup on a stop can be made.
“TimeOfServiceCode” Type (string)
A category code that represents a block of time(eg after 5PM)
“Zone” Type (string)
A rating zone for a pickup stop.
“DispatchZone” Type (string)
A dispatch zone code used to identify a dispatcher area of control
“Name” Type (string)
Customer name on this stop.
“Address” Type (string)
Stop address
“City” Type (string)
Stop city
“State” Type (string)
Stop state
“Zip” Type (string)
Stop Zip code
“LocationTypeID” Type (integer)
Cross reference to location types.
“JobStopStatus” Type (string) (optional)
“ArriveDateTime” Type (DateTime) (optional)
“DepartDateTime” Type (DateTime) (optional)
“Pieces” Type (integer) (optional)
“Weight” Type (integer) (optional)
“PodName” Type (string) (optional)
“PodDateTime” Type (DateTime) (optional)
“ArriveDateTimeSource” Type (string) (optional)
“DepartDateTimeSource” Type (string) (optional)
“ManifestDriverID” Type (integer) (optional)
“ZLatitude” Type (Double) (optional)
Latitude of zip code.
“ZLongitude” Type (Double) (optional)
Longitude of zip code.
“Latitude” Type (Double) (optional)
“Longitude” Type (Double) (optional)
“StopID” Type (integer) (optional)
“Country” Type (string) (optional)
“Room” Type (string) (optional)
“Note” Type (string) (optional)
“Phone” Type (string) (optional)
“See” Type (string) (optional)
“CustomerShipToCode” Type (string) (optional)
“Service” Type (string) (optional)
“Description” Type (string) (optional)
“ContractNumber” Type (string) (optional)
“RouteNumber” Type (string) (optional)
“Frequency” Type (string) (optional)
“DriverPay” Type (Double) (optional)
“AmountCharged” Type (Double) (optional)
“StopClassID” Type (integer) (optional)
“DriverCode” Type (string) (optional)

OrderNotifiers
All notifications on a delivery.

OrderNotify (optional) An occurance of an order notify

“Sequence” Type (integer) (required) AutoNumber field that should be generated in ascending order for each order notify.
“OrderNotifyID” Type (integer) (required)
Possible Values:
CMS Order Create = -1
CMS Order Dispatch = -2
CMS Order Stop = 1
CMS Order POD = 2
CMS Order PODApprove = 3
MobileAlert = 4
CMS PayVerify EMail = 5
CMS Order Pickup = 6
Web Remote OrderConfirmation = 7
Web Order Create = 8
Web Order Pickup = 9
Web Order Delivered = 10
CMS JobStop Clear = 11
CMS Order Transfer Confirm = 12
“NotifyEmail” Type (string) (required)
Email address to send the notification to
“NotifyDateTime” Type (DateTime) use=”prohibited”>
System date stamp of the date / time notification was sent
“FromEmail” Type (string) use=”optional”
Email address that the notification came from if left blank system default will be used
“Subject” Type (string) (required)
Short subject text of the email, note allows token subsitution using $ preface on order xsd attributes
“StyleSheetID” Type (integer) (required)
Internal Stylesheet ID to use when performing the xsl transform to create the email body of the notification
“CustomerNotifyID” Type (integer) (optional)
Internal default order notify template that me be used to create a order notify instance

OrderEvents
All Events on a delivery

OrderEvent (optional)
An occurence of a defined milestone in the lifetime of a delivery. eg Pickup, POD, Status change, etc.

“OrderEventID” Type (integer) (May only be set in e-Courier System)
“EventType” Type (string) (May only be set in e-Courier System)
“EventDateTime” Type (DateTime) (May only be set in e-Courier System)
“UserName” Type (string) (May only be set in e-Courier System)
“UserID” Type (integer) (May only be set in e-Courier System)
“Note” Type (string) (May only be set in e-Courier System)
“EventSource” Type (string) (May only be set in e-Courier System)
“EventNote” Type (string) (May only be set in e-Courier System)
“EdiNote” Type (string) (May only be set in e-Courier System)

OrderFees
All fee’s on a order

OrderFee (optional)
A line item unit of pricing for a ‘job task’ on an order

“Sequence” Type (integer) (required)
“SubSequence” Type (integer) (required)
“FeeAmount” Type (Double) (required)
“FeeValue” Type (string) (required)
“OverrideFlag” Type (Boolean) (optional)
“Notes” Type (string) (optional)
“FeeTitle” Type (string) (optional)
“FeeCode” Type (string) (optional)

Customer
Billing customer for a delivery
“CustomerID” Type (integer) (required)
“CustomerCode” Type (string) (required)
“Name” Type (string) (required)
“Address” Type (string) (required)
“City” Type (string) (required)
“State” Type (string) (required)
“Zip” Type (string) (required)
“Country” Type (string)
“Phone” Type (string) (required)
“See” Type (string) (optional)
“PState” Type (string) (required)
“PCountry” Type (string)
“Notes” Type (string) (optional)
“Service” Type (string) (optional)
“VehicleTypeID” Type (integer) (optional)
“CreatedDate” Type (Date)
“ReferencePrompt” Type (string) (optional)
“SiteID” Type (integer) (required)
“CustomerTypeID” Type (integer) (required)
“SiteCode” Type (string) (optional)
“OkCreditStatus” Type (integer)

RESPONSE STATUS CODES

HTTP Status 200 is the normal success response condition.

Additionally, a JSON response object may be returned such as:

{
“status”: “0”,
“statusdescription”: “JSON Post Received”
}

Any HTTP 409 status returned indicates the post message was unable to perform an update or cancellation of an existing order due to business rules set by NIN customer.

An HTTP status 409 will be accompanied by a status description indicating:

Order Unable to Cancel or Order Unable to Modify

An HTTP status 500 occurs when an error occurs. When this happens a JSON object is returned with a specific error code to indicate what failed in the transmission.

An error status of -1 is a general error without additional diagnostic information available.

{
“status”: “-1”,
“statusdescription”: “An undefined error has occurred”
}

An error status of -2 indicates that message submitted was unable to be parsed. This is generally caused by a formatting error. In this case validate your JSON document and attempt to repost.

{
“status”: “-2”,
“statusdescription”: “Unable to parse JSON”
}

An error status of -3 indicates the NIN database is unavailable. In this case, wait and retry your submission at a later time.

{
“status”: “-3”,
“statusdescription”: “Unable to Connect to Database”
}

An error status of -4 indicates the requested action was unable to be performed. This can occur if required order elements are missing, or if submitted values do not match available options in the customer system. In this case, the status description will attempt to return useful information to determine why the requested action was not performed.

{
“status”: “-4”,
“statusdescription”: “Order Not Found”
}

An error status of -5 indicates the UserGUID access token was not provided.

{
“status”: “-5”,
“statusdescription”: “No UserGUID Received”
}

An error status of -6 indicates an underlying configuration file was not found. This generally indicates the endpoint is not configured properly to accept messages for this customer or with the provided UserGUID. In this case, contact the NIN customer to seek support in configuring the API properly.

{
“status”: “-6”,
“statusdescription”: “No config file found: Configuration='{00000000-0000-0000-0000-00000000}”
}