4 Collect and Receive Base APIs

This chapter describes the Collect and Receive base APIs:

• Quote Services

  • Build a Quote — POST

  • Get a Quote — GET

  • Checks if a Quote Exists — HEAD

  • Queries for a Quote — GET

  • Queries for Quote Records/Count — GET

  • Queries for Quote Records by Attributes — GET

• Delivery Services

  • Build a Delivery — POST

  • Cancel a Delivery — POST

  • Get the Current Status of a Delivery — GET

  • Get a Delivery — GET

  • Checks if a Delivery Exists — HEAD

  • Queries for Delivery Records — GET

  • Queries for Delivery Records/Count — GET

  • Queries for Delivery Records by Attributes — GET

• Metrics Services

  • Metrics — GET

  • Location Metrics — GET

• Webhook Credential Services

  • Add Credential — POST

  • Get Credentials — GET

  • Get Credential — GET

  • Update Credential — PUT

  • Delete Credential — DELETE

• Status Notification Webhook Services

  • Add a New Webhook — POST

  • Queries for Webhook Records — GET

  • Performs a Bulk Action using a Collection of Webhook — POST

  • Queries for Webhook Records/Count — GET

  • Get a Webhook — GET

  • Update a Webhook — PUT

  • Delete a Webhook — DELETE

  • Checks If a Webhook Exists — HEAD

  • Queries for Webhook Records By Attributes — GET

• Data Retention Configuration Service

  • Add a New DataRetentionConfig — POST

  • Queries for DataRetention Configuration Records — GET

  • Queries for DataRetention Configuration Records/Count — GET

  • Get a DataRetention Configuration — GET

  • Update a DataRetention Configuration — PUT

  • Delete a DataRetention Configuration — DELETE

  • Checks If a DataRetention Configuration Exists — HEAD

  • Queries for DataRetention Configuration Records By Attributes — GET

The Collect and Receive contains the following OpenAPI endpoint, which can be used to obtain the specification for the services it provides.

api/delivery/openapi 

Quote Services

This section describes the Quote services.

Build a Quote — POST

This section describes the Build Quote endpoint. The Build Quote endpoint is used to check courier serviceability, validity, and cost for a delivery between the pickup and dropoff addresses. The Build Quote request gets a quote and should be made prior to submitting the request to Build a Delivery. The quote is valid for a short period of time and the quote ID returned in the response message is sent as part of the request to Build a Delivery.

Method

POST

URL

/api/delivery/v5/quote/build

Allowed Scope(s)

delivery-rw 

Request

There are no request parameters for this operation.

The request content-type is application/json.

The ModelField request.

Example Value

{
  "deliveryType": "DELIVERY",
  "undeliverableAction": "LEAVE_AT_DOOR",
  "crossReferences": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "deliveryId": "string",
  "dropoffAddress": {
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "latitude": 0,
    "locationCode": "string",
    "longitude": 0,
    "postalCode": "string",
    "state": "string"
  },
  "dropoffContact": {
    "businessName": "string",
    "contactReference": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "phoneNumber": "string",
    "suffix": "string"
  },
  "dropoffDeadline": "2024-12-02T14:43:05.312Z",
  "dropoffNotes": "string",
  "dropoffOptions": {
    "additionalInstructions": "string",
    "barcodeRequired": false,
    "contactRequired": false,
    "minimumAge": 9999,
    "pictureRequired": false,
    "pincode": "string",
    "signatureRequired": false
  },
  "dropoffReady": "2024-12-02T14:43:05.312Z",
  "labelsAttached": false,
  "manifest": [
    {
      "description": "string",
      "height": 9999,
      "identifier": "string",
      "items": [
        {
          "description": "string",
          "identifier": "string",
          "price": 10000000000000000,
          "quantity": 9999
        }
      ],
      "length": 9999,
      "packDimensionCode": "string",
      "totalAmount": 10000000000000000,
      "weight": 10000000000000000,
      "width": 9999
    }
  ],
  "pickupAddress": {
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "latitude": 0,
    "locationCode": "string",
    "longitude": 0,
    "postalCode": "string",
    "state": "string"
  },
  "pickupContact": {
    "businessName": "string",
    "contactReference": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "phoneNumber": "string",
    "suffix": "string"
  },
  "pickupDeadline": "2024-12-02T14:43:05.312Z",
  "pickupNotes": "string",
  "pickupOptions": {
    "additionalInstructions": "string",
    "barcodeRequired": false,
    "contactRequired": false,
    "minimumAge": 9999,
    "pictureRequired": false,
    "pincode": "string",
    "signatureRequired": false
  },
  "pickupReady": "2024-12-02T14:43:05.312Z",
  "provider": "string",
  "quoteId": <quoteId>,
  "tip": 10000000000000000,
  "totalValue": 10000000000000000
}

Schema — Delivery Request

The following table describes details of proposed delivery request.

Table 4-1 Delivery Request — Object

Element Name	Required	Data Type	Description
deliveryType	NA	string	The delivery type identifier. Default: DELIVERY; Enum: DELIVERY; RETURN
undeliverableAction	NA	string	Indicates what the courier should do with the packages in the event they are unable to be delivered. Enum: LEAVE_AT_DOOR, RETURN
crossReferences	NA	object	Cross references for the delivery. Intended for use by the retailer as an additional reference stored with the delivery order.
deliveryId	Yes	string (128)	The primary reference ID from the calling system uniquely identifying this delivery. Multiple quotes may be obtained, but only one delivery may be arranged for a given reference ID.
dropoffAddress	Yes	object	An address for a given dropoff location.
dropoffContact	Yes	object	A point of contact for a given dropoff location.
dropoffDeadline	NA	string <date-time>	The time by which the items must be dropped off. Date-time strings are in ISO 8601 timestamp with offset format.
dropoffNotes	NA	string	Notes for the courier at drop-off location.
dropoffOptions	NA	object	Options for customizing required verification.
dropoffReady	NA	string <date-time>	The time at which the items may be dropped off. Date-time strings are in ISO 8601 timestamp with offset format.
labelsAttached	NA	boleean	Indicates whether the package(s) will have a pre-paid shipping label attached when the courier arrives. Default: false Note: Return delivery types have the following limitations with the Uber integration: Labels Attached will always be set to TRUE which indicates that a label will be attached to the package(s).
manifest	Yes	object	The packages to be delivered.
pickupAddress	Yes	object	An address given pickup location.
pickupContact	Yes	object	A point of contact for a given pickup location.
pickupDeadline	NA	string <date-time>	The time by which the items must be picked up. Date-time strings are in ISO 8601 timestamp with offset format.
pickupNotes	NA	string	Notes for the courier at pickup location.
pickupOptions	NA	object	Options for customizing required verification.
pickupReady	NA	string <date-time>	The time at which the items will be ready for pickup. Date-time strings are in ISO 8601 timestamp with offset format.
provider	NA	string (10)	The preferred provider.
quoteId	NA	integer <int64>	The prior quote ID for the delivery, if applicable.
tip	NA	number	The amount of the tip.
totalValue	Yes	number	The total value of the request.

The following table describes the elements of an address for a pickup or delivery.

Table 4-2 Request Address

Element Name	Required	Data Type	Description
address1	Yes	string (254)	The address line 1.
address2	NA	string (254)	The address line 2.
address3	NA	string (254)	The address line 3.
address4	NA	string (254)	The address line 4.
addressType	NA	string	enum: RESIDENTIAL, BUSINESS
apartment	NA	string (254)	The apartment.
city	Yes	string (254)	The city or town.
country	Yes	string (254)	The ISO 3166 country code. Applications can decide whether to use 2 or 3 char codes.
latitude	NA	number	The latitude of the address.
locationCode	NA	string (10)	The location code for the address, if applicable. This must be unique across the retailer's landscape.
longitude	NA	number	The longitude of the address.
postalCode	NA	string (20)	The postal code.
state	NA	string (254)	The ISO 3166 state, province or territory code.

The following table describes the elements of a point of contact for a given pickup or delivery.

Table 4-3 Request Contact

Element Name	Required	Data Type	Description
businessName	NA	string (254)	The business name.
contactReference	NA	string (64)	A reference number for the contact.
emailAddress	NA	string (254)	The email address.
firstName	NA	string (254)	The first (that is, given) name.
lastName	NA	string (254)	The last (that is, family) name.
middleName	NA	string (254)	The middle name.
phoneNumber	Yes	string (50)	The phone number.
suffix	NA	string (254)	A name suffix.

The following table describes the elements of options for customizing required verification.

Table 4-4 Verification Options

Element Name	Required	Data Type	Description
additionalInstructions	NA	string	Additional instructions for the courier at handoff.
barcodeRequired	NA	boolean	Indicates that a barcode scan is required. Default: false
contactRequired	NA	boolean	Indicates that contact is required (that is must NOT be contactless). Default: false
minimumAge	NA	integer <int32>	The minimum age of the recipient. If this value is specified, Uber will reject the request if the age is not between 18 and 25. Note: Return delivery types have the following limitations with the Uber integration: The use of Minimum Age is not supported as drop off verification option.
pictureRequired	NA	boolean	Indicates that a picture is required. Default: false Note: Return delivery types have the following limitations with the Uber integration: Picture Required will always be set to TRUE which requires the courier to take a picture as a drop off verification.
pincode	NA	string	A pincode required for entry at handoff. Note: Return delivery types have the following limitations with the Uber integration: The use of Pincodes are not supported as drop off verification option.
signatureRequired	NA	boolean	Indicates that a signature is required. Default: false

The following table describes the elements of a package of items to be delivered.

Table 4-5 Manifest Package — Object

Element Name	Required	Data Type	Description
description	NA	string (128)	The description of the package.
height	Yes	integer <int32>	The height of the item in centimeters.
identifier	Yes	string (100)	A unique identifier for the package. This value will be considered when producing verification barcodes.
items	NA	object	The items to be delivered.
length	Yes	integer <int32>	The length of the item in centimeters.
packDimensionCode	NA	string	The package dimension code.
totalAmount	NA	number	The combined prices of all items within the package.
weight	Yes	number	The weight of the item in kilograms.
width	Yes	integer <int32>	The width of the item in centimeters.

The following table describes the elements of an individual item within a delivery.

Table 4-6 Item — Object

Element Name	Required	Data Type	Description
description	Yes	string (128)	The description of the item.
identifier	Yes	string (100)	The identifier (UPC, EAN, SKU, and so on) of the item.
price	NA	number	The price of the item.
quantity	Yes	integer <int32>	The quantity of the item.

Responses

This section describes the responses of the buildQuote endpoint.

Response Code: 200

The result object.

The media type is application/json.

Example Value

{
  "errors": [
    {
      "errorCode": 2147483647,
      "errorMessage": "string",
      "moreInfo": {
        "code": "string",
        "description": "string"
      },
      "provider": "string"
    }
  ],
  "quotes": [
    {
      "created": "2024-05-23T13:44:28.179Z",
      "createdBy": "string",
      "updated": "2024-05-23T13:44:28.179Z",
      "updatedBy": "string",
      "id": <id>,
      "crossReferences": [
        {
          "created": "2024-05-23T13:44:28.179Z",
          "createdBy": "string",
          "updated": "2024-05-23T13:44:28.179Z",
          "updatedBy": "string",
          "id": <id>,
          "key": "string",
          "parentId": <parentId>,
          "value": "string"
        }
      ],
      "currency": "str",
      "deliveryId": "string",
      "deliveryType": "DELIVERY",
      "dropoffAddress": {
        "created": "2024-05-23T13:44:28.179Z",
        "createdBy": "string",
        "updated": "2024-05-23T13:44:28.179Z",
        "updatedBy": "string",
        "id": <id>,
        "address1": "string",
        "address2": "string",
        "address3": "string",
        "address4": "string",
        "addressType": "RESIDENTIAL",
        "apartment": "string",
        "city": "string",
        "country": "string",
        "latitude": 999999999,
        "locationCode": "string",
        "longitude": 999999999,
        "postalCode": "string",
        "state": "string"
      },
      "dropoffAddressId": <dropoffAddressId>,
      "dropoffContact": {
        "created": "2024-05-23T13:44:28.179Z",
        "createdBy": "string",
        "updated": "2024-05-23T13:44:28.179Z",
        "updatedBy": "string",
        "id": <id>,
        "businessName": "string",
        "contactReference": "string",
        "emailAddress": "string",
        "firstName": "string",
        "lastName": "string",
        "middleName": "string",
        "phoneNumber": "string",
        "suffix": "string"
      },
      "dropoffContactId": <dropoffContactId>,
      "dropoffDeadline": "2024-05-23T13:44:28.179Z",
      "dropoffEta": "2024-05-23T13:44:28.179Z",
      "dropoffLocationCode": "string",
      "expires": "2024-05-23T13:44:28.179Z",
      "fee": 10000000000000000,
      "pickupAddress": {
        "created": "2024-05-23T13:44:28.179Z",
        "createdBy": "string",
        "updated": "2024-05-23T13:44:28.179Z",
        "updatedBy": "string",
        "id": <id>,
        "address1": "string",
        "address2": "string",
        "address3": "string",
        "address4": "string",
        "addressType": "RESIDENTIAL",
        "apartment": "string",
        "city": "string",
        "country": "string",
        "latitude": 999999999,
        "locationCode": "string",
        "longitude": 999999999,
        "postalCode": "string",
        "state": "string"
      },
      "pickupAddressId": <pickupAddressId>,
      "pickupContact": {
        "created": "2024-05-23T13:44:28.179Z",
        "createdBy": "string",
        "updated": "2024-05-23T13:44:28.179Z",
        "updatedBy": "string",
        "id": <id>,
        "businessName": "string",
        "contactReference": "string",
        "emailAddress": "string",
        "firstName": "string",
        "lastName": "string",
        "middleName": "string",
        "phoneNumber": "string",
        "suffix": "string"
      },
      "pickupContactId": <pickupContactId>,
      "pickupDeadline": "2024-05-23T13:44:28.179Z",
      "pickupEta": "2024-05-23T13:44:28.179Z",
      "pickupLocationCode": "string",
      "provider": "string",
      "providerCreated": "2024-05-23T13:44:28.179Z",
      "providerId": "string",
      "providerInstance": "string"
    }
  ]
}

Schema — Quote Response

The following table describes the elements of a response to a quote request.

Table 4-7 Quote Response — Object

Element Name	Required	Data Type	Description
errors	NA	object	A collection of errors from providers which could not service the request.
quotes	NA	object	A collection of quotes for the provided request.

The following table describes elements of a container for an error from a provider.

Table 4-8 Provider Errors — Object

Element Name	Required	Data Type	Description
errorCode	NA	integer <int32>	A numeric error indicating the type of error.
errorMessage	NA	string	An unlocalized message indicating details about the error.
moreInfo	NA	object	An object containing provider-specific details pertaining to an error.
provider	Yes	string (10)	The provider associated with the error.

The following table describes elements of an object containing provider-specific details pertaining to an error.

Table 4-9 More Error Information — Object

Element Name	Required	Data Type	Description
code	NA	string	A code describing the error.
description	NA	string	An unlocalizable description describing the error.

The following table describes elements of a quote from a delivery provider for a proposed delivery.

Table 4-10 Quote — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
crossReferences	NA	Collection of [object]	A list of cross-references for the quote.
currency	NA	string (3)	The currency code associated with the quote.
deliveryId	Yes	string (128)	The primary reference ID from the calling system uniquely identifying the delivery associated with this quote.
deliveryType	Yes	string	The delivery type identifier. Default: DELIVERY; Enum: DELIVERY, RETURN
dropoffAddress	NA	object	An address for a given dropoff location.
dropoffAddressId	NA	integer <int64>	Drop Off Address ID
dropoffContact	NA	object	A point of contact for a given dropoff location.
dropoffContactId	NA	integer <int64>	Drop Off Contact ID
dropoffDeadline	NA	string <date-time>	The time by which the order must be dropped off. Date-time strings are in ISO 8601 timestamp with offset format.
dropoffEta	NA	string <date-time>	The time by which the order is expected to be dropped off. Date-time strings are in ISO 8601 timestamp with offset format.
dropoffLocationCode	NA	string(10)	The location code for the dropoff address.
expires	NA	string <date-time>	The time at which this quote will no longer be accepted. Date-time strings are in ISO 8601 timestamp with offset format.
fee	NA	number	The cost of the delivery
pickupAddress	NA	object	An address for a given pickup location.
pickupAddressId	NA	integer <int64>	Pick Up Address ID.
pickupContact	NA	object	A point of contact for a given pickup location.
pickupContactId	NA	integer <int64>	Pick Up Contact ID.
pickupDeadline	NA	string <date-time>	The time by which the order must be picked up. Date-time strings are in ISO 8601 timestamp with offset format.
pickupEta	NA	string <date-time>	The time by which the order is expected to be picked up. Date-time strings are in ISO 8601 timestamp with offset format.
pickupLocationCode	NA	string (10)	The pickup location code associated with this quote.
provider	Yes	string (10)	The provider of the quote.
providerCreated	Yes	string <date-time>	The creation timestamp, as indicated by the provider. Date-time strings are in ISO 8601 timestamp with offset format.
providerInstance	Yes	string (20)	The specific instance of the provider of the quote.
providerlId	Yes	string (128)	The id from the provider of the quote.

The following table describes the elements of an address for a pickup or delivery.

Table 4-11 Address

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	<int64>	ID
address1	Yes	string (254)	The address line 1.
address2	NA	string (254)	The address line 2.
address3	NA	string (254)	The address line 3.
address4	NA	string (254)	The address line 4.
addressType	NA	string	enum: RESIDENTIAL, BUSINESS
apartment	NA	string (254)	The apartment.
city	Yes	string (254)	The city or town.
country	Yes	string (254)	The ISO 3166 country code. Applications can decide whether to use 2 or 3 char codes.
latitude	NA	number	The latitude of the address.
locationCode	NA	string (10)	The location code for the address, if applicable. This must be unique across the retailer's landscape.
longitude	NA	number	The longitude of the address.
postalCode	NA	string (20)	The postal code.
state	NA	string (254)	The ISO 3166 state, province or territory code.

The following table describes the elements of a point of contact for a given pickup or delivery.

Table 4-12 Contact

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who last created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	<int64>	ID
businessName	NA	string (254)	The business name.
contactReference	NA	string (64)	A reference number for the contact.
emailAddress	NA	string (254)	The email address.
firstName	NA	string (254)	The first (that is, given) name.
lastName	NA	string (254)	The last (that is, family) name.
middleName	NA	string (254)	The middle name.
phoneNumber	Yes	string (50)	The phone number.
suffix	NA	string (254)	A name suffix.

The following table describes the elements of a cross reference record.

Table 4-13 Quote Cross References — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
key	Yes	string (128)	The identifier for the cross reference.
parentId	NA	integer <int64>	Parent ID
value	Yes	string (128)	The the value of the cross reference.

Response Code: 204

No providers were eligible to service this request.

Response Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

The table below describes the elements of the Mapper Error Data object.

Table 4-14 Mapper Error Data — Object

Element Name	Required	Data Type	Description
column	NA	integer <int32>	The JSON file column number the error occurred on if known
line	NA	integer <int32>	The JSON file line number the error occurred on if known
errorCode	NA	integer <int32>	A numeric identifier for the type of error
errorMessage	NA	string	The unlocalized error message
moreInfo	NA	object	Additional information pertaining to the error
field	NA	string	The field. This is the last part of the path
value	NA	string	The JSON value that caused the error if known
errorType	NA	string	enum: INTEGRATION, INTERNAL, MAPPING, PARSING, VALIDATION An enumeration of specific known error types.

The following table describes the elements of the additional information pertaining to the error.

Table 4-15 More Info — Object

Element Name	Required	Data Type	Description
code	NA	string	A code describing the error.
description	NA	string	An unlocalizable description describing the error.

Response Code: 404

Provided quote ID or associated provider could not be found.

Response Code: 424

No providers could service this request.

The media type is application/json.

Example Value

[
  {
    "errorCode": 2147483647,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "provider": "string"
  }
]

Schema — Provider Error

The following table describes elements of a container for an error from a provider.

Table 4-16 Provider Error — Object

Element Name	Required	Data Type	Description
errorCode	NA	integer <int32>	A numeric error indicating the type of error.
errorMessage	NA	string	An unlocalized message indicating details about the error.
moreInfo	NA	object	An object containing provider-specific details pertaining to an error.
provider	Yes	string (10)	The provider associated with the error.

The following table describes elements of an object containing provider-specific details pertaining to an error.

Table 4-17 More Error Information — Object

Element Name	Required	Data Type	Description
code	NA	string	A code describing the error.
description	NA	string	An unlocalizable description describing the error.

Response Code: 500

The request failed.

Get a Quote — GET

This section describes the Get a Quote endpoint. Use the Get a Quote endpoint to get the quote details for an existing quote record.

Method

GET

URL

/api/delivery/v5/quote/{id}

Allowed Scope(s)

delivery-r
delivery-rw 

Request

This section describes the request parameters.

Table 4-18 Get a Quote — Request Parameters

Parameter	Required	Data Type	Description
id	Yes	integer <int64>	ID
expands	NA	string	A comma-delimited list of relationship paths, in dot-notated path form (that is, "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.

Responses

This section describes the Get a Quote endpoint responses.

Response Code: 200

The requested record.

The media type is application/json.

Example Value

{
  "created": "2024-05-23T14:17:10.839Z",
  "createdBy": "string",
  "updated": "2024-05-23T14:17:10.839Z",
  "updatedBy": "string",
  "id": <id>,
  "crossReferences": [
    {
      "created": "2024-05-23T14:17:10.839Z",
      "createdBy": "string",
      "updated": "2024-05-23T14:17:10.839Z",
      "updatedBy": "string",
      "id": <id>,
      "key": "string",
      "parentId": 9223372036854776000,
      "value": "string"
    }
  ],
  "currency": "str",
  "deliveryId": "string",
  "deliveryType": "DELIVERY",
  "dropoffAddress": {
    "created": "2024-05-23T14:17:10.839Z",
    "createdBy": "string",
    "updated": "2024-05-23T14:17:10.839Z",
    "updatedBy": "string",
    "id": <id>,
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "latitude": 999999999,
    "locationCode": "string",
    "longitude": 999999999,
    "postalCode": "string",
    "state": "string"
  },
  "dropoffAddressId": <dropoffAddressId>,
  "dropoffContact": {
    "created": "2024-05-23T14:17:10.839Z",
    "createdBy": "string",
    "updated": "2024-05-23T14:17:10.839Z",
    "updatedBy": "string",
    "id": <id>,
    "businessName": "string",
    "contactReference": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "phoneNumber": "string",
    "suffix": "string"
  },
  "dropoffContactId": <dropoffContactId>,
  "dropoffDeadline": "2024-05-23T14:17:10.839Z",
  "dropoffEta": "2024-05-23T14:17:10.839Z",
  "dropoffLocationCode": "string",
  "expires": "2024-05-23T14:17:10.839Z",
  "fee": 10000000000000000,
  "pickupAddress": {
    "created": "2024-05-23T14:17:10.839Z",
    "createdBy": "string",
    "updated": "2024-05-23T14:17:10.839Z",
    "updatedBy": "string",
    "id": <id>,
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "latitude": 999999999,
    "locationCode": "string",
    "longitude": 999999999,
    "postalCode": "string",
    "state": "string"
  },
  "pickupAddressId": <pickupAddressId>,
  "pickupContact": {
    "created": "2024-05-23T14:17:10.839Z",
    "createdBy": "string",
    "updated": "2024-05-23T14:17:10.839Z",
    "updatedBy": "string",
    "id": <id>,
    "businessName": "string",
    "contactReference": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "phoneNumber": "string",
    "suffix": "string"
  },
  "pickupContactId": <pickupContactId>,
  "pickupDeadline": "2024-05-23T14:17:10.839Z",
  "pickupEta": "2024-05-23T14:17:10.839Z",
  "pickupLocationCode": "string",
  "provider": "string",
  "providerCreated": "2024-05-23T14:17:10.839Z",
  "providerId": "string",
  "providerInstance": "string"
}

Schema — Quote

The tables below describe the elements of a quote from a delivery provider for a proposed delivery.

Table 4-19 Quote — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
crossReferences	NA	object	A list of cross-references for the quote.
currency	NA	string (3)	The currency code associated with the quote.
deliveryId	Yes	string (128)	The primary reference ID from the calling system uniquely identifying the delivery associated with this quote.
deliveryType	Yes	string	The delivery type identifier. Default: DELIVERY; Enum: DELIVERY, RETURN
dropoffAddress	NA	object	An address for a given dropoff location.
dropoffAddressId	NA	integer <int64>	NA
dropoffContact	NA	object	A point of contact for a given dropoff location.
dropoffContactId	NA	integer <int64>	NA
dropoffDeadline	NA	string <date-time>	The time by which the order must be dropped off. Date-time strings are in ISO 8601 timestamp with offset format.
dropoffEta	NA	string <date-time>	The time by which the order is expected to be dropped off. Date-time strings are in ISO 8601 timestamp with offset format.
dropoffLocationCode	NA	string(10)	The location code for the dropoff address.
expires	NA	string <date-time>	The time at which this quote will no longer be accepted. Date-time strings are in ISO 8601 timestamp with offset format.
fee	NA	number	The cost of the delivery.
pickupAddress	Yes	object	An address given pickup location.
pickupAddressId	NA	integer <int64>	NA
pickupContact	NA	object	A point of contact for a given pickup location.
pickupContactId	NA	integer <int64>	NA
pickupDeadline	NA	string <date-time>	The time by which the order must be picked up. Date-time strings are in ISO 8601 timestamp with offset format.
pickupEta	NA	string <date-time>	The time by which the order is expected to be picked up. Date-time strings are in ISO 8601 timestamp with offset format.
pickupLocationCode	NA	string (10)	The pickup location code associated with this quote.
provider	Yes	string (10)	The provider of the quote.
providerCreated	Yes	string <date-time>	The creation timestamp, as indicated by the provider. Date-time strings are in ISO 8601 timestamp with offset format.
providerInstance	Yes	string (20)	The specific instance of the provider of the quote.
providerId	Yes	string (128)	The ID from the provider of the quote.

The following table describes the elements of a cross reference record for a quote from a delivery provider for a proposed delivery.

Table 4-20 Quote Cross Reference — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
key	Yes	string (128)	The identifier for the cross reference.
parentId	NA	integer <int64>	Parent ID
value	Yes	string (128)	The the value of the cross reference.

The following table describes the elements of an address for a given pickup or delivery.

Table 4-21 Address

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
address1	Yes	string (254)	The address line 1.
address2	NA	string (254)	The address line 2.
address3	NA	string (254)	The address line 3.
address4	NA	string (254)	The address line 4.
addressType	NA	string	enum: RESIDENTIAL, BUSINESS
apartment	NA	string (254)	The apartment.
city	Yes	string (254)	The city or town.
country	Yes	string (254)	The ISO 3166 country code. Applications can decide whether to use 2 or 3 char codes.
latitude	NA	number	The latitude of the address.
locationCode	NA	string (10)	The location code for the address, if applicable. This must be unique across the retailer's landscape.
longitude	NA	number	The longitude of the address.
postalCode	NA	string (20)	The postal code.
state	NA	string (254)	The ISO 3166 state, province or territory code.

The following table describes the elements of a point of contact for a given pickup or delivery.

Table 4-22 Contact

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
businessName	NA	string (254)	The business name.
contactReference	NA	string (64)	A reference number for the contact.
emailAddress	NA	string (254)	The email address.
firstName	NA	string (254)	The first (that is, given) name.
lastName	NA	string (254)	The last (that is, family) name.
middleName	NA	string (254)	The middle name.
phoneNumber	Yes	string (50)	The phone number.
suffix	NA	string (254)	A name suffix.

Response Code: 404

The record could not be found.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Checks if a Quote Exists — HEAD

This section describes the endpoint which checks if a quote exists.

Method

HEAD

URL

/api/delivery/v5/quote/{id}

Allowed Scope(s)

delivery-r
delivery-rw 

Request

This section describes the request parameters.

Table 4-23 Checks if a Quote Exists — Request Parameters

Parameter	Required	Data Type	Description
id	Yes	integer <int64> (path)	ID

Responses

This section describes the responses of the Checks if a Quote Exists endpoint.

Response Code: 200

The requested record exists.

Response Code: 404

The record could not be found.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Queries for a Quote — GET

This section describes the Queries for a Quote endpoint. This service returns a list of quote records and the associated quote details matching the provided criteria.

Method

GET

URL

/api/delivery/v5/quote

Allowed Scope(s)

delivery-r
delivery-rw 

Request

This section describes the request parameters.

Table 4-24 Queries for a Quote Records— Request Parameters

Parameter	Required	Data Type	Description
where	NA	object (query)	A JSON object containing query parameters for filtering results. Fields to be filtered on may be provided in the form of a dot-notated path named for the fields known to this resource, that is a delimited field named "child.id" would filter by the entity field of this resource named "child" and that entity has a field named "id". Querying is supported in 3 ways. If a single value is provided, it is treated as a baseline. If the single value is a character type, then the value is used as the basis for a "like" or startsWith-type comparison, for example,  {"child.name":"Jo"} would match Joe, John, and so on. For all other types, it serves as the lower bound of a >= comparison, {"minAmount":100.00}. If an array is provided, the values within it are treated as "equals" or "in" values depending upon the element count, for example, {"id":[1, 2, 3]}. If an object is provided, fields named "from" and "to" within the object, will serve as lower and/or upper bounds for a range-based query, for example, {"id":{"from":0,"to":100}}, a field named "singleValue" can be used to follow the single value pattern discussed above, a field named "in" can be used to follow the array pattern discussed above, or a field named "fieldPath" can be used to specify the path of a related field. Additionally, a field named "caseInsensitive" can be used to enable case-insensitive querying of character-based fields and a field named "invert" can be used to invert a predicate (that is as a NOT). Combining of criteria in "and" and "or" blocks is supported by providing specially named properties with names beginning with '"@and"' and '"@or"' with JSON object values. These can be used directly within the body for criteria grouping purposes, and also nested within each other. When using multiple @and/@or groupings within a given object, take care to suffix them with additional characters (that is '"@and1"', '"@and2"', and so on) to ensure that they are uniquely named since any duplicates will be eliminated.
orderBy	NA	string (query)	A comma-delimited list of fields used to determine result ordering or a JSON array of complex sorting criteria. When supplied as strings, names are provided in the same format as the where argument - optionally followed by "asc" (default) or "desc" to control order direction. When supplied as a JSON array, a String fieldName field must be included in the object. Optional String order (asc or desc) and boolean caseInsensitive fields may also be provided.
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.
limit	NA	integer <int32> (query)	Provides a maximum number of records to be returned.
offset	NA	integer <int32> (query)	Provides the zero-based value for the position of the first value to be returned.

Responses

This section describes the Queries for a Quote endpoint responses.

Response Code: 200

The requested record.

The media type is application/json.

Example Value

[
  {
    "created": "2024-05-23T14:41:45.940Z",
    "createdBy": "string",
    "updated": "2024-05-23T14:41:45.940Z",
    "updatedBy": "string",
    "id": <id>,
    "crossReferences": [
      {
        "created": "2024-05-23T14:41:45.940Z",
        "createdBy": "string",
        "updated": "2024-05-23T14:41:45.940Z",
        "updatedBy": "string",
        "id": <id>,
        "key": "string",
        "parentId": <parentId>,
        "value": "string"
      }
    ],
    "currency": "str",
    "deliveryId": "string",
    "deliveryType": "DELIVERY",
    "dropoffAddress": {
      "created": "2024-05-23T14:41:45.940Z",
      "createdBy": "string",
      "updated": "2024-05-23T14:41:45.940Z",
      "updatedBy": "string",
      "id": <id>,
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "address4": "string",
      "addressType": "RESIDENTIAL",
      "apartment": "string",
      "city": "string",
      "country": "string",
      "latitude": 999999999,
      "locationCode": "string",
      "longitude": 999999999,
      "postalCode": "string",
      "state": "string"
    },
    "dropoffAddressId": <dropoffAddressId>,
    "dropoffContact": {
      "created": "2024-05-23T14:41:45.940Z",
      "createdBy": "string",
      "updated": "2024-05-23T14:41:45.940Z",
      "updatedBy": "string",
      "id": <id>,
      "businessName": "string",
      "contactReference": "string",
      "emailAddress": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "phoneNumber": "string",
      "suffix": "string"
    },
    "dropoffContactId": <dropoffContactId>,
    "dropoffDeadline": "2024-05-23T14:41:45.940Z",
    "dropoffEta": "2024-05-23T14:41:45.940Z",
    "dropoffLocationCode": "string",
    "expires": "2024-05-23T14:41:45.940Z",
    "fee": 10000000000000000,
    "pickupAddress": {
      "created": "2024-05-23T14:41:45.940Z",
      "createdBy": "string",
      "updated": "2024-05-23T14:41:45.940Z",
      "updatedBy": "string",
      "id": <id>,
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "address4": "string",
      "addressType": "RESIDENTIAL",
      "apartment": "string",
      "city": "string",
      "country": "string",
      "latitude": 999999999,
      "locationCode": "string",
      "longitude": 999999999,
      "postalCode": "string",
      "state": "string"
    },
    "pickupAddressId": <pickupAddressId>,
    "pickupContact": {
      "created": "2024-05-23T14:41:45.940Z",
      "createdBy": "string",
      "updated": "2024-05-23T14:41:45.940Z",
      "updatedBy": "string",
      "id": <id>,
      "businessName": "string",
      "contactReference": "string",
      "emailAddress": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "phoneNumber": "string",
      "suffix": "string"
    },
    "pickupContactId": <pickupContactId>,
    "pickupDeadline": "2024-05-23T14:41:45.940Z",
    "pickupEta": "2024-05-23T14:41:45.940Z",
    "pickupLocationCode": "string",
    "provider": "string",
    "providerCreated": "2024-05-23T14:41:45.940Z",
    "providerId": "string",
    "providerInstance": "string"
  }
]

Schema — Quote

For more information about the Quote schema, see the Schema — Quote section.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Queries for Quote Records/Count— GET

This section describes the Queries for Quote Records Count endpoint. This service returns a count of records matching the provided criteria.

Method

GET

URL

/api/delivery/v5/quote/count

Allowed Scope(s)

delivery-r
delivery-rw 

Request

This section describes the request parameters.

Table 4-25 Queries for Quote Records Count — Request Parameters

Parameter	Required	Data Type	Description
where	NA	object (query)	A JSON object containing query parameters for filtering results. Fields to be filtered on may be provided in the form of a dot-notated path named for the fields known to this resource, i.e. a delimited field named "child.id" would filter by the entity field of this resource named "child" and that entity has a field named "id". Querying is supported in 3 ways. If a single value is provided, it is treated as a baseline. If the single value is a character type, then the value is used as the basis for a "like" or startsWith-type comparison, for example, {"child.name":"Jo"} would match Joe, John, and so on. For all other types, it serves as the lower bound of a >= comparison, {"minAmount":100.00}. If an array is provided, the values within it are treated as "equals" or "in" values depending upon the element count, for example, {"id":[1, 2, 3]}. If an object is provided, fields named "from" and "to" within the object, will serve as lower and/or upper bounds for a range-based query, for example, {"id":{"from":0,"to":100}}, a field named "singleValue" can be used to follow the single value pattern discussed above, a field named "in" can be used to follow the array pattern discussed above, or a field named "fieldPath" can be used to specify the path of a related field. Additionally, a field named "caseInsensitive" can be used to enable case-insensitive querying of character-based fields and a field named "invert" can be used to invert a predicate (that is as a NOT). Combining of criteria in "and" and "or" blocks is supported by providing specially named properties with names beginning with '"@and"' and '"@or"' with JSON object values. These can be used directly within the body for criteria grouping purposes, and also nested within each other. When using multiple @and/@or groupings within a given object, take care to suffix them with additional characters (that is '"@and1"', '"@and2"', and so on) to ensure that they are uniquely named since any duplicates will be eliminated.

Responses

This section describes the responses of the Queries for Quote Records Count endpoint.

Response Code: 200

The count of the requested records.

The media type is application/json.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Queries for Quote Records by Attributes — GET

This section describes the Queries for Quote Records by Attributes endpoint. This endpoint returns a list of records matching the provided attributes.

Method

GET

URL

/api/delivery/v5/quote/byattributes

Allowed Scope(s)

delivery-r

Request

This section describes the request parameters.

Table 4-26 Queries for Quote Records by Attributes — Request Parameters

Parameter	Required	Data Type	Description
id	NA	integer ($int64) (query)	id
currency	NA	string (query)	currency
deliveryId	NA	string (query)	delivery id
deliveryType	NA	string (query)	delivery type; Available values : DELIVERY, RETURN; Default value: DELIVERY
dropoffAddressId	NA	integer ($int64) (query)	dropoff address ID
dropoffContactId	NA	intege ($int64) (query)	dropoff dontact ID
dropoffDeadline	NA	string ($date-time) (query)	dropoff deadline
dropoffEta	NA	string ($date-time) (query)	dropoff Eta
dropoffLocationCode		string (query)	dropoff location code
expires	NA	string($date-time) (query)	expires
fee	NA	number (query)	fee
pickupAddressId	NA	integer ($int64) (query)	pickup address ID
pickupContactId	NA	integer($int64) (query)	pickup contact ID
pickupDeadline	NA	string($date-time) (query)	pickup deadline
pickupEta	NA	string($date-time) (query)	pickup Eta
pickupLocationCode	NA	string (query)	pickup location code
provider	NA	string (query)	provider
providerCreated	NA	string($date-time) (query)	providerCreated
providerId	NA	string (query)	provider ID
providerInstance	NA	string (query)	provider instance
orderBy	NA	string (quer)y	A comma-delimited list of fields used to determine result ordering or a JSON array of complex sorting criteria. When supplied as strings, names are provided in the same format as the where argument - optionally followed by "asc" (default) or "desc" to control order direction. When supplied as a JSON array, a String fieldName field must be included in the object. Optional String order (asc or desc) and boolean caseInsensitive fields may also be provided.
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.
limit	NA	integer ($int32) (query)	Provides a maximum number of records to be returned.
offset	NA	integer ($int32) (query)	Provides the zero-based value for the position of the first value to be returned.

Responses

This section describes the responses of the Queries for Quote Records by Attributes endpoint.

Response Code: 200

The requested record.

The media type is application/json.

Example Value

[
  {
    "created": "2024-05-23T14:47:57.555Z",
    "createdBy": "string",
    "updated": "2024-05-23T14:47:57.555Z",
    "updatedBy": "string",
    "id": <id>,
    "crossReferences": [
      {
        "created": "2024-05-23T14:47:57.555Z",
        "createdBy": "string",
        "updated": "2024-05-23T14:47:57.555Z",
        "updatedBy": "string",
        "id": <id>,
        "key": "string",
        "parentId": <parentId>,
        "value": "string"
      }
    ],
    "currency": "str",
    "deliveryId": "string",
    "deliveryType": "DELIVERY",
    "dropoffAddress": {
      "created": "2024-05-23T14:47:57.555Z",
      "createdBy": "string",
      "updated": "2024-05-23T14:47:57.555Z",
      "updatedBy": "string",
      "id": <id>,
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "address4": "string",
      "addressType": "RESIDENTIAL",
      "apartment": "string",
      "city": "string",
      "country": "string",
      "latitude": 999999999,
      "locationCode": "string",
      "longitude": 999999999,
      "postalCode": "string",
      "state": "string"
    },
    "dropoffAddressId": 9223372036854776000,
    "dropoffContact": {
      "created": "2024-05-23T14:47:57.555Z",
      "createdBy": "string",
      "updated": "2024-05-23T14:47:57.555Z",
      "updatedBy": "string",
      "id": <id>,
      "businessName": "string",
      "contactReference": "string",
      "emailAddress": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "phoneNumber": "string",
      "suffix": "string"
    },
    "dropoffContactId": <dropoffContactId>,
    "dropoffDeadline": "2024-05-23T14:47:57.555Z",
    "dropoffEta": "2024-05-23T14:47:57.555Z",
    "dropoffLocationCode": "string",
    "expires": "2024-05-23T14:47:57.555Z",
    "fee": 10000000000000000,
    "pickupAddress": {
      "created": "2024-05-23T14:47:57.555Z",
      "createdBy": "string",
      "updated": "2024-05-23T14:47:57.555Z",
      "updatedBy": "string",
      "id": <id>,
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "address4": "string",
      "addressType": "RESIDENTIAL",
      "apartment": "string",
      "city": "string",
      "country": "string",
      "latitude": 999999999,
      "locationCode": "string",
      "longitude": 999999999,
      "postalCode": "string",
      "state": "string"
    },
    "pickupAddressId": <pickupAddressId>,
    "pickupContact": {
      "created": "2024-05-23T14:47:57.555Z",
      "createdBy": "string",
      "updated": "2024-05-23T14:47:57.555Z",
      "updatedBy": "string",
      "id": <id>,
      "businessName": "string",
      "contactReference": "string",
      "emailAddress": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "phoneNumber": "string",
      "suffix": "string"
    },
    "pickupContactId": <pickupContactId>,
    "pickupDeadline": "2024-05-23T14:47:57.555Z",
    "pickupEta": "2024-05-23T14:47:57.555Z",
    "pickupLocationCode": "string",
    "provider": "string",
    "providerCreated": "2024-05-23T14:47:57.555Z",
    "providerId": "string",
    "providerInstance": "string"
  }
]

Schema — Quote

For more information about the Quote schema, see the Schema — Quote section.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Delivery Services

This section describes the Delivery services.

Build a Delivery — POST

This section describes the Build Delivery endpoint. Use the Build Delivery endpoint to create a delivery with the courier provider. This includes but is not limited to: the pickup and dropoff information, package details, scheduling and delivery verification options.

Method

POST

URL

/api/delivery/v5/delivery/build

Allowed Scope(s)

delivery-rw

Request

There are no request parameters for this operation.

The request body e is application/json.

The ModelField request.

Example Value

{
  "deliveryType": "DELIVERY",
  "undeliverableAction": "LEAVE_AT_DOOR",
  "crossReferences": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "deliveryId": "string",
  "dropoffAddress": {
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "latitude": 0,
    "locationCode": "string",
    "longitude": 0,
    "postalCode": "string",
    "state": "string"
  },
  "dropoffContact": {
    "businessName": "string",
    "contactReference": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "phoneNumber": "string",
    "suffix": "string"
  },
  "dropoffDeadline": "2024-11-28T12:22:24.965Z",
  "dropoffNotes": "string",
  "dropoffOptions": {
    "additionalInstructions": "string",
    "barcodeRequired": false,
    "contactRequired": false,
    "minimumAge": 9999,
    "pictureRequired": false,
    "pincode": "string",
    "signatureRequired": false
  },
  "dropoffReady": "2024-11-28T12:22:24.965Z",
  "labelsAttached": false,
  "manifest": [
    {
      "description": "string",
      "height": 9999,
      "identifier": "string",
      "items": [
        {
          "description": "string",
          "identifier": "string",
          "price": 10000000000000000,
          "quantity": 9999
        }
      ],
      "length": 9999,
      "packDimensionCode": "string",
      "totalAmount": 10000000000000000,
      "weight": 10000000000000000,
      "width": 9999
    }
  ],
  "pickupAddress": {
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "latitude": 0,
    "locationCode": "string",
    "longitude": 0,
    "postalCode": "string",
    "state": "string"
  },
  "pickupContact": {
    "businessName": "string",
    "contactReference": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "phoneNumber": "string",
    "suffix": "string"
  },
  "pickupDeadline": "2024-11-28T12:22:24.965Z",
  "pickupNotes": "string",
  "pickupOptions": {
    "additionalInstructions": "string",
    "barcodeRequired": false,
    "contactRequired": false,
    "minimumAge": 9999,
    "pictureRequired": false,
    "pincode": "string",
    "signatureRequired": false
  },
  "pickupReady": "2024-11-28T12:22:24.965Z",
  "provider": "string",
  "quoteId": 9223372036854776000,
  "tip": 10000000000000000,
  "totalValue": 10000000000000000
}

Schema — Delivery Request

The following table describes details of proposed delivery request.

Table 4-27 Delivery Request — Object

Element Name	Required	Data Type	Description
deliveryType	NA	string	The delivery type identifier. Default: DELIVERY; Enum: DELIVERY; RETURN
undeliverableAction	NA	string	Indicates what the courier should do with the packages in the event they are unable to be delivered. Enum: LEAVE_AT_DOOR, RETURN
crossReferences	NA	object	Cross references for the delivery. Intended for use by the retailer as an additional reference stored with the delivery order.
deliveryId	Yes	string (128)	The primary reference ID from the calling system uniquely identifying this delivery. Multiple quotes may be obtained, but only one delivery may be arranged for a given reference ID.
dropoffAddress	Yes	object	An address for a given dropoff location.
dropoffContact	Yes	object	A point of contact for a given dropoff location.
dropoffDeadline	NA	string <date-time>	The time by which the items must be dropped off. Date-time strings are in ISO 8601 timestamp with offset format.
dropoffNotes	NA	string	Notes for the courier at drop-off location.
dropoffOptions	NA	object	Options for customizing required verification.
dropoffReady	NA	string <date-time>	The time at which the items may be dropped off. Date-time strings are in ISO 8601 timestamp with offset format.
labelsAttached	NA	boleean	Indicates whether the package(s) will have a pre-paid shipping label attached when the courier arrives. Default: false Note: Return delivery types have the following limitations with the Uber integration: Labels Attached will always be set to TRUE which indicates that a label will be attached to the package(s).
manifest	Yes	object	The packages to be delivered.
pickupAddress	Yes	object	An address given pickup location.
pickupContact	Yes	object	A point of contact for a given pickup location.
pickupDeadline	NA	string <date-time>	The time by which the items must be picked up. Date-time strings are in ISO 8601 timestamp with offset format.
pickupNotes	NA	string	Notes for the courier at pickup location.
pickupOptions	NA	object	Options for customizing required verification.
pickupReady	NA	string <date-time>	The time at which the items will be ready for pickup. Date-time strings are in ISO 8601 timestamp with offset format.
provider	NA	string (10)	The preferred provider.
quoteId	NA	integer <int64>	The prior quote ID for the delivery, if applicable.
tip	NA	number	The amount of the tip.
totalValue	Yes	number	The total value of the request.

The following table describes the elements of an address for a pickup or delivery.

Table 4-28 Request Address

Element Name	Required	Data Type	Description
address1	Yes	string (254)	The address line 1.
address2	NA	string (254)	The address line 2.
address3	NA	string (254)	The address line 3.
address4	NA	string (254)	The address line 4.
addressType	NA	string	enum: RESIDENTIAL, BUSINESS
apartment	NA	string (254)	The apartment.
city	Yes	string (254)	The city or town.
country	Yes	string (254)	The ISO 3166 country code. Applications can decide whether to use 2 or 3 char codes.
latitude	NA	number	The latitude of the address.
locationCode	NA	string (10)	The location code for the address, if applicable. This must be unique across the retailer's landscape.
longitude	NA	number	The longitude of the address.
postalCode	NA	string (20)	The postal code.
state	NA	string (254)	The ISO 3166 state, province or territory code.

The following table describes the elements of a point of contact for a given pickup or delivery.

Table 4-29 Request Contact

Element Name	Required	Data Type	Description
businessName	NA	string (254)	The business name.
contactReference	NA	string (64)	A reference number for the contact.
emailAddress	NA	string (254)	The email address.
firstName	NA	string (254)	The first (that is, given) name.
lastName	NA	string (254)	The last (that is, family) name.
middleName	NA	string (254)	The middle name.
phoneNumber	Yes	string (50)	The phone number.
suffix	NA	string (254)	A name suffix.

The following table describes the elements of options for customizing required verification.

Table 4-30 Verification Options

Element Name	Required	Data Type	Description
additionalInstructions	NA	string	Additional instructions for the courier at handoff.
barcodeRequired	NA	boolean	Indicates that a barcode scan is required. Default: false
contactRequired	NA	boolean	Indicates that contact is required (that is must NOT be contactless). Default: false
minimumAge	NA	integer <int32>	The minimum age of the recipient. If this value is specified, Uber will reject the request if the age is not between 18 and 25. Note: Return delivery types have the following limitations with the Uber integration: The use of Minimum Age is not supported as drop off verification option.
pictureRequired	NA	boolean	Indicates that a picture is required. Default: false Note: Return delivery types have the following limitations with the Uber integration: Picture Required will always be set to TRUE which requires the courier to take a picture as a drop off verification.
pincode	NA	string	A pincode required for entry at handoff. Note: Return delivery types have the following limitations with the Uber integration: The use of Pincodes are not supported as drop off verification option.
signatureRequired	NA	boolean	Indicates that a signature is required. Default: false

The following table describes the elements of a package of items to be delivered.

Table 4-31 Manifest Package — Object

Element Name	Required	Data Type	Description
description	NA	string (128)	The description of the package.
height	Yes	integer <int32>	The height of the item in centimeters.
identifier	Yes	string (100)	A unique identifier for the package. This value will be considered when producing verification barcodes.
items	NA	object	The items to be delivered.
length	Yes	integer <int32>	The length of the item in centimeters.
packDimensionCode	NA	string	The package dimension code.
totalAmount	NA	number	The combined prices of all items within the package.
weight	Yes	number	The weight of the item in kilograms.
width	Yes	integer <int32>	The width of the item in centimeters.

The following table describes the elements of an individual item within a delivery.

Table 4-32 Item — Object

Element Name	Required	Data Type	Description
description	Yes	string (128)	The description of the item.
identifier	Yes	string (100)	The identifier (UPC, EAN, SKU, and so on) of the item.
price	NA	number	The price of the item.
quantity	Yes	integer <int32>	The quantity of the item.

Responses

This section describes the responses of the Build Delivery endpoint.

Response Code: 200

The result object.

The media type is application/json.

Example Value

{
  "delivery": {
    "created": "2024-11-28T12:33:59.747Z",
    "createdBy": "string",
    "updated": "2024-11-28T12:33:59.747Z",
    "updatedBy": "string",
    "id": <id>,
    "barcodes": [
      {
        "created": "2024-11-28T12:33:59.747Z",
        "createdBy": "string",
        "updated": "2024-11-28T12:33:59.747Z",
        "updatedBy": "string",
        "id": <id>,
        "identifier": "string",
        "parentId": ,
        "type": "CODE39",
        "value": "string"
      }
    ],
    "cancelReasonCode": "string",
    "canceledBy": "string",
    "crossReferences": [
      {
        "created": "2024-11-28T12:33:59.747Z",
        "createdBy": "string",
        "updated": "2024-11-28T12:33:59.747Z",
        "updatedBy": "string",
        "id": <id>,
        "key": "string",
        "parentId": <parentId>,
        "value": "string"
      }
    ],
    "currency": "str",
    "deliveryCancelReason": "COURIER",
    "deliveryId": "string",
    "deliveryType": "DELIVERY",
    "dropoffAddress": {
      "created": "2024-11-28T12:33:59.747Z",
      "createdBy": "string",
      "updated": "2024-11-28T12:33:59.747Z",
      "updatedBy": "string",
      "id": 9223372036854776000,
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "address4": "string",
      "addressType": "RESIDENTIAL",
      "apartment": "string",
      "city": "string",
      "country": "string",
      "latitude": 999999999,
      "locationCode": "string",
      "longitude": 999999999,
      "postalCode": "string",
      "state": "string"
    },
    "dropoffAddressId": 9223372036854776000,
    "dropoffContact": {
      "created": "2024-11-28T12:33:59.747Z",
      "createdBy": "string",
      "updated": "2024-11-28T12:33:59.747Z",
      "updatedBy": "string",
      "id": <id>,
      "businessName": "string",
      "contactReference": "string",
      "emailAddress": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "phoneNumber": "string",
      "suffix": "string"
    },
    "dropoffContactId": <dropoffContactId>,
    "dropoffDeadline": "2024-11-28T12:33:59.747Z",
    "dropoffEta": "2024-11-28T12:33:59.747Z",
    "dropoffLocationCode": "string",
    "dropoffNotes": "string",
    "dropoffReady": "2024-11-28T12:33:59.747Z",
    "dropoffVerification": {
      "created": "2024-11-28T12:33:59.747Z",
      "createdBy": "string",
      "updated": "2024-11-28T12:33:59.747Z",
      "updatedBy": "string",
      "id": <id>,
      "barcodeRequired": false,
      "barcodes": {
        "additionalProp1": "CODE39",
        "additionalProp2": "CODE39",
        "additionalProp3": "CODE39"
      },
      "contactRequired": false,
      "courierNotes": "string",
      "identificationVerified": true,
      "minimumAge": 9999,
      "pictureRequired": false,
      "pictureURL": "string",
      "signatureRequired": false,
      "signatureURL": "string"
    },
    "dropoffVerificationId": <dropoffVerificationId>,
    "errorCount": 9999,
    "fee": 10000000000000000,
    "labelsAttached": false,
    "manifest": [
      {
        "created": "2024-11-28T12:33:59.747Z",
        "createdBy": "string",
        "updated": "2024-11-28T12:33:59.747Z",
        "updatedBy": "string",
        "id": <id>,
        "description": "string",
        "height": 9999,
        "identifier": "string",
        "items": [
          {
            "created": "2024-11-28T12:33:59.747Z",
            "createdBy": "string",
            "updated": "2024-11-28T12:33:59.747Z",
            "updatedBy": "string",
            "id": <id>,
            "description": "string",
            "identifier": "string",
            "parentId": <parentId>,
            "price": 10000000000000000,
            "quantity": 9999
          }
        ],
        "length": 9999,
        "packDimensionCode": "string",
        "parentId": <parentId>,
        "totalAmount": 10000000000000000,
        "weight": 10000000000000000,
        "width": 9999
      }
    ],
    "manifestSize": 9999,
    "pickupAddress": {
      "created": "2024-11-28T12:33:59.747Z",
      "createdBy": "string",
      "updated": "2024-11-28T12:33:59.747Z",
      "updatedBy": "string",
      "id": <id>,
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "address4": "string",
      "addressType": "RESIDENTIAL",
      "apartment": "string",
      "city": "string",
      "country": "string",
      "latitude": 999999999,
      "locationCode": "string",
      "longitude": 999999999,
      "postalCode": "string",
      "state": "string"
    },
    "pickupAddressId": <pickupAddressId>,
    "pickupContact": {
      "created": "2024-11-28T12:33:59.747Z",
      "createdBy": "string",
      "updated": "2024-11-28T12:33:59.747Z",
      "updatedBy": "string",
      "id": <id>,
      "businessName": "string",
      "contactReference": "string",
      "emailAddress": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "phoneNumber": "string",
      "suffix": "string"
    },
    "pickupContactId": <pickupContactId>,
    "pickupDeadline": "2024-11-28T12:33:59.747Z",
    "pickupEta": "2024-11-28T12:33:59.747Z",
    "pickupLocationCode": "string",
    "pickupNotes": "string",
    "pickupReady": "2024-11-28T12:33:59.747Z",
    "pickupVerification": {
      "created": "2024-11-28T12:33:59.747Z",
      "createdBy": "string",
      "updated": "2024-11-28T12:33:59.747Z",
      "updatedBy": "string",
      "id": <id>,
      "barcodeRequired": false,
      "barcodes": {
        "additionalProp1": "CODE39",
        "additionalProp2": "CODE39",
        "additionalProp3": "CODE39"
      },
      "contactRequired": false,
      "courierNotes": "string",
      "identificationVerified": true,
      "minimumAge": 9999,
      "pictureRequired": false,
      "pictureURL": "string",
      "signatureRequired": false,
      "signatureURL": "string"
    },
    "pickupVerificationId": 9223372036854776000,
    "provider": "string",
    "providerCreated": "2024-11-28T12:33:59.747Z",
    "providerId": "string",
    "providerInstance": "string",
    "returnTripId": 9223372036854776000,
    "status": "CREATED",
    "statusHistory": [
      {
        "created": "2024-11-28T12:33:59.747Z",
        "createdBy": "string",
        "updated": "2024-11-28T12:33:59.747Z",
        "updatedBy": "string",
        "id": <id>,
        "newStatus": "CREATED",
        "parentId": 9223372036854776000,
        "priorStatus": "CREATED"
      }
    ],
    "tip": 10000000000000000,
    "totalValue": 10000000000000000,
    "trackingURL": "string",
    "undeliverableInfo": {
      "created": "2024-11-28T12:33:59.747Z",
      "createdBy": "string",
      "updated": "2024-11-28T12:33:59.747Z",
      "updatedBy": "string",
      "id": <id>,
      "moreInfo": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "reason": "string",
      "undeliverableAction": "LEAVE_AT_DOOR"
    },
    "undeliverableInfoId": 9223372036854776000
  },
  "errors": [
    {
      "errorCode": 2147483647,
      "errorMessage": "string",
      "moreInfo": {
        "code": "string",
        "description": "string"
      },
      "provider": "string"
    }
  ]
}

Schema — Delivery Response

Schema — Delivery Response

The following table describes the elements of a response to a delivery request.

Table 4-33 Delivery Response — Object

Element Name	Required	Data Type	Description
delivery	NA	object	A delivery from a delivery provider.
errors	NA	object	A collection of errors from providers which could not service the request.

The following table describes the elements of a delivery from a delivery provider.

Table 4-34 Delivery — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was last created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
barcodes	NA	object	A list of barcodes associated with the delivery.
cancelReasonCode	NA	string(40)	The user cancel reason code.
canceledBy	NA	string (256)	The ID of the caller who requested cancelation of the delivery (if applicable).
crossReferences	NA	object	A list of cross-references for the delivery.
currency	NA	string (3)	The currency code associated with the delivery.
deliveryCancelReason	NA	string	The delivery cancel reason. Enum: COURIER, PROVIDER, CUSTOMER
deliveryId	Yes	string (128)	The primary reference ID from the calling system uniquely identifying this delivery.
deliveryType	Yes	string	The delivery type identifier. Default: DELIVERY; Enum: DELIVERY, RETURN
dropoffAddress	NA	object	An address for a given dropoff location.
dropoffAddressId	NA	integer <int64>	NA
dropoffContact	NA	object	A point of contact for a given dropoff location.
dropoffContactId	NA	integer <int64>	NA
dropoffDeadline	NA	string <date-time>	The time by which the order must be dropped off. Date-time strings are in ISO 8601 timestamp with offset format.
dropoffEta	NA	string <date-time>	The time by which the order is expected to be dropped off. Date-time strings are in ISO 8601 timestamp with offset format.
dropoffLocationCode	NA	string(10)	The location code for the dropoff address.
dropoffNotes	NA	string(256)	Notes for the courier at dropoff location.
dropoffReady	NA	string($date-time)	The time at which the items may be dropped off.
dropoffVerification	NA	object	A record indicating verification proof information for a given delivery.
dropoffVerificationId	NA	integer <int64>	NA
errorCount	NA	integer($int32)	The count of failed Provider API calls.
fee	NA	number	The cost of the delivery.
lablesAttached	NA	boolean	Indicates whether the package(s) will have a pre-paid shipping label attached when the courier arrives. Default: false
manifest		object	The packages to be delivered.
manifestSize	NA	integer <int32>	The count of manifest items in the delivery.
pickupAddress	NA	object	An address for a given pickup location.
pickupAddressId	NA	integer <int64>	NA
pickupContact	NA	object	A point of contact for a given pickup location.
pickupContactId	NA	integer <int64>	NA
pickupDeadline	NA	string <date-time>	The time by which the order must be picked up. Date-time strings are in ISO 8601 timestamp with offset format.
pickupEta	NA	string <date-time>	The time by which the order is expected to be picked up. Date-time strings are in ISO 8601 timestamp with offset format.
pickupLocationCode	NA	string (10)	The pickup location code associated with this delivery.
pickupNotes	NA	string(256)	Notes for the courier at pickup location.
pickupReady	NA	string($date-time)	The time at which the items will be ready for pickup.
pickupVerification	NA	object	A record indicating verification proof information for a given delivery.
pickupVerificationId	NA	integer <int64>	NA
provider	Yes	string (10)	The provider of the delivery.
providerCreated	Yes	string <date-time>	The creation timestamp, as indicated by the provider. Date-time strings are in ISO 8601 timestamp with offset format.
providerInstance	Yes	string (20)	The specific instance of the provider of the delivery.
providerlId	Yes	string (128)	The id from the provider of the delivery.
returnTripId	NA	integer($int64)	The return trip id of the delivery.
status	Yes	string	The last known status of the delivery. enum: CREATED, PENDING, ENROUTE_PICKUP, PICKUP_COMPLETE, ENROUTE_DROPOFF, DROPOFF_COMPLETE, CANCELED, RETURNED, ERROR, ENROUTE_RETURN
statusHistory	NA	object	Status history for the delivery.
tip	NA	number	The amount of the tip.
totalValue	NA	number	The total value of the request.
trackingURL	NA	string	The tracking URL for the delivery.
undeliverableInfo	NA	object	A record indicating details about a delivery that could not be completed.
undeliverableInfoId	NA	integer <int64>	NA

The following table describes elements of a barcode for a delivery package.

Table 4-35 Manifest Package Barcode — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	NA
identifier	Yes	string (100)	The identifier for the manifest entry associated with this barcode.
parentId	NA	integer <int64>	NA
type	NA	string	enum: CODE39, CODE39_FULL_ASCII, CODE128, QR
value	Yes	string (100)	The the value of the barcode.

The following table describes the elements of a cross reference record.

Table 4-36 Delivery Cross References — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
key	Yes	string (128)	The identifier for the cross reference.
parentId	NA	integer <int64>	Parent ID
value	Yes	string (128)	The the value of the cross reference.

The following table describes the elements of an address for a given pickup or delivery.

Table 4-37 Address

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
address1	Yes	string (254)	The address line 1.
address2	NA	string (254)	The address line 2.
address3	NA	string (254)	The address line 3.
address4	NA	string (254)	The address line 4.
addressType	NA	string	enum: RESIDENTIAL, BUSINESS
apartment	NA	string (254)	The apartment.
city	Yes	string (254)	The city or town.
country	Yes	string (254)	The ISO 3166 country code. Applications can decide whether to use 2 or 3 char codes.
latitude	NA	number	The latitude of the address.
locationCode	NA	string (10)	The location code for the address, if applicable. This must be unique across the retailer's landscape.
longitude	NA	number	The longitude of the address.
postalCode	NA	string (20)	The postal code.
state	NA	string (254)	The ISO 3166 state, province or territory code.

The following table describes the elements of a point of contact for a given pickup or delivery.

Table 4-38 Contact

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <$date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
businessName	NA	string (254)	The business name.
contactReference	NA	string (64)	A reference number for the contact.
emailAddress	NA	string (254)	The email address.
firstName	NA	string (254)	The first (that is, given) name.
lastName	NA	string (254)	The last (that is, family) name.
middleName	NA	string (254)	The middle name.
phoneNumber	Yes	string (50)	The phone number.
suffix	NA	string (254)	A name suffix.

The following table describes a record indicating details for a delivery package.

Table 4-39 Manifest Package Detail — Object

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
description	NA	string(256)	The description of the package.
height	NA	integer($int32)	The height of the item in centimeters.
identifier	Yes	string(100)	The identifier for the manifest package entry.
items	NA	object	The packages to be delivered.
length	NA	integer($int32)	The length of the item in centimeters.
packDimensionCode	NA	string(15)	The package dimension code.
parentId	NA	integer($int64)	The parent ID.
totalAmount	NA	number	The combined prices of all items within the package.
weight	NA	number	The weight of the item in kilograms.
width	NA	integer($int32)	The width of the item in centimeters.

The following table describes a record indicating details for an item in the delivery package.

Table 4-40 Manifest Item Detail — Object

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
description	NA	string(256)	The description of the item.
height	NA	integer($int32)	The height of the item in centimeters.
identifier	Yes	string(100)	The identifier for the item entry.
parentId	NA	integer($int64)	The parent ID.
price	NA	number	The price of the item.
quantity	NA	integer($int32)	The quantity of the item.

The following table describes elements of a record indicating verification proof information for a given delivery.

Table 4-41 Delivery Verification Proof — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
barcodeRequired	NA	boolean	Indicates that a barcode scan is required. Default: false
barcodes	NA	string	Barcode values and types that were scanned. Enum: CODE39, CODE39_FULL_ASCII, CODE128, QR
contactRequired	NA	boolean	Indicates that contact is required (that is, must NOT be contactless). Default: false
courierNotes	NA	string (2000)	Additional notes pertaining to proof of handoff.
identificationVerified	NA	boolean	Indicates that identification was successfully verified.
minimumAge	NA	integer($int32)	The minimum age of the recipient.
pictureRequired	NA	boolean	Indicates that a picture is required. Default: false
pictureURL	NA	string	The URL for the picture image.
signatureRequired	NA	boolean	Indicates that a signature is required. Default: false
signatureURL	NA	string	The URL for the signature image.

The following table describes elements of a record indicating a status transition for a delivery.

Table 4-42 Delivery Status History — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
newStatus	Yes	string	The new status of the delivery. Enum: CREATED, PENDING, ENROUTE_PICKUP, PICKUP_COMPLETE, ENROUTE_DROPOFF, DROPOFF_COMPLETE, CANCELED, RETURNED, ERROR, ENROUTE_RETURN
parentId	NA	integer <int64>	Parent ID
priorStatus	Yes	string	The prior status of the delivery. Enum: CREATED, PENDING, ENROUTE_PICKUP, PICKUP_COMPLETE, ENROUTE_DROPOFF, DROPOFF_COMPLETE, CANCELED, RETURNED, ERROR, ENROUTE_RETURN

The following table describes elements of a record indicating details about a delivery that could not be completed.

Table 4-43 Delivery Undeliverable Information — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
moreInfo	NA	string	Any additional provider-specific information which might be available.
reason	NA	string (2000)	The reason the delivery was undeliverable.
undeliverableAction	NA	string	Indicates what the courier should do with the packages in the event they are unable to be delivered. Enum: DISCARD, LEAVE_AT_DOOR, RETURN

The following table describes elements of a container for an error from a provider.

Table 4-44 Provider Error — Object

Element Name	Required	Data Type	Description
errorCode	NA	integer <int32>	A numeric error indicating the type of error.
errorMessage	NA	string	An unlocalized message indicating details about the error.
moreInfo	NA	object	An object containing provider-specific details pertaining to an error.
provider	Yes	string	The provider associated with the error.

The following table describes elements of an object containing provider-specific details pertaining to an error.

Table 4-45 More Error Information — Object

Element Name	Required	Data Type	Description
code	NA	string	A code describing the error.
description	NA	string	An unlocalizable description describing the error.

Response Code: 204

No providers were eligible to service this request.

Response Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

For more information about the Mapper Error Data schema, see the Schema — Mapper Error Data section.

Response Code: 404

Provided quote ID or associated provider could not be found.

Response Code: 409

Provided delivery ID already exists.

Response Code: 424

No providers could service this request.

The media type is application/json.

Example Value

[
  {
    "errorCode": 2147483647,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "provider": "string"
  }
]

Schema — Provider Error

For more information about the Provider Error schema, see the Schema — Provider Error section.

Response Code: 500

The request failed.

Cancel a Delivery — POST

This section describes the Cancel a Delivery endpoint. This service attempts to cancel the delivery, contacting the provider to do so.

Method

POST

URL

/api/delivery/v5/delivery/cancel

Allowed Scope(s)

delivery-rw

Request

This section describes the request parameters.

Table 4-46 Cancel a Delivery — Request Parameters

Parameter	Required	Data Type	Description
id	NA	integer <int64> (query)	The identifier of the delivery.
deliveryId	NA	string (query)	The primary reference ID from the originating system uniquely identifying this delivery.
cancelReasonCode	NA	string (query)	The user cancel reason code.

Responses

This section describes the responses of the Cancel a Delivery endpoint.

Response Code: 200

The result object.

The media type is application/json.

Example Value

{
  "created": "2024-11-28T13:11:28.299Z",
  "createdBy": "string",
  "updated": "2024-11-28T13:11:28.299Z",
  "updatedBy": "string",
  "id": <id>,
  "barcodes": [
    {
      "created": "2024-11-28T13:11:28.299Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:11:28.299Z",
      "updatedBy": "string",
      "id": <id>,
      "identifier": "string",
      "parentId": <parentId>,
      "type": "CODE39",
      "value": "string"
    }
  ],
  "cancelReasonCode": "string",
  "canceledBy": "string",
  "crossReferences": [
    {
      "created": "2024-11-28T13:11:28.299Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:11:28.299Z",
      "updatedBy": "string",
      "id": <id>,
      "key": "string",
      "parentId": <parentId>,
      "value": "string"
    }
  ],
  "currency": "str",
  "deliveryCancelReason": "COURIER",
  "deliveryId": "string",
  "deliveryType": "DELIVERY",
  "dropoffAddress": {
    "created": "2024-11-28T13:11:28.299Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:11:28.299Z",
    "updatedBy": "string",
    "id": <id>,
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "latitude": 999999999,
    "locationCode": "string",
    "longitude": 999999999,
    "postalCode": "string",
    "state": "string"
  },
  "dropoffAddressId": <dropoffAddressId>,
  "dropoffContact": {
    "created": "2024-11-28T13:11:28.299Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:11:28.299Z",
    "updatedBy": "string",
    "id": <id>,
    "businessName": "string",
    "contactReference": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "phoneNumber": "string",
    "suffix": "string"
  },
  "dropoffContactId": <dropoffContactId>,
  "dropoffDeadline": "2024-11-28T13:11:28.299Z",
  "dropoffEta": "2024-11-28T13:11:28.299Z",
  "dropoffLocationCode": "string",
  "dropoffNotes": "string",
  "dropoffReady": "2024-11-28T13:11:28.299Z",
  "dropoffVerification": {
    "created": "2024-11-28T13:11:28.299Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:11:28.299Z",
    "updatedBy": "string",
    "id": <id>,
    "barcodeRequired": false,
    "barcodes": {
      "additionalProp1": "CODE39",
      "additionalProp2": "CODE39",
      "additionalProp3": "CODE39"
    },
    "contactRequired": false,
    "courierNotes": "string",
    "identificationVerified": true,
    "minimumAge": 9999,
    "pictureRequired": false,
    "pictureURL": "string",
    "signatureRequired": false,
    "signatureURL": "string"
  },
  "dropoffVerificationId": <dropoffVerificationId>,
  "errorCount": 9999,
  "fee": 10000000000000000,
  "labelsAttached": false,
  "manifest": [
    {
      "created": "2024-11-28T13:11:28.299Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:11:28.299Z",
      "updatedBy": "string",
      "id": <id>,
      "description": "string",
      "height": 9999,
      "identifier": "string",
      "items": [
        {
          "created": "2024-11-28T13:11:28.299Z",
          "createdBy": "string",
          "updated": "2024-11-28T13:11:28.299Z",
          "updatedBy": "string",
          "id": <id>,
          "description": "string",
          "identifier": "string",
          "parentId": <parentId>,
          "price": 10000000000000000,
          "quantity": 9999
        }
      ],
      "length": 9999,
      "packDimensionCode": "string",
      "parentId": <parentId>,
      "totalAmount": 10000000000000000,
      "weight": 10000000000000000,
      "width": 9999
    }
  ],
  "manifestSize": 9999,
  "pickupAddress": {
    "created": "2024-11-28T13:11:28.299Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:11:28.299Z",
    "updatedBy": "string",
    "id": <id>,
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "latitude": 999999999,
    "locationCode": "string",
    "longitude": 999999999,
    "postalCode": "string",
    "state": "string"
  },
  "pickupAddressId": <pickAddressId>,
  "pickupContact": {
    "created": "2024-11-28T13:11:28.299Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:11:28.299Z",
    "updatedBy": "string",
    "id": <id>,
    "businessName": "string",
    "contactReference": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "phoneNumber": "string",
    "suffix": "string"
  },
  "pickupContactId": <pickupContactId>,
  "pickupDeadline": "2024-11-28T13:11:28.299Z",
  "pickupEta": "2024-11-28T13:11:28.299Z",
  "pickupLocationCode": "string",
  "pickupNotes": "string",
  "pickupReady": "2024-11-28T13:11:28.299Z",
  "pickupVerification": {
    "created": "2024-11-28T13:11:28.299Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:11:28.299Z",
    "updatedBy": "string",
    "id": <id>,
    "barcodeRequired": false,
    "barcodes": {
      "additionalProp1": "CODE39",
      "additionalProp2": "CODE39",
      "additionalProp3": "CODE39"
    },
    "contactRequired": false,
    "courierNotes": "string",
    "identificationVerified": true,
    "minimumAge": 9999,
    "pictureRequired": false,
    "pictureURL": "string",
    "signatureRequired": false,
    "signatureURL": "string"
  },
  "pickupVerificationId": <pickupVerificationId>,
  "provider": "string",
  "providerCreated": "2024-11-28T13:11:28.299Z",
  "providerId": "string",
  "providerInstance": "string",
  "returnTripId": 9223372036854776000,
  "status": "CREATED",
  "statusHistory": [
    {
      "created": "2024-11-28T13:11:28.299Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:11:28.299Z",
      "updatedBy": "string",
      "id": <id>,
      "newStatus": "CREATED",
      "parentId": <parentId>,
      "priorStatus": "CREATED"
    }
  ],
  "tip": 10000000000000000,
  "totalValue": 10000000000000000,
  "trackingURL": "string",
  "undeliverableInfo": {
    "created": "2024-11-28T13:11:28.299Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:11:28.299Z",
    "updatedBy": "string",
    "id": <id>,
    "moreInfo": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "reason": "string",
    "undeliverableAction": "LEAVE_AT_DOOR"
  },
  "undeliverableInfoId": <undeliverableInfoId>
}

Schema — Delivery

Schema — Delivery

The following table describes the elements of a delivery from a delivery provider.

Table 4-47 Delivery — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
barcodes	NA	object	A list of barcodes associated with the delivery.
cancelReasonCode	NA	string(40)	The user cancel reason code.
canceledBy	NA	string (256)	The ID of the caller who requested cancelation of the delivery (if applicable).
crossReferences	NA	object	A list of cross-references for the delivery.
currency	NA	string (3)	The currency code associated with the delivery.
deliveryCancelReason	NA	string	The delivery cancel reason. Enum: COURIER, PROVIDER, CUSTOMER
deliveryId	Yes	string (128)	The primary reference ID from the calling system uniquely identifying this delivery.
deliveryType	Yes	string	The delivery identifier. Default: DELIVERY; Enum: DELIVERY, RETURN
dropoffAddress	NA	object	An address for a given dropoff location.
dropoffAddressId	NA	integer <int64>	NA
dropoffContact	NA	object	A point of contact for a given dropoff location.
dropoffContactId	NA	integer <int64>	NA
dropoffDeadline	NA	string <date-time>	The time by which the order must be dropped off. Date-time strings are in ISO 8601 timestamp with offset format.
dropoffEta	NA	string <date-time>	The time by which the order is expected to be dropped off. Date-time strings are in ISO 8601 timestamp with offset format.
dropoffLocationCode	NA	string(10)	The location code for the dropoff address.
dropoffNotes	NA	string(256)	Notes for the courier at dropoff location.
dropoffReady	NA	string($date-time)	The time at which the items may be dropped off.
dropoffVerification	NA	object	A record indicating verification proof information for a given delivery.
dropoffVerificationId	NA	integer <int64>	NA
errorCount	NA	integer($int32)	The count of failed Provider API calls.
fee	NA	number	The cost of the delivery.
labelsAttached	NA	boolean	Indicates whether the package(s) will have a pre-paid shipping label attached when the courier arrives. Default: false Note: Return delivery types have the following limitations with the Uber integration: Labels Attached will always be set to TRUE which indicates that a label will be attached to the package(s).
manifest	NA	object	The packages to be delivered.
manifestSize	NA	integer <int32>	The count of manifest items in the delivery.
pickupAddress	NA	object	An address for a given pickup location.
pickupAddressId	NA	integer <int64>	NA
pickupContact	NA	object	A point of contact for a given pickup location.
pickupContactId	NA	integer <int64>	NA
pickupDeadline	NA	string <date-time>	The time by which the order must be picked up. Date-time strings are in ISO 8601 timestamp with offset format.
pickupEta	NA	string <date-time>	The time by which the order is expected to be picked up. Date-time strings are in ISO 8601 timestamp with offset format.
pickupLocationCode	NA	string (10)	The pickup location code associated with this delivery.
pickupNotes	NA	string(256)	Notes for the courier at pickup location.
pickupReady	NA	string($date-time)	The time at which the items will be ready for pickup.
pickupVerification	NA	object	A record indicating verification proof information for a given delivery.
pickupVerificationId	NA	integer <int64>	NA
provider	Yes	string (10)	The provider of the delivery.
providerCreated	Yes	string <date-time>	The creation timestamp, as indicated by the provider. Date-time strings are in ISO 8601 timestamp with offset format.
providerInstance	Yes	string (20)	The specific instance of the provider of the delivery.
providerlId	Yes	string (128)	The id from the provider of the delivery.
returnTripId	NA	integer($int64)	The return trip id of the delivery.
status	Yes	string	The last known status of the delivery. enum: CREATED, PENDING, ENROUTE_PICKUP, PICKUP_COMPLETE, ENROUTE_DROPOFF, DROPOFF_COMPLETE, CANCELED, RETURNED, ERROR, ENROUTE_RETURN
statusHistory	NA	object	Status history for the delivery.
tip	NA	number	The amount of the tip.
totalValue	NA	number	The total value of the request.
trackingURL	NA	string	The tracking URL for the delivery.
undeliverableInfo	NA	object	A record indicating details about a delivery that could not be completed.
undeliverableInfoId	NA	integer <int64>	NA

The following table describes elements of a barcode for a delivery package.

Table 4-48 Manifest Package Barcode — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	NA
identifier	Yes	string (100)	The identifier for the manifest entry associated with this barcode.
parentId	NA	integer <int64>	NA
type	NA	string	enum: CODE39, CODE39_FULL_ASCII, CODE128, QR
value	Yes	string (100)	The the value of the barcode.

The following table describes the elements of a cross reference record.

Table 4-49 Delivery Cross References — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
key	Yes	string (128)	The identifier for the cross reference.
parentId	NA	integer <int64>	Parent ID
value	Yes	string (128)	The the value of the cross reference.

The following table describes the elements of an address for a given pickup or delivery.

Table 4-50 Address

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
address1	Yes	string (254)	The address line 1.
address2	NA	string (254)	The address line 2.
address3	NA	string (254)	The address line 3.
address4	NA	string (254)	The address line 4.
addressType	NA	string	enum: RESIDENTIAL, BUSINESS
apartment	NA	string (254)	The apartment.
city	Yes	string (254)	The city or town.
country	Yes	string (254)	The ISO 3166 country code. Applications can decide whether to use 2 or 3 char codes.
latitude	NA	number	The latitude of the address.
locationCode	NA	string (10)	The location code for the address, if applicable. This must be unique across the retailer's landscape.
longitude	NA	number	The longitude of the address.
postalCode	NA	string (20)	The postal code.
state	NA	string (254)	The ISO 3166 state, province or territory code.

The following table describes the elements of a point of contact for a given pickup or delivery.

Table 4-51 Contact

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
businessName	NA	string (254)	The business name.
contactReference	NA	string (64)	A reference number for the contact.
emailAddress	NA	string (254)	The email address.
firstName	NA	string (254)	The first (that is, given) name.
lastName	NA	string (254)	The last (that is, family) name.
middleName	NA	string (254)	The middle name.
phoneNumber	Yes	string (50)	The phone number.
suffix	NA	string (254)	A name suffix.

The following table describes elements of a record indicating verification proof information for a given delivery.

Table 4-52 Delivery Verification Proof — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
barcodeRequired	NA	boolean	Indicates that a barcode scan is required. Default: false
barcodes	NA	string	Barcode values and types that were scanned. Enum: CODE39, CODE39_FULL_ASCII, CODE128, QR
contactRequired	NA	boolean	Indicates that contact is required (that is, must NOT be contactless) Default: false
courierNotes	NA	string (2000)	Additional notes pertaining to proof of handoff.
identificationVerified	NA	boolean	Indicates that identification was successfully verified.
minimumAge	NA	integer($int32)	The minimum age of the recipient.
pictureRequired	NA	boolean	Indicates that a picture is required. Default: false
pictureURL	NA	string	The URL for the picture image.
signatureRequired	NA	boolean	Indicates that a signature is required. Default: false
signatureURL	NA	string	The URL for the signature image.

The following table describes elements of a record indicating a status transition for a delivery.

Table 4-53 Manifest Package Detail — Object

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
description	NA	string	The description of the package.
height	NA	integer($int32)	The height of the item in centimeters.
identifier	Yes	string	The identifier for the manifest package entry.
items	NA	object	The packages to be delivered.
length	NA	integer($int32)	The length of the item in centimeters.
packDimensionCode	NA	string(15)	The package dimension code.
parentId	NA	integer($int64)	The parent ID.
totalAmount	NA	number	The combined prices of all items within the package.
weight	NA	number	The weight of the item in kilograms.
width	NA	integer($int32)	The width of the item in centimeters.

The following table describes a record indicating details for an item in the delivery package.

Table 4-54 Manifest Item Detail — Object

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
description	NA	string(256)	The description of the item.
height	NA	integer($int32)	The height of the item in centimeters.
identifier	Yes	string(100)	The identifier for the item entry.
parentId	NA	integer($int64)	The parent ID.
price	NA	number	The price of the item.
quantity	NA	integer($int32)	The quantity of the item.

Table 4-55 Delivery Status History — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
newStatus	Yes	string	The new status of the delivery. Enum: CREATED, PENDING, ENROUTE_PICKUP, PICKUP_COMPLETE, ENROUTE_DROPOFF, DROPOFF_COMPLETE, CANCELED, RETURNED, ERROR, ENROUTE_RETURN
parentId	NA	integer <int64>	Parent ID
priorStatus	Yes	string	The prior status of the delivery. Enum: CREATED, PENDING, ENROUTE_PICKUP, PICKUP_COMPLETE, ENROUTE_DROPOFF, DROPOFF_COMPLETE, CANCELED, RETURNED, ERROR, ENROUTE_RETURN

The following table describes elements of a record indicating details about a delivery that could not be completed.

Table 4-56 Delivery Undeliverable Information — Object

Element Name	Required	Data Type	Description
created	NA	string <date-time>	The timestamp at which the record was created. Date-time strings are in ISO 8601 timestamp with offset format.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string <date-time>	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer <int64>	ID
moreInfo	NA	string	Any additional provider-specific information which might be available.
reason	NA	string (2000)	The reason the delivery was undeliverable.
undeliverableAction	NA	string	Indicates what the courier should do with the packages in the event they are unable to be delivered. Enum: DISCARD, LEAVE_AT_DOOR, RETURN

Response Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

For more information about the schema Mapper Error Data, see the Schema — Mapper Error Data section.

Response Code: 404

Provided delivery ID could not be found.

Response Code: 409

Provided delivery ID is not in a status eligible for cancellation.

Response Code: 424

No provider could service this request.

The media type is application/json.

Example Value

[
  {
    "errorCode": 2147483647,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "provider": "string"
  }
]

Schema — Provider Error

For more information about the Provider Error Schema, see the Schema — Provider Error section.

Response Code: 500

The request failed.

Get the Current Status of a Delivery — GET

This section describes the Get the Current Status of a Delivery endpoint. This service retrieves the latest status of the delivery, calling the provider if appropriate. It will also retrieve the most current details about delivery in case of updates to the delivery schedule, notes, or other.

Method

GET

URL

/api/delivery/v5/delivery/status

Allowed Scope(s)

delivery-r
delivery-rw 

Request

This section describes the request parameters.

Table 4-57 Get the Current Status of a Delivery — Request Parameters

Parameter	Required	Data Type	Description
id	NA	integer <int64> (query)	The identifier of the delivery.
deliveryId	NA	string (query)	The primary reference ID from the originating system uniquely identifying this delivery.

Responses

This section describes responses of the Get the Current Status of a Delivery endpoint.

Response Code: 200

The result object.

The media type is application/json.

Example Value

{
  "created": "2024-11-28T13:28:27.877Z",
  "createdBy": "string",
  "updated": "2024-11-28T13:28:27.877Z",
  "updatedBy": "string",
  "id": <id>,
  "barcodes": [
    {
      "created": "2024-11-28T13:28:27.877Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:28:27.877Z",
      "updatedBy": "string",
      "id": <id>,
      "identifier": "string",
      "parentId": <parentId>,
      "type": "CODE39",
      "value": "string"
    }
  ],
  "cancelReasonCode": "string",
  "canceledBy": "string",
  "crossReferences": [
    {
      "created": "2024-11-28T13:28:27.877Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:28:27.877Z",
      "updatedBy": "string",
      "id": <id>,
      "key": "string",
      "parentId": <parentId>,
      "value": "string"
    }
  ],
  "currency": "str",
  "deliveryCancelReason": "COURIER",
  "deliveryId": "string",
  "deliveryType": "DELIVERY",
  "dropoffAddress": {
    "created": "2024-11-28T13:28:27.877Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:28:27.877Z",
    "updatedBy": "string",
    "id": <id>,
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "latitude": 999999999,
    "locationCode": "string",
    "longitude": 999999999,
    "postalCode": "string",
    "state": "string"
  },
  "dropoffAddressId": <dropoffAddressId>,
  "dropoffContact": {
    "created": "2024-11-28T13:28:27.877Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:28:27.877Z",
    "updatedBy": "string",
    "id": <id>,
    "businessName": "string",
    "contactReference": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "phoneNumber": "string",
    "suffix": "string"
  },
  "dropoffContactId": <dropoffContactId>,
  "dropoffDeadline": "2024-11-28T13:28:27.877Z",
  "dropoffEta": "2024-11-28T13:28:27.877Z",
  "dropoffLocationCode": "string",
  "dropoffNotes": "string",
  "dropoffReady": "2024-11-28T13:28:27.877Z",
  "dropoffVerification": {
    "created": "2024-11-28T13:28:27.877Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:28:27.877Z",
    "updatedBy": "string",
    "id": <id>,
    "barcodeRequired": false,
    "barcodes": {
      "additionalProp1": "CODE39",
      "additionalProp2": "CODE39",
      "additionalProp3": "CODE39"
    },
    "contactRequired": false,
    "courierNotes": "string",
    "identificationVerified": true,
    "minimumAge": 9999,
    "pictureRequired": false,
    "pictureURL": "string",
    "signatureRequired": false,
    "signatureURL": "string"
  },
  "dropoffVerificationId": <dropoffVerificationId>,
  "errorCount": 9999,
  "fee": 10000000000000000,
  "labelsAttached": false,
  "manifest": [
    {
      "created": "2024-11-28T13:28:27.877Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:28:27.877Z",
      "updatedBy": "string",
      "id": <id>,
      "description": "string",
      "height": 9999,
      "identifier": "string",
      "items": [
        {
          "created": "2024-11-28T13:28:27.877Z",
          "createdBy": "string",
          "updated": "2024-11-28T13:28:27.877Z",
          "updatedBy": "string",
          "id": <id>,
          "description": "string",
          "identifier": "string",
          "parentId": 9223372036854776000,
          "price": 10000000000000000,
          "quantity": 9999
        }
      ],
      "length": 9999,
      "packDimensionCode": "string",
      "parentId": <parentId>,
      "totalAmount": 10000000000000000,
      "weight": 10000000000000000,
      "width": 9999
    }
  ],
  "manifestSize": 9999,
  "pickupAddress": {
    "created": "2024-11-28T13:28:27.877Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:28:27.877Z",
    "updatedBy": "string",
    "id": <id>,
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "latitude": 999999999,
    "locationCode": "string",
    "longitude": 999999999,
    "postalCode": "string",
    "state": "string"
  },
  "pickupAddressId": <pickupAddressId>,
  "pickupContact": {
    "created": "2024-11-28T13:28:27.877Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:28:27.877Z",
    "updatedBy": "string",
    "id": <id>,
    "businessName": "string",
    "contactReference": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "phoneNumber": "string",
    "suffix": "string"
  },
  "pickupContactId": <pickupContactId>,
  "pickupDeadline": "2024-11-28T13:28:27.877Z",
  "pickupEta": "2024-11-28T13:28:27.877Z",
  "pickupLocationCode": "string",
  "pickupNotes": "string",
  "pickupReady": "2024-11-28T13:28:27.877Z",
  "pickupVerification": {
    "created": "2024-11-28T13:28:27.877Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:28:27.877Z",
    "updatedBy": "string",
    "id": <id>,
    "barcodeRequired": false,
    "barcodes": {
      "additionalProp1": "CODE39",
      "additionalProp2": "CODE39",
      "additionalProp3": "CODE39"
    },
    "contactRequired": false,
    "courierNotes": "string",
    "identificationVerified": true,
    "minimumAge": 9999,
    "pictureRequired": false,
    "pictureURL": "string",
    "signatureRequired": false,
    "signatureURL": "string"
  },
  "pickupVerificationId": <pickupVerificationId>,
  "provider": "string",
  "providerCreated": "2024-11-28T13:28:27.877Z",
  "providerId": "string",
  "providerInstance": "string",
  "returnTripId": 9223372036854776000,
  "status": "CREATED",
  "statusHistory": [
    {
      "created": "2024-11-28T13:28:27.877Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:28:27.877Z",
      "updatedBy": "string",
      "id": <id>,
      "newStatus": "CREATED",
      "parentId": <parentId>,
      "priorStatus": "CREATED"
    }
  ],
  "tip": 10000000000000000,
  "totalValue": 10000000000000000,
  "trackingURL": "string",
  "undeliverableInfo": {
    "created": "2024-11-28T13:28:27.877Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:28:27.877Z",
    "updatedBy": "string",
    "id": <id>,
    "moreInfo": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "reason": "string",
    "undeliverableAction": "LEAVE_AT_DOOR"
  },
  "undeliverableInfoId": <undeliverableInfoId>
}

Schema — Delivery

For more information about the Delivery schema, see the Schema — Delivery section.

Response Code: 400

The provided input is invalid

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

For more information about the schema Mapper Error Data, see the Schema — Mapper Error Data section.

Response Code: 404

Provided delivery ID could not be found.

Response Code: 424

No providers could service this request. A collection of related ProviderError objects will be returned.

Example Value

[
  {
    "errorCode": 2147483647,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "provider": "string"
  }
]

Schema — Provider Error

For more information about the Provider Error schema, see the Schema — Provider Error section.

Response Code: 500

The request failed.

Get a Delivery — GET

This section describes the Get a Delivery endpoint. This service retrieves the details of a delivery as stored in the database. It will not call out to the provider to retrieve any new updates.

Method

GET

URL

/api/delivery/v5/delivery/{id}

Allowed Scope(s)

delivery-r
delivery-rw 

Request

This section describes the request parameters.

Table 4-58 Get a Delivery — Request Parameters

Parameter	Required	Data Type	Description
id	Yes	integer <int64> (path)	The identifier of the delivery.
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.

Responses

This section describes the responses of the Get a Delivery endpoint.

Response Code: 200

The requested record.

The media type is application/json.

Example Value

{
  "created": "2024-11-28T13:39:37.057Z",
  "createdBy": "string",
  "updated": "2024-11-28T13:39:37.057Z",
  "updatedBy": "string",
  "id": <id>,
  "barcodes": [
    {
      "created": "2024-11-28T13:39:37.057Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:39:37.057Z",
      "updatedBy": "string",
      "id": <Id>,
      "identifier": "string",
      "parentId": <parentId>,
      "type": "CODE39",
      "value": "string"
    }
  ],
  "cancelReasonCode": "string",
  "canceledBy": "string",
  "crossReferences": [
    {
      "created": "2024-11-28T13:39:37.057Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:39:37.057Z",
      "updatedBy": "string",
      "id": <id>,
      "key": "string",
      "parentId": <parentId>,
      "value": "string"
    }
  ],
  "currency": "str",
  "deliveryCancelReason": "COURIER",
  "deliveryId": "string",
  "deliveryType": "DELIVERY",
  "dropoffAddress": {
    "created": "2024-11-28T13:39:37.058Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:39:37.058Z",
    "updatedBy": "string",
    "id": <id>,
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "latitude": 999999999,
    "locationCode": "string",
    "longitude": 999999999,
    "postalCode": "string",
    "state": "string"
  },
  "dropoffAddressId": <dropoffAddressId>,
  "dropoffContact": {
    "created": "2024-11-28T13:39:37.058Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:39:37.058Z",
    "updatedBy": "string",
    "id": <id>,
    "businessName": "string",
    "contactReference": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "phoneNumber": "string",
    "suffix": "string"
  },
  "dropoffContactId": <dropoffContactId>,
  "dropoffDeadline": "2024-11-28T13:39:37.058Z",
  "dropoffEta": "2024-11-28T13:39:37.058Z",
  "dropoffLocationCode": "string",
  "dropoffNotes": "string",
  "dropoffReady": "2024-11-28T13:39:37.058Z",
  "dropoffVerification": {
    "created": "2024-11-28T13:39:37.058Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:39:37.058Z",
    "updatedBy": "string",
    "id": <id>,
    "barcodeRequired": false,
    "barcodes": {
      "additionalProp1": "CODE39",
      "additionalProp2": "CODE39",
      "additionalProp3": "CODE39"
    },
    "contactRequired": false,
    "courierNotes": "string",
    "identificationVerified": true,
    "minimumAge": 9999,
    "pictureRequired": false,
    "pictureURL": "string",
    "signatureRequired": false,
    "signatureURL": "string"
  },
  "dropoffVerificationId": <dropoffVerificationId>,
  "errorCount": 9999,
  "fee": 10000000000000000,
  "labelsAttached": false,
  "manifest": [
    {
      "created": "2024-11-28T13:39:37.058Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:39:37.058Z",
      "updatedBy": "string",
      "id": <id>,
      "description": "string",
      "height": 9999,
      "identifier": "string",
      "items": [
        {
          "created": "2024-11-28T13:39:37.058Z",
          "createdBy": "string",
          "updated": "2024-11-28T13:39:37.058Z",
          "updatedBy": "string",
          "id": <id>,
          "description": "string",
          "identifier": "string",
          "parentId": <parentId>,
          "price": 10000000000000000,
          "quantity": 9999
        }
      ],
      "length": 9999,
      "packDimensionCode": "string",
      "parentId": <parentId>,
      "totalAmount": 10000000000000000,
      "weight": 10000000000000000,
      "width": 9999
    }
  ],
  "manifestSize": 9999,
  "pickupAddress": {
    "created": "2024-11-28T13:39:37.058Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:39:37.058Z",
    "updatedBy": "string",
    "id": <id>,
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "latitude": 999999999,
    "locationCode": "string",
    "longitude": 999999999,
    "postalCode": "string",
    "state": "string"
  },
  "pickupAddressId": <pickupAddressId>,
  "pickupContact": {
    "created": "2024-11-28T13:39:37.058Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:39:37.058Z",
    "updatedBy": "string",
    "id": <id>,
    "businessName": "string",
    "contactReference": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "phoneNumber": "string",
    "suffix": "string"
  },
  "pickupContactId": <pickupContactId>,
  "pickupDeadline": "2024-11-28T13:39:37.058Z",
  "pickupEta": "2024-11-28T13:39:37.058Z",
  "pickupLocationCode": "string",
  "pickupNotes": "string",
  "pickupReady": "2024-11-28T13:39:37.058Z",
  "pickupVerification": {
    "created": "2024-11-28T13:39:37.058Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:39:37.058Z",
    "updatedBy": "string",
    "id": <id>,
    "barcodeRequired": false,
    "barcodes": {
      "additionalProp1": "CODE39",
      "additionalProp2": "CODE39",
      "additionalProp3": "CODE39"
    },
    "contactRequired": false,
    "courierNotes": "string",
    "identificationVerified": true,
    "minimumAge": 9999,
    "pictureRequired": false,
    "pictureURL": "string",
    "signatureRequired": false,
    "signatureURL": "string"
  },
  "pickupVerificationId": <pickupVerificationId>,
  "provider": "string",
  "providerCreated": "2024-11-28T13:39:37.058Z",
  "providerId": "string",
  "providerInstance": "string",
  "returnTripId": <returnTripId>,
  "status": "CREATED",
  "statusHistory": [
    {
      "created": "2024-11-28T13:39:37.058Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:39:37.058Z",
      "updatedBy": "string",
      "id": <id>,
      "newStatus": "CREATED",
      "parentId": <parentId>,
      "priorStatus": "CREATED"
    }
  ],
  "tip": 10000000000000000,
  "totalValue": 10000000000000000,
  "trackingURL": "string",
  "undeliverableInfo": {
    "created": "2024-11-28T13:39:37.058Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:39:37.058Z",
    "updatedBy": "string",
    "id": <id>,
    "moreInfo": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "reason": "string",
    "undeliverableAction": "LEAVE_AT_DOOR"
  },
  "undeliverableInfoId": <undeliverableInfoId>
}

Schema — Delivery

For more information about the schema Delivery, see the Schema — Delivery section.

Response Code: 404

The record could not be found.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Check if a Delivery Exists — HEAD

This section describes the endpoint which checks if a delivery exists.

Method

HEAD

URL

/api/delivery/v5/delivery/{id}

Allowed Scope(s)

delivery-r
delivery-rw 

Request

This section describes the request parameters.

Table 4-59 Checks if a Delivery Exists — Request Parameters

Parameter	Required	Data Type	Description
id	Yes	integer <int64> (query)	The identifier of the delivery.

Responses

This section describes the responses of the Check if Delivery Exists endpoint.

Response Code: 200

The requested record exists.

Response Code: 404

The record could not be found.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Queries for Delivery Records — GET

This section describes the Queries for Delivery Records endpoint. This service returns a list of delivery records and the associated delivery details matching the provided criteria.

Method

GET

URL

/api/delivery/v5/delivery

Allowed Scope(s)

delivery-r
delivery-rw 

Request

This section describes the request parameters.

Table 4-60 Queries for Delivery Records — Request Parameters

Parameter	Required	Data Type	Description
where	NA	object (query)	A JSON object containing query parameters for filtering results. Fields to be filtered on may be provided in the form of a dot-notated path named for the fields known to this resource, that is a delimited field named "child.id" would filter by the entity field of this resource named "child" and that entity has a field named "id". Querying is supported in 3 ways. If a single value is provided, it is treated as a baseline. If the single value is a character type, then the value is used as the basis for a "like" or startsWith-type comparison, for example, {"child.name":"Jo"} would match Joe, John, etc. For all other types, it serves as the lower bound of a >= comparison, {"minAmount":100.00}. If an array is provided, the values within it are treated as "equals" or "in" values depending upon the element count, for example, {"id":[1, 2, 3]}. If an object is provided, fields named "from" and "to" within the object, will serve as lower and/or upper bounds for a range-based query, for example {"id":{"from":0,"to":100}}, a field named "singleValue" can be used to follow the single value pattern discussed above, a field named "in" can be used to follow the array pattern discussed above, or a field named "fieldPath" can be used to specify the path of a related field. Additionally, a field named "caseInsensitive" can be used to enable case-insensitive querying of character-based fields and a field named "invert" can be used to invert a predicate (that is as a NOT). Combining of criteria in "and" and "or" blocks is supported by providing specially named properties with names beginning with '"@and"' and '"@or"' with JSON object values. These can be used directly within the body for criteria grouping purposes, and also nested within each other. When using multiple @and/@or groupings within a given object, take care to suffix them with additional characters (that is '"@and1"', '"@and2"', and so on) to ensure that they are uniquely named since any duplicates will be eliminated.
orderBy	NA	string (query)	A comma-delimited list of fields used to determine result ordering or a JSON array of complex sorting criteria. When supplied as strings, names are provided in the same format as the where argument - optionally followed by "asc" (default) or "desc" to control order direction. When supplied as a JSON array, a String fieldName field must be included in the object. Optional String order (asc or desc) and boolean caseInsensitive fields may also be provided.
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.
limit	NA	integer($int32) (query)	Provides a maximum number of records to be returned.
offset	NA	integer($int32) (query)	Provides the zero-based value for the position of the first value to be returned.

Responses

This section describes the responses of the Queries for Delivery Records endpoint.

Response Code: 200

The requested records.

The media type is application/json.

Example Value

[
  {
    "created": "2024-11-28T13:46:35.808Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:46:35.808Z",
    "updatedBy": "string",
    "id": <id>,
    "barcodes": [
      {
        "created": "2024-11-28T13:46:35.808Z",
        "createdBy": "string",
        "updated": "2024-11-28T13:46:35.808Z",
        "updatedBy": "string",
        "id": <id>,
        "identifier": "string",
        "parentId": <parentId>,
        "type": "CODE39",
        "value": "string"
      }
    ],
    "cancelReasonCode": "string",
    "canceledBy": "string",
    "crossReferences": [
      {
        "created": "2024-11-28T13:46:35.808Z",
        "createdBy": "string",
        "updated": "2024-11-28T13:46:35.808Z",
        "updatedBy": "string",
        "id": <id>,
        "key": "string",
        "parentId": <parentId>,
        "value": "string"
      }
    ],
    "currency": "str",
    "deliveryCancelReason": "COURIER",
    "deliveryId": "string",
    "deliveryType": "DELIVERY",
    "dropoffAddress": {
      "created": "2024-11-28T13:46:35.808Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:46:35.808Z",
      "updatedBy": "string",
      "id": <id>,
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "address4": "string",
      "addressType": "RESIDENTIAL",
      "apartment": "string",
      "city": "string",
      "country": "string",
      "latitude": 999999999,
      "locationCode": "string",
      "longitude": 999999999,
      "postalCode": "string",
      "state": "string"
    },
    "dropoffAddressId": <dropoffAddressId>,
    "dropoffContact": {
      "created": "2024-11-28T13:46:35.808Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:46:35.808Z",
      "updatedBy": "string",
      "id": <id>,
      "businessName": "string",
      "contactReference": "string",
      "emailAddress": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "phoneNumber": "string",
      "suffix": "string"
    },
    "dropoffContactId": <dropoffContactId>,
    "dropoffDeadline": "2024-11-28T13:46:35.808Z",
    "dropoffEta": "2024-11-28T13:46:35.808Z",
    "dropoffLocationCode": "string",
    "dropoffNotes": "string",
    "dropoffReady": "2024-11-28T13:46:35.808Z",
    "dropoffVerification": {
      "created": "2024-11-28T13:46:35.808Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:46:35.808Z",
      "updatedBy": "string",
      "id": <id>,
      "barcodeRequired": false,
      "barcodes": {
        "additionalProp1": "CODE39",
        "additionalProp2": "CODE39",
        "additionalProp3": "CODE39"
      },
      "contactRequired": false,
      "courierNotes": "string",
      "identificationVerified": true,
      "minimumAge": 9999,
      "pictureRequired": false,
      "pictureURL": "string",
      "signatureRequired": false,
      "signatureURL": "string"
    },
    "dropoffVerificationId": <dropoffVerificationId>,
    "errorCount": 9999,
    "fee": 10000000000000000,
    "labelsAttached": false,
    "manifest": [
      {
        "created": "2024-11-28T13:46:35.808Z",
        "createdBy": "string",
        "updated": "2024-11-28T13:46:35.808Z",
        "updatedBy": "string",
        "id": <id>,
        "description": "string",
        "height": 9999,
        "identifier": "string",
        "items": [
          {
            "created": "2024-11-28T13:46:35.808Z",
            "createdBy": "string",
            "updated": "2024-11-28T13:46:35.808Z",
            "updatedBy": "string",
            "id": <id>,
            "description": "string",
            "identifier": "string",
            "parentId": <parentId>,
            "price": 10000000000000000,
            "quantity": 9999
          }
        ],
        "length": 9999,
        "packDimensionCode": "string",
        "parentId": <parentId>,
        "totalAmount": 10000000000000000,
        "weight": 10000000000000000,
        "width": 9999
      }
    ],
    "manifestSize": 9999,
    "pickupAddress": {
      "created": "2024-11-28T13:46:35.808Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:46:35.808Z",
      "updatedBy": "string",
      "id": <id>,
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "address4": "string",
      "addressType": "RESIDENTIAL",
      "apartment": "string",
      "city": "string",
      "country": "string",
      "latitude": 999999999,
      "locationCode": "string",
      "longitude": 999999999,
      "postalCode": "string",
      "state": "string"
    },
    "pickupAddressId": <pickupAddressId>,
    "pickupContact": {
      "created": "2024-11-28T13:46:35.808Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:46:35.808Z",
      "updatedBy": "string",
      "id": <id>,
      "businessName": "string",
      "contactReference": "string",
      "emailAddress": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "phoneNumber": "string",
      "suffix": "string"
    },
    "pickupContactId": <pickupContactId>,
    "pickupDeadline": "2024-11-28T13:46:35.808Z",
    "pickupEta": "2024-11-28T13:46:35.808Z",
    "pickupLocationCode": "string",
    "pickupNotes": "string",
    "pickupReady": "2024-11-28T13:46:35.808Z",
    "pickupVerification": {
      "created": "2024-11-28T13:46:35.808Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:46:35.808Z",
      "updatedBy": "string",
      "id": <id>,
      "barcodeRequired": false,
      "barcodes": {
        "additionalProp1": "CODE39",
        "additionalProp2": "CODE39",
        "additionalProp3": "CODE39"
      },
      "contactRequired": false,
      "courierNotes": "string",
      "identificationVerified": true,
      "minimumAge": 9999,
      "pictureRequired": false,
      "pictureURL": "string",
      "signatureRequired": false,
      "signatureURL": "string"
    },
    "pickupVerificationId": <pickVerificationId>,
    "provider": "string",
    "providerCreated": "2024-11-28T13:46:35.808Z",
    "providerId": "string",
    "providerInstance": "string",
    "returnTripId": <returnTripId>,
    "status": "CREATED",
    "statusHistory": [
      {
        "created": "2024-11-28T13:46:35.808Z",
        "createdBy": "string",
        "updated": "2024-11-28T13:46:35.808Z",
        "updatedBy": "string",
        "id": 9223372036854776000,
        "newStatus": "CREATED",
        "parentId": <parentId>,
        "priorStatus": "CREATED"
      }
    ],
    "tip": 10000000000000000,
    "totalValue": 10000000000000000,
    "trackingURL": "string",
    "undeliverableInfo": {
      "created": "2024-11-28T13:46:35.808Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:46:35.808Z",
      "updatedBy": "string",
      "id": <id>,
      "moreInfo": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "reason": "string",
      "undeliverableAction": "LEAVE_AT_DOOR"
    },
    "undeliverableInfoId": <undeliverableInfoId>
  }
]

Schema — Delivery

For more information about the schema Delivery, see the Schema — Delivery section.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Queries for Delivery Records/Count — GET

This section describes the Queries for Delivery Records Count endpoint. This service returns a count of records matching the provided criteria.

Method

GET

URL

/api/delivery/v5/delivery/count

Allowed Scope(s)

delivery-r

Request

This section describes the request parameters.

Table 4-61 Queries for a Delivery Records Count — Request Parameters

Parameter	Required	Data Type	Description
where	NA	object (query)	A JSON object containing query parameters for filtering results. Fields to be filtered on may be provided in the form of a dot-notated path named for the fields known to this resource, that is a delimited field named "child.id" would filter by the entity field of this resource named "child" and that entity has a field named "id". Querying is supported in 3 ways. If a single value is provided, it is treated as a baseline. If the single value is a character type, then the value is used as the basis for a "like" or startsWith-type comparison, for example, {"child.name":"Jo"} would match Joe, John, and son on. For all other types, it serves as the lower bound of a >= comparison, {"minAmount":100.00}. If an array is provided, the values within it are treated as "equals" or "in" values depending upon the element count, for example, {"id":[1, 2, 3]}. If an object is provided, fields named "from" and "to" within the object, will serve as lower and/or upper bounds for a range-based query, for example, {"id":{"from":0,"to":100}}, a field named "singleValue" can be used to follow the single value pattern discussed above, a field named "in" can be used to follow the array pattern discussed above, or a field named "fieldPath" can be used to specify the path of a related field. Additionally, a field named "caseInsensitive" can be used to enable case-insensitive querying of character-based fields and a field named "invert" can be used to invert a predicate (that is as a NOT). Combining of criteria in "and" and "or" blocks is supported by providing specially named properties with names beginning with '"@and"' and '"@or"' with JSON object values. These can be used directly within the body for criteria grouping purposes, and also nested within each other. When using multiple @and/@or groupings within a given object, take care to suffix them with additional characters (that is '"@and1"', '"@and2"', and so on) to ensure that they are uniquely named since any duplicates will be eliminated.

Responses

This section describes the responses of the Queries for Delivery Records Count endpoint.

Response Code: 200

The requested records.

The media type is application/json.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Queries for Delivery Records by Attributes — GET

This section describes the Queries for Delivery Records by Attributes endpoint. This endpoint returns a list of records matching the provided attributes.

Method

GET

URL

/api/deliver/v5/delivery/byattributes

Allowed Scope(s)

delivery-r

Request

This section describes the request parameters.

Table 4-62 Queries for Delivery Records by Attributes — Request Parameters

Parameter	Required	Data Type	Description
id	NA	integer ($int64) (query)	ID
cancelReasonCode	NA	string (query)	cancel Reason Code
canceledBy	NA	string (query)	canceled by
currency	NA	string (query)	currency
deliveryCancelReason	NA	string (query)	delivery cancel reason Available values: COURIER, PROVIDER, CUSTOMER
deliveryId	NA	string (query)	delivery ID
deliveryType	NA	string (query)	delivery type; Available values: DELIVERY, RETURN; Default value: DELIVERY
dropoffAddressId	NA	integer ($int64) (query)	dropoff address ID
dropoffContactId	NA	integer ($int64) (query)	dropoff contact ID
dropoffDeadline	NA	string ($date-time) (query)	dropoff deadline
dropoffEta	NA	string($date-time) (query)	dropoff Eta
dropoffLocationCode	NA	string (query)	dropoff location code
dropoffNotes	NA	string (query)	dropoff notes
dropoffReady	NA	string($date-time) (query)	dropoff ready
dropoffVerificationId	NA	integer($int64) (query)	dropoff verification ID
errorCount	NA	integer($int32) (query)	error count
fee	NA	number (query)	fee
labelsAttached	NA	boolean (query)	Default value : false Note: Return delivery types have the following limitations with the Uber integration: Labels Attached will always be set to TRUE which indicates that a label will be attached to the package(s).
manifestSize	NA	integer ($int32) (query)	manifest size
pickupAddressId	NA	integer ($int64) (query)	pickup address ID
pickupContactId	NA	integer ($int64) (query)	pickup contact ID
pickupDeadline	NA	string ($date-time) (query)	pickup deadline
pickupEta	NA	string ($date-time) (query)	pickup Eta
pickupLocationCode	NA	string (query)	pickup location code
pickupNotes	NA	string (query)	pickup notes
pickupReady	NA	string ($date-time) (query)	pickup ready
pickupVerificationId	NA	integer ($int64) (query)	pickup verification ID
provider	NA	string (query)	provider
providerCreated	NA	string ($date-time) (query)	provider created
providerId	NA	string (query)	provider ID
providerInstance	NA	string (query)	provider instance
returnTripId		integer($int64) (query)	return trip ID
status	NA	string (query)	Available values : CREATED, PENDING, ENROUTE_PICKUP, PICKUP_COMPLETE, ENROUTE_DROPOFF, DROPOFF_COMPLETE, CANCELED, RETURNED, ERROR, ENROUTE_RETURN
tip	NA	number (query)	tip
totalValue	NA	number (query)	total value
trackingURL	NA	string (query)	tracking URL
undeliverableInfoId	NA	integer ($int64) (query)	undeliverable info ID
orderBy	NA	string (query)	A comma-delimited list of fields used to determine result ordering or a JSON array of complex sorting criteria. When supplied as strings, names are provided in the same format as the where argument - optionally followed by "asc" (default) or "desc" to control order direction. When supplied as a JSON array, a String fieldName field must be included in the object. Optional String order (asc or desc) and boolean caseInsensitive fields may also be provided.
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is"child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.
limit	NA	integer ($int32) (query)	Provides a maximum number of records to be returned.
offset	NA	integer ($int32) (query)	Provides the zero-based value for the position of the first value to be returned.

Responses

This section describes the responses of the Queries for Delivery Records by Attributes endpoint.

Response Code: 200

The requested records.

The media type is application/json.

Example Value

[
  {
    "created": "2024-11-28T13:53:35.285Z",
    "createdBy": "string",
    "updated": "2024-11-28T13:53:35.285Z",
    "updatedBy": "string",
    "id": <id>,
    "barcodes": [
      {
        "created": "2024-11-28T13:53:35.285Z",
        "createdBy": "string",
        "updated": "2024-11-28T13:53:35.285Z",
        "updatedBy": "string",
        "id": <id>,
        "identifier": "string",
        "parentId": <parentId>,
        "type": "CODE39",
        "value": "string"
      }
    ],
    "cancelReasonCode": "string",
    "canceledBy": "string",
    "crossReferences": [
      {
        "created": "2024-11-28T13:53:35.285Z",
        "createdBy": "string",
        "updated": "2024-11-28T13:53:35.285Z",
        "updatedBy": "string",
        "id": <id>,
        "key": "string",
        "parentId": <parentId>,
        "value": "string"
      }
    ],
    "currency": "str",
    "deliveryCancelReason": "COURIER",
    "deliveryId": "string",
    "deliveryType": "DELIVERY",
    "dropoffAddress": {
      "created": "2024-11-28T13:53:35.285Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:53:35.285Z",
      "updatedBy": "string",
      "id": <id>,
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "address4": "string",
      "addressType": "RESIDENTIAL",
      "apartment": "string",
      "city": "string",
      "country": "string",
      "latitude": 999999999,
      "locationCode": "string",
      "longitude": 999999999,
      "postalCode": "string",
      "state": "string"
    },
    "dropoffAddressId": <dropoffAddressId>,
    "dropoffContact": {
      "created": "2024-11-28T13:53:35.285Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:53:35.285Z",
      "updatedBy": "string",
      "id": <id>,
      "businessName": "string",
      "contactReference": "string",
      "emailAddress": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "phoneNumber": "string",
      "suffix": "string"
    },
    "dropoffContactId": <dropoffContactId>,
    "dropoffDeadline": "2024-11-28T13:53:35.285Z",
    "dropoffEta": "2024-11-28T13:53:35.285Z",
    "dropoffLocationCode": "string",
    "dropoffNotes": "string",
    "dropoffReady": "2024-11-28T13:53:35.285Z",
    "dropoffVerification": {
      "created": "2024-11-28T13:53:35.285Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:53:35.285Z",
      "updatedBy": "string",
      "id": <id>,
      "barcodeRequired": false,
      "barcodes": {
        "additionalProp1": "CODE39",
        "additionalProp2": "CODE39",
        "additionalProp3": "CODE39"
      },
      "contactRequired": false,
      "courierNotes": "string",
      "identificationVerified": true,
      "minimumAge": 9999,
      "pictureRequired": false,
      "pictureURL": "string",
      "signatureRequired": false,
      "signatureURL": "string"
    },
    "dropoffVerificationId": 9223372036854776000,
    "errorCount": 9999,
    "fee": 10000000000000000,
    "labelsAttached": false,
    "manifest": [
      {
        "created": "2024-11-28T13:53:35.285Z",
        "createdBy": "string",
        "updated": "2024-11-28T13:53:35.285Z",
        "updatedBy": "string",
        "id": 9223372036854776000,
        "description": "string",
        "height": 9999,
        "identifier": "string",
        "items": [
          {
            "created": "2024-11-28T13:53:35.285Z",
            "createdBy": "string",
            "updated": "2024-11-28T13:53:35.285Z",
            "updatedBy": "string",
            "id": <id>,
            "description": "string",
            "identifier": "string",
            "parentId": 9223372036854776000,
            "price": 10000000000000000,
            "quantity": 9999
          }
        ],
        "length": 9999,
        "packDimensionCode": "string",
        "parentId": 9223372036854776000,
        "totalAmount": 10000000000000000,
        "weight": 10000000000000000,
        "width": 9999
      }
    ],
    "manifestSize": 9999,
    "pickupAddress": {
      "created": "2024-11-28T13:53:35.285Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:53:35.285Z",
      "updatedBy": "string",
      "id": <id>,
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "address4": "string",
      "addressType": "RESIDENTIAL",
      "apartment": "string",
      "city": "string",
      "country": "string",
      "latitude": 999999999,
      "locationCode": "string",
      "longitude": 999999999,
      "postalCode": "string",
      "state": "string"
    },
    "pickupAddressId": <pickupAddressId>,
    "pickupContact": {
      "created": "2024-11-28T13:53:35.285Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:53:35.285Z",
      "updatedBy": "string",
      "id": <id>,
      "businessName": "string",
      "contactReference": "string",
      "emailAddress": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "phoneNumber": "string",
      "suffix": "string"
    },
    "pickupContactId": <pickupcontactId>,
    "pickupDeadline": "2024-11-28T13:53:35.285Z",
    "pickupEta": "2024-11-28T13:53:35.285Z",
    "pickupLocationCode": "string",
    "pickupNotes": "string",
    "pickupReady": "2024-11-28T13:53:35.285Z",
    "pickupVerification": {
      "created": "2024-11-28T13:53:35.285Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:53:35.285Z",
      "updatedBy": "string",
      "id": <id>,
      "barcodeRequired": false,
      "barcodes": {
        "additionalProp1": "CODE39",
        "additionalProp2": "CODE39",
        "additionalProp3": "CODE39"
      },
      "contactRequired": false,
      "courierNotes": "string",
      "identificationVerified": true,
      "minimumAge": 9999,
      "pictureRequired": false,
      "pictureURL": "string",
      "signatureRequired": false,
      "signatureURL": "string"
    },
    "pickupVerificationId": <pickupVerificationId>,
    "provider": "string",
    "providerCreated": "2024-11-28T13:53:35.285Z",
    "providerId": "string",
    "providerInstance": "string",
    "returnTripId": <returnTripId>,
    "status": "CREATED",
    "statusHistory": [
      {
        "created": "2024-11-28T13:53:35.285Z",
        "createdBy": "string",
        "updated": "2024-11-28T13:53:35.285Z",
        "updatedBy": "string",
        "id": <id>,
        "newStatus": "CREATED",
        "parentId": <parentId>,
        "priorStatus": "CREATED"
      }
    ],
    "tip": 10000000000000000,
    "totalValue": 10000000000000000,
    "trackingURL": "string",
    "undeliverableInfo": {
      "created": "2024-11-28T13:53:35.285Z",
      "createdBy": "string",
      "updated": "2024-11-28T13:53:35.285Z",
      "updatedBy": "string",
      "id": <id>,
      "moreInfo": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "reason": "string",
      "undeliverableAction": "LEAVE_AT_DOOR"
    },
    "undeliverableInfoId": <undeliverableInfoId>
  }
]

Schema — Delivery

For more information about the schema Delivery, see the Schema — Delivery section.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Metrics Services

This section describes the Metrics Services.

Metrics — GET

This section describes the Metrics endpoint. This service retrieves delivery metrics for created, completed, canceled, and returned deliveries based on specified parameters such as delivery type, start and end date, and time zone offset.

Method

GET

URL

/api/delivey/v5/metric/delivery

Allowed Scope(s)

delivery-r

Request

This section describes the request parameters.

Table 4-63 Metrics — Request Parameters

Parameter	Required	Data Type	Description
providerInstance	NA	string (query)	The provider instance of the delivery.
type	NA	string (query)	The delivery type of metric data. Available values: DELIVERY, RETURN Note: If both values are required, leave the type value blank.
dateRange	NA	string (query)	The date range of delivery metric data. dateRange takes precedence and ignores startDate and endDate when specified. Available values: YDY, TDY, MTD, YTD
offset	NA	string (query)	The time-zone offset of dateRange in the form of (+/-)HH:MI between -18:00 and +18:00 (inclusive).
startDateTime	NA	string ($date-time) (query)	The start datetime of delivery metric data when dateRange is not specified.
endDateTime	NA	string ($date-time) (query)	The end datetime of delivery metric data when dateRange is not specified.
results	Yes	string (query)	The summary type that determines how data will be aggregated when returned. Available values: DETAIL, DAILY, SINGLE

Responses

This section describes the responses of the Metrics endpoint.

Response Code: 200

The result object.

The media type is application/json.

Example Value

[
  {
    "intervalEnd": "2024-07-24T16:18:49.626Z",
    "intervalStart": "2024-07-24T16:18:49.626Z",
    "metrics": [
      {
        "metricType": "DELIVERIES_CREATED",
        "value": 2147483647
      }
    ]
  }

Schema — Metric Response

The following table describes the Metric Response object.

Table 4-64 Metric Response — Object

Element Name	Required	Data Type	Description
intervalEnd	Yes	string($date-time)	The end time of metric data.
intervalStart	Yes	string($date-time)	The start time of metric data.
metrics	NA	object	A collection of metric items for a given period.

The following table describes a container for predefined metrics.

Table 4-65 Metric — Object

Element Name	Required	Data Type	Description
metricType	NA	string	A type of metric. Enum: [DELIVERIES_CREATED, DELIVERIES_COMPLETED, DELIVERIES_CANCELED, DELIVERIES_RETURNED, RETURNS_CREATED, RETURNS_COMPLETED, RETURNS_CANCELED, RETURNS_RETURNED]
value	NA	integer ($int32)	A count of metric.

Response Code: 400

The provided input is valid.

The media type is application/json.

Example

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

For details about the Mapper Error Data schema, see the Schema — Mapper Error Data section.

Response Code: 500

The request failed.

Location Metrics — GET

This section describes the Location Metrics endpoint. This service retrieves delivery metrics, for a specific location, for created, completed, canceled, and returned deliveries based on specified parameters such as delivery type, start and end date, and time zone offset.

Method

GET

URL

/api/delivery/v5/metric/location/{locationCode}

Allowed Scope(s)

delivery-r

Request

This section describes the request parameters.

Table 4-66 Location Metrics — Request Parameters

Parameter	Required	Data Type	Description
providerInstance	NA	string (query)	The provider instance of the delivery.
type	NA	string (query)	The delivery type of metric data. All types will be returned if left empty. Available values : DELIVERY, RETURN
dateRange	NA	string (query)	The date range of delivery metric data. dateRange takes precedence and ignores startDate and endDate when specified. Available values : YDY, TDY, MTD, YTD
offset	NA	string (query)	The time-zone offset of dateRange in the form of (+/-)HH:MI between -18:00 and +18:00 (inclusive).
startDateTime	NA	string($date-time) (query)	The start datetime of delivery metric data when dateRange is not specified.
endDateTime	NA	string($date-time) (query)	The end datetime of delivery metric data when dateRange is not specified.
results	Yes	string (query)	The summary type that determines how data will be aggregated when returned. Available values : DETAIL, DAILY, SINGLE
locationCode	Yes	string (path)	The location code of metric data. A location code that matches a pickup location code will fall under Outbound Metrics data and a location code that matches a dropoff location code will fall under Inbound Metrics data.

Responses

This section describes the responses of the Metrics endpoint.

Response Code: 200

The result object.

The media type is application/json.

Example Value

[
  {
    "intervalEnd": "2024-07-24T16:19:45.792Z",
    "intervalStart": "2024-07-24T16:19:45.792Z",
    "locationCode": "string",
    "metricsInbound": [
      {
        "metricType": "DELIVERIES_CREATED",
        "value": 2147483647
      }
    ],
    "metricsOutbound": [
      {
        "metricType": "DELIVERIES_CREATED",
        "value": 2147483647
      }
    ]
  }
]

Schema — Location Metric Response

The following table describes the Location Metric Response object. A container for a metric response

Table 4-67 Location Metric Response — Object

Element Name	Required	Data Type	Description
intervalEnd	Yes	string($date-time)	The end time of metric data.
intervalStart	Yes	string($date-time)	The start time of metric data.
locationCode	NA	string	The location code of metric data where inbound (dropoff location) and outbound (pickup location) metrics are based.
metricsInbound	NA	object	A collection of metric inbound items for a given period if a location code is provided and if the location code matches a dropoff location code.
metricsOutbound	NA	object	A collection of metric outbound items for a given period if a location code is provided and if the location code matches a pickup location code.

The following table describes a container for predefined metrics.

Table 4-68 Metric — Object

Element Name	Required	Data Type	Description
metricType	NA	string	A type of metric. Enum: [DELIVERIES_CREATED, DELIVERIES_COMPLETED, DELIVERIES_CANCELED, DELIVERIES_RETURNED, RETURNS_CREATED, RETURNS_COMPLETED, RETURNS_CANCELED, RETURNS_RETURNED]
value	NA	integer ($int32)	A count of metric.

Response Code: 400

The provided input is valid.

The media type is application/json.

Example

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

For details about the Mapper Error Data schema, see the Schema — Mapper Error Data section.

Response Code: 500

The request failed.

Webhook Credential Services

This section describes the Webhook Credential Services.

Add Credential — POST

This section describes the AddCredential API. This API creates a new credential.

Method

POST

URL

/api/delivery/v5/webhook/credential

Allowed Scope(s)

webhook-rw

Request

There are no request parameters.

The request body is application/json.

A request indicating the parameters of the credential.

Example Value

{
  "clientId": "string",
  "clientSecret": "string",
  "credentialId": "string",
  "description": "string",
  "id": <id>,
  "scope": "string",
  "url": "string"
}

Schema — Credential Request

The following table describes a request to create/update a credential used when accessing an external service.

Table 4-69 CredentialRequest — Object

Element Name	Required	Data Type	Description
clientId	yes	string(256)	The client ID for the credential.
clientSecret	yes	string(256)	The client secret for the credential.
credentialId	yes	string(32)	The credential ID.
description	NA	string(256)	The credential description, if one has been defined.
id	NA	integer($int64)	ID
scope	NA	string	The scope for the credential.
url	yes	string	The OAuth2 URL for the credential.

Responses

This section describes the responses of the Add Credential endpoint.

Response Code: 200

The request was processed successfully.

The media type is application/json.

Example Value

{
  "created": "2024-01-19T10:11:38.601Z",
  "createdBy": "string",
  "credentialId": "string",
  "description": "string",
  "id": <id>,
  "updated": "2024-01-19T10:11:38.601Z",
  "updatedBy": "string"
}

Schema — Credential Response

The table below describes a credential used when accessing an external service..

Table 4-70 Credential Response — Object

Element Name	Required	Data Type	Description
created	yes	string ($date-time)	The timestamp at which the credential was created.
created By	yes	string	The user that created the credential.
credentialId	yes	string(32)	The credential ID.
description	NA	string(256)	The credential description, if one has been defined.
id	NA	integer($int64)	ID
updated	NA	string($date-time)	The timestamp at which the credential was last updated, or null if it has never been updated.
updatedBy	NA	string	The user that last updated the credential, or null if it has never been updated.

Response Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

The table below describes the elements of the Mapper Error Data object.

Table 4-71 Mapper Error Data — Object

Element Name	Required	Data Type	Description
column	NA	integer <int32>	The JSON file column number the error occurred on if known
line	NA	integer <int32>	The JSON file line number the error occurred on if known
errorCode	NA	integer <int32>	A numeric identifier for the type of error
errorMessage	NA	string	The unlocalized error message
moreInfo	NA	object	Additional information pertaining to the error
field	NA	string	The field. This is the last part of the path
value	NA	string	The JSON value that caused the error if known
errorType	NA	string	enum: INTEGRATION, INTERNAL, MAPPING, PARSING, VALIDATION An enumeration of specific known error types.

The following table describes the elements of the additional information pertaining to the error.

Table 4-72 More Info — Object

Element Name	Required	Data Type	Description
code	NA	string	A code describing the error.
description	NA	string	An unlocalizable description describing the error.

Response Code: 409

The provided credentialId already exists.

Response Code: 500

A server error prevented successful processing of the request.

Get Credentials — GET

This section describes the GetCredentials API. This API obtains a set of known credentials.

Method

GET

URL

/api/delivery/v5/webhook/credential

Allowed Scope(s)

webhook-rw

Request

There are no request parameters.

Responses

This section describes the responses of the GetCredentials API.

Response Code: 200

A set of known credentials.

The media type is application/json.

Example Value

[
  {
    "created": "2024-01-19T10:20:01.887Z",
    "createdBy": "string",
    "credentialId": "string",
    "description": "string",
    "id": <id>,
    "updated": "2024-01-19T10:20:01.887Z",
    "updatedBy": "string"
  }
]

Schema — Credential Response

The table below describes a credential used when accessing an external service..

Table 4-73 Credential Response — Object

Element Name	Required	Data Type	Description
created	yes	string ($date-time)	The timestamp at which the credential was created.
created By	yes	string	The user that created the credential.
credentialId	yes	string(32)	The credential ID.
description	NA	string(256)	The credential description, if one has been defined.
id	NA	integer($int64)	ID
updated	NA	string($date-time)	The timestamp at which the credential was last updated, or null if it has never been updated.
updatedBy	NA	string	The user that last updated the credential, or null if it has never been updated.

Response Code: 500

A server error prevented successful processing of the request.

Get Credential — GET

This section describes the GetCredential API. This API obtains a credential.

Method

GET

URL

/api/delivery/v5/webhook/credential/{id}

Allowed Scope(s)

webhook-rw

Request

This section describes the request parameters.

Table 4-74 Get Credential — Request Parameters

Parameter	Required	Data Type	Description
id	Yes	integer($int64)	ID

Responses

This section describes the responses of the GetCredential API.

Response Code: 200

The requested credential.

The media type is application/json.

Example Value

{
  "created": "2024-05-22T11:55:10.379Z",
  "createdBy": "string",
  "credentialId": "string",
  "description": "string",
  "id": <id>,
  "updated": "2024-05-22T11:55:10.379Z",
  "updatedBy": "string"
}

Schema — Credential Response

The table below describes a credential used when accessing an external service..

Table 4-75 Credential Response — Object

Element Name	Required	Data Type	Description
created	yes	string ($date-time)	The timestamp at which the credential was created.
created By	yes	string	The user that created the credential.
credentialId	yes	string(32)	The credential ID.
description	NA	string(256)	The credential description, if one has been defined.
id	NA	integer($int64)	ID
updated	NA	string($date-time)	The timestamp at which the credential was last updated, or null if it has never been updated.
updatedBy	NA	string	The user that last updated the credential, or null if it has never been updated.

Response Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

The table below describes the elements of the Mapper Error Data object.

Table 4-76 Mapper Error Data — Object

Element Name	Required	Data Type	Description
column	NA	integer <int32>	The JSON file column number the error occurred on if known
line	NA	integer <int32>	The JSON file line number the error occurred on if known
errorCode	NA	integer <int32>	A numeric identifier for the type of error
errorMessage	NA	string	The unlocalized error message
moreInfo	NA	object	Additional information pertaining to the error
field	NA	string	The field. This is the last part of the path
value	NA	string	The JSON value that caused the error if known
errorType	NA	string	enum: INTEGRATION, INTERNAL, MAPPING, PARSING, VALIDATION An enumeration of specific known error types.

The following table describes the elements of the additional information pertaining to the error.

Table 4-77 More Info — Object

Element Name	Required	Data Type	Description
code	NA	string	A code describing the error.
description	NA	string	An unlocalizable description describing the error.

Response Code: 404

The requested credential could not be found.

Response Code: 500

A server error prevented successful processing of the request.

Update Credential — PUT

This section describes the UpdateCredential API. This API updates a credential.

Method

PUT

URL

/api/delivery/v5/webhook/credential/{id}

Allowed Scope(s)

webhook-rw

Request

This table describes the request parameters of the DeleteCredential API.

The request body is application/json.

A request indicating the parameters of the credential.

Table 4-78 UpdateCredential — Request Parameters

Parameter	Required	Data Type	Description
id	yes	integer($int64) (path)	The credential id to be updated.

Example Value

{
  "clientId": "string",
  "clientSecret": "string",
  "credentialId": "string",
  "description": "string",
  "id": <id>,
  "scope": "string",
  "url": "string"
}

Schema — Credential Request

The following table describes a request to create/update a credential used when accessing an external service.

Table 4-79 CredentialRequest — Object

Element Name	Required	Data Type	Description
clientId	yes	string(256)	The client ID for the credential.
clientSecret	yes	string(256)	The client secret for the credential.
credentialId	yes	string(32)	The credential ID.
description	NA	string(256)	The credential description, if one has been defined.
id	NA	integer($int64)	ID
scope	NA	string	The scope for the credential.
url	yes	string	The OAuth2 URL for the credential.

Responses

This section describes the responses of the UpdateCredential API.

Response Code: 200

The request was processed successfully.

The media type is application/json.

Example Value

{
  "created": "2024-01-19T10:27:47.428Z",
  "createdBy": "string",
  "credentialId": "string",
  "description": "string",
  "id": <id>,
  "updated": "2024-01-19T10:27:47.428Z",
  "updatedBy": "string"
}

Schema — Credential Response

The table below describes a credential used when accessing an external service..

Table 4-80 Credential Response — Object

Element Name	Required	Data Type	Description
created	yes	string ($date-time)	The timestamp at which the credential was created.
created By	yes	string	The user that created the credential.
credentialId	yes	string(32)	The credential ID.
description	NA	string(256)	The credential description, if one has been defined.
id	NA	integer($int64)	ID
updated	NA	string($date-time)	The timestamp at which the credential was last updated, or null if it has never been updated.
updatedBy	NA	string	The user that last updated the credential, or null if it has never been updated.

Response Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

The table below describes the elements of the Mapper Error Data object.

Table 4-81 Mapper Error Data — Object

Element Name	Required	Data Type	Description
column	NA	integer <int32>	The JSON file column number the error occurred on if known
line	NA	integer <int32>	The JSON file line number the error occurred on if known
errorCode	NA	integer <int32>	A numeric identifier for the type of error
errorMessage	NA	string	The unlocalized error message
moreInfo	NA	object	Additional information pertaining to the error
field	NA	string	The field. This is the last part of the path
value	NA	string	The JSON value that caused the error if known
errorType	NA	string	enum: INTEGRATION, INTERNAL, MAPPING, PARSING, VALIDATION An enumeration of specific known error types.

The following table describes the elements of the additional information pertaining to the error.

Table 4-82 More Info — Object

Element Name	Required	Data Type	Description
code	NA	string	A code describing the error.
description	NA	string	An unlocalizable description describing the error.

Response Code: 404

The requested credential could not be found.

Response Code: 500

A server error prevented successful processing of the request.

Delete Credential — DELETE

This section describes the DeleteCredential API. This API deletes a credential.

Method

DELETE

URL

/api/delivery/v5/webhook/credential/{id} 

Allowed Scope(s)

webhook-rw

Request

This table describes the request parameters of the DeleteCredential API.

Table 4-83 DeleteCredential — Request Parameters

Parameter	Required	Data Type	Description
id	yes	integer($int64) (path)	The credential id to be deleted.

Responses

This section describes the responses of the DeleteCredential API.

Response Code: 204

The credential was successfully found and deleted.

Response Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

The table below describes the elements of the Mapper Error Data object.

Table 4-84 Mapper Error Data — Object

Element Name	Required	Data Type	Description
column	NA	integer <int32>	The JSON file column number the error occurred on if known
line	NA	integer <int32>	The JSON file line number the error occurred on if known
errorCode	NA	integer <int32>	A numeric identifier for the type of error
errorMessage	NA	string	The unlocalized error message
moreInfo	NA	object	Additional information pertaining to the error
field	NA	string	The field. This is the last part of the path
value	NA	string	The JSON value that caused the error if known
errorType	NA	string	enum: INTEGRATION, INTERNAL, MAPPING, PARSING, VALIDATION An enumeration of specific known error types.

The following table describes the elements of the additional information pertaining to the error.

Table 4-85 More Info — Object

Element Name	Required	Data Type	Description
code	NA	string	A code describing the error.
description	NA	string	An unlocalizable description describing the error.

Response Code: 404

The requested credential could not be found.

Response Code: 409

The provided credential ID is in use and cannot be deleted.

Response Code: 500

A server error prevented successful processing of the request.

Status Notification Webhook Services

This section describes the Status Notification Webhook Services.

Collect and Receive can notify external applications about updates to the statuses of deliveries by webhooks. Webhook notifications occur whenever the status of a delivery changes, and allows interested applications to subscribe to notifications in near-real-time. Note the following details:

• Notifications are sent via REST, authenticated using OAuth 2.0, and may include up to 100 notifications per batch.

• Consuming applications must acknowledge the receipt of notifications by responding as per the requirements of the API.

• Delivery attempts will be made for up to 48 hours if notifications cannot be transmitted successfully.

  • Any notification that could not reach its destination, or was not acknowledged, is treated as unsuccessful.

  • Each retry attempt will be attempted with increasing delay. The first retry will occur after 30 seconds, and each subsequent attempt increases the delay period by 4x.

The webhook API, which would be implemented by an application interested in these notifications, looks as following:

{
    "openapi": "3.0.1",
    "info": {
        "title": "Oracle Collect and Receive Delivery Notification",
        "version": "2.0.0",
        "description": "A delivery notification API for Oracle Collect and Receive"
    },
    "paths": {
        "/notify": {
            "post": {
                "summary": "notify",
                "description": "Send delivery status notifications.",
                "operationId": "notify",
                "tags": [
                  "WebhookV2"
                ],
                "requestBody": {
                    "description": "Delivery with pickup or dropOff delayed notifications.",
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/NotificationV2"
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successfully received delivery IDs.  This array must contain the unique identifiers of deliveries that have been successfully received from the request body.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "maximum": 9223372036854776000,
                                        "minimum": -9223372036854776000,
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "The unique identifier of the delivery."
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "NotificationV2": {
                "type": "object",
                "properties": {
                    "id": {
                        "maximum": 9223372036854776000,
                        "minimum": -9223372036854776000,
                        "type": "integer",
                        "format": "int64",
                        "description": "The unique identifier of the delivery."
                    },
                    "deliveryId": {
                        "maxLength": 128,
                        "minLength": 0,
                        "type": "string",
                        "description": "The primary reference ID from the calling system uniquely identifying this delivery."
                    },
                    "deliveryAttributes": {
                        "description": "The delivery identifier attributes.",
                        "$ref": "#/components/schemas/DeliveryAttributes"
                    },
                    "status": {
                        "description": "The last known status of the delivery.",
                        "$ref": "#/components/schemas/DeliveryStatus"
                    },
                    "updated": {
                        "type": "string",
                        "description": "The timestamp at which the record was last updated.",
                        "format": "date-time"
                    }
                }
            },
            "DeliveryStatus": {
              "type": "string",
              "description": "The last known status of the delivery.",
              "enum": [
                  "CREATED",
                  "PENDING",
                  "ENROUTE_PICKUP",
                  "PICKUP_COMPLETE",
                  "ENROUTE_DROPOFF",
                  "DROPOFF_COMPLETE",
                  "CANCELED",
                  "RETURNED",
                  "ERROR",
                  "ENROUTE_RETURN"
              ]
            },
            "DeliveryAttributes": {
             "type": "array",
             "description": "The delivery identifier attributes.",
			 "items": {
                "type": "string",
				"description": "The enumeration of attributes.",
                "enum": ["PICKUP_DELAYED","DROPOFF_DELAYED"]
              }
          }
        }
    }
}

Leveraging the Status Notification Webhook for Delivery Communications

The Collect and Receive Status Notification Webhook can be leveraged and used to facilitate and trigger communication to the sending and/or receiving parties of a delivery. Leveraging the webhook to send communications is beneficial specifically for external clients, businesses, or users, that are not part of your organization and do not have access to the Collect and Receive UI, but need updates about the progress of a delivery. 

It is strongly recommended that the business system(s) that are receiving the Status Notification webhooks use the notifications to get the delivery details, create package labels, and communicate them to the contact at the pickup location. As part of the delivery process, labels must be attached to all packages for the courier to scan during transport. When the contact at the pickup location does not have access to the Collect and Receive UI, they will not be able to retrieve the package labels. 

Sending communications externally can be accomplished by doing the following on receipt of the Status Notification Webhook:

1. The receiving system can call the Collect and Receive getStatus API to retrieve all of the details about the delivery

2. Trigger, via your business’ own communication tool (i.e. Email Service Provider), an external notification (i.e. email, SMS, push notification) about the status of an order and the ongoing delivery process. (Examples: Delivery Scheduled Successfully, Delivery is delayed, Packages are out for delivery, an so on)

3. If the status in the webhook notification was pending, use the delivery details to create and send package label(s) to the contact at the pickup location. Package labels and barcodes must be affixed to each package being sent in a delivery prior to courier pickup. When creating a package label, consider including the following: 

   1. Delivery ID - (Required)

   2. Manifest Identifier - Printed as a QR code (Required) 

   3. Package X of Y

   4. Pickup Contact and Address Details

   5. Dropoff Contact and Address Details

The following are sample scenarios that articulate the benefits of leveraging the status notifications to send external communications:

Scenario 1: A business user creates an inbound delivery via the Collect and Receive User Interface, for packages to be picked up from a non-Collect and Receive user.

When not leveraging the Status Notification Webhook, the non-Collect and Receive user will:	When leveraging the Status Notification Webhook, the non-Collect and Receive user can:
Not receive a communication confirming the pickup and delivery details Not be aware they need to print and affix package labels Not be sent any labels for their packages Not know when the courier is enroute to pickup the packages	Receive a communication confirming the pickup and delivery details. Receive communication that includes the package labels with instructions on how/where to affix them. Receive added communication when the courier is enroute to pickup the packages Receive communication if a delivery is delayed.

 Scenario 2: A business user creates an outbound delivery via the Collect and Receive User Interface, for packages to be sent to a non-Collect and Receive user.

When not leveraging the Status Notification Webhook, the non-Collect and Receive user will:	When leveraging the Status Notification Webhook, the non-Collect and Receive user can:
Not receive a communication confirming the pickup and delivery details. This may include instructions such as having an ID ready for Age Verification or the ability to track the delivery/courier. Not receive on-going communications when as the delivery progresses in status through completion.	Receive communications throughout the entire delivery lifecycle. Receive communication if a delivery is delayed.

Add a New Webhook — POST

This section describes the Add a New Webhook API.

Method

POST

URL

/api/delivery/v5/webhook

Allowed Scope(s)

webhook-rw

Request

This section describes the request parameters.

The request body is application/json.

The ModelField is null.

Table 4-86 Add a New Webhook — Request Parameters

Parameter	Required	Data Type	Description
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.

Example Value

{
  "created": "2023-12-14T09:51:05.370Z",
  "createdBy": "string",
  "updated": "2023-12-14T09:51:05.370Z",
  "updatedBy": "string",
  "id": <id>,
  "credentialId": "string",
  "description": "string",
  "url": "string",
  "webhookId": "string",
  "webhookType": "STATUS_NOTIFICATION_V1"
}

Schema — Webhook

The following table describes the elements of a webhook used to send delivery status notifications to an external service.

Table 4-87 Webhook — Object

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
credentialId	Yes	string(32)	The credential ID.
description	NA	string(256)	The webhook description, if one has been defined.
url	Yes	string(1024)	The URL for the webhook.
webhookId	Yes	string(32)	The webhook ID. Webhook IDs must contain only letters, numbers, and underscores.
webhookType	Yes	string	Enum: STATUS_NOTIFICATION_V1, STATUS_NOTIFICATION_V2

Responses

This section describes the responses of the Add a New Webhook API.

Reason Code: 200

The new record.

The media type is application/json.

Example Value

{
  "created": "2023-12-14T09:51:05.435Z",
  "createdBy": "string",
  "updated": "2023-12-14T09:51:05.435Z",
  "updatedBy": "string",
  "id": <id>,
  "credentialId": "string",
  "description": "string",
  "url": "string",
  "webhookId": "string",
  "webhookType": "STATUS_NOTIFICATION_V1"
}

Schema — Webhook

The following table describes the elements of a webhook used to send delivery status notifications to an external service.

Table 4-88 Webhook — Object

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
credentialId	Yes	string(32)	The credential ID.
description	NA	string(256)	The webhook description, if one has been defined.
url	Yes	string(1024)	The URL for the webhook.
webhookId	Yes	string(32)	The webhook ID. Webhook IDs must contain only letters, numbers, and underscores.
webhookType	Yes	string	Enum: STATUS_NOTIFICATION_V1, STATUS_NOTIFICATION_V2

Reason Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

The table below describes the elements of the Mapper Error Data object.

Table 4-89 Mapper Error Data — Object

Element Name	Required	Data Type	Description
column	NA	integer <int32>	The JSON file column number the error occurred on if known
line	NA	integer <int32>	The JSON file line number the error occurred on if known
errorCode	NA	integer <int32>	A numeric identifier for the type of error
errorMessage	NA	string	The unlocalized error message
moreInfo	NA	object	Additional information pertaining to the error
field	NA	string	The field. This is the last part of the path
value	NA	string	The JSON value that caused the error if known
errorType	NA	string	enum: INTEGRATION, INTERNAL, MAPPING, PARSING, VALIDATION An enumeration of specific known error types.

The following table describes the elements of the additional information pertaining to the error.

Table 4-90 More Info — Object

Element Name	Required	Data Type	Description
code	NA	string	A code describing the error.
description	NA	string	An unlocalizable description describing the error.

Reason Code: 409

The record already exists or a related entity was not found.

Reason Code: 500

An error occurred during persistence or the request failed for some other reason.

Queries for Webhook Records — GET

This section describes the Queries for Webhook Records API. This API returns a list of records matching the provided criteria.

Method

GET

URL

/api/delivery/v5/webhook

Allowed Scope(s)

webhook-rw

Request

This section describes the request parameters.

Table 4-91 Queries for Webhook Records— Request Parameters

Parameter	Required	Data Type	Description
where	NA	object (query)	A JSON object containing query parameters for filtering results. Fields to be filtered on may be provided in the form of a dot-notated path named for the fields known to this resource, that is a delimited field named "child.id" would filter by the entity field of this resource named "child" and that entity has a field named "id". Querying is supported in 3 ways. If a single value is provided, it is treated as a baseline. If the single value is a character type, then the value is used as the basis for a "like" or startsWith-type comparison, for example {"child.name":"Jo"} would match Joe, John, and so on. For all other types, it serves as the lower bound of a >= comparison, {"minAmount":100.00}. If an array is provided, the values within it are treated as "equals" or "in" values depending upon the element count, for example {"id":[1, 2, 3]}. If an object is provided, fields named "from" and "to" within the object, will serve as lower and/or upper bounds for a range-based query, for example {"id":{"from":0,"to":100}}, a field named "singleValue" can be used to follow the single value pattern discussed above, a field named "in" can be used to follow the array pattern discussed above, or a field named "fieldPath" can be used to specify the path of a related field. Additionally, a field named "caseInsensitive" can be used to enable case-insensitive querying of character-based fields and a field named "invert" can be used to invert a predicate (that is as a NOT). Combining of criteria in "and" and "or" blocks is supported by providing specially named properties with names beginning with '"@and"' and '"@or"' with JSON object values. These can be used directly within the body for criteria grouping purposes, and also nested within each other. When using multiple @and/@or groupings within a given object, take care to suffix them with additional characters (that is '"@and1"', '"@and2"', and so on) to ensure that they are uniquely named since any duplicates will be eliminated.
orderBy	NA	string (query)	A comma-delimited list of fields used to determine result ordering or a JSON array of complex sorting criteria. When supplied as strings, names are provided in the same format as the where argument - optionally followed by "asc" (default) or "desc" to control order direction. When supplied as a JSON array, a String fieldName field must be included in the object. Optional String order (asc or desc) and boolean caseInsensitive fields may also be provided.
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.
limit	NA	integer($int32) (query)	Provides a maximum number of records to be returned.
offset	NA	integer($int32) (query)	Provides the zero-based value for the position of the first value to be returned.

Responses

This section describes the responses of the Queries for Webhook Records API.

Response Code: 200

The requested records.

The media type is application/json.

Example Value

[
  {
    "created": "2023-12-14T13:29:34.113Z",
    "createdBy": "string",
    "updated": "2023-12-14T13:29:34.113Z",
    "updatedBy": "string",
    "id": <id>,
    "credentialId": "string",
    "description": "string",
    "url": "string",
    "webhookId": "string",
    "webhookType": "STATUS_NOTIFICATION_V1"
  }
]

Schema — Webhook

The following table describes the elements of a webhook used to send delivery status notifications to an external service.

Table 4-92 Webhook — Object

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
credentialId	Yes	string(32)	The credential ID.
description	NA	string(256)	The webhook description, if one has been defined.
url	Yes	string(1024)	The URL for the webhook.
webhookId	Yes	string(32)	The webhook ID. Webhook IDs must contain only letters, numbers, and underscores.
webhookType	Yes	string	Enum: STATUS_NOTIFICATION_V1, STATUS_NOTIFICATION_V2

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Performs a Bulk Action using a Collection of Webhook — POST

This section describes the Performs a Bulk Action using a Collection of Webhook API. This API returns a list of records to be loaded.

Method

POST

URL

/api/delivery/v5/webhook/bulk

Allowed Scope(s)

webhook-rw

Request

This section describes the request parameters.

The request body is application/json.

Table 4-93 Performs a Bulk Action using a Collection of Webhook — Request Parameters

Parameter	Required	Data Type	Description
action	NA	string (query)	Provides an action to be used performing the bulk operation. If not specified, the default of ADD_OR_UPDATE is used. Available values: ADD, ADD_OR_UPDATE, DELETE, UPDATE

Example Value

[
  {
    "created": "2023-12-14T13:57:12.105Z",
    "createdBy": "string",
    "updated": "2023-12-14T13:57:12.105Z",
    "updatedBy": "string",
    "id": <id>,
    "credentialId": "string",
    "description": "string",
    "url": "string",
    "webhookId": "string",
    "webhookType": "STATUS_NOTIFICATION_V1"
  }
]

Schema — Webhook

The following table describes the elements of a webhook used to send delivery status notifications to an external service.

Table 4-94 Webhook — Object

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
credentialId	Yes	string(32)	The credential ID.
description	NA	string(256)	The webhook description, if one has been defined.
url	Yes	string(1024)	The URL for the webhook.
webhookId	Yes	string(32)	The webhook ID. Webhook IDs must contain only letters, numbers, and underscores.
webhookType	Yes	string	Enum: STATUS_NOTIFICATION_V1, STATUS_NOTIFICATION_V2

Responses

This section describes the responses of the Performs a Bulk Action using a Collection of Webhook API.

Response Code: 200

The result of the loading operation.

The media type is application/json.

Example Value

{
  "errorRecords": [
    {
      "index": 0,
      "error": "CONFLICT"
    }
  ],
  "successCount": 0
}

Schema — Bulk Operation Result

The following table describes the elements of a Bulk Operation, describing the result of a bulk operation.

Table 4-95 Bulk Operation Result — Object

Element Name	Required	Data Type	Description
errorRecords	NA	object	A list of ErrorRecord objects describing any records which were not successfully processed.
successCount	NA	integer($int32)	The count of the records which were successfully processed.

The following table describes an object describing an error which occurred during a bulk operation.

Table 4-96 Error Record— Object

Element Name	Required	Data Type	Description
index	NA	integer($int32)	The 0-based index of the associated record which was not processed.
error	NA	string	An enumeration describing the result of a bulk action which was not successfully completed. CONFLICT - The record was provided with criteria which conflicts with another record. DOES_NOT_EXIST - The record was provided with an action which required it to exist, but the record was not found. ALREADY_EXISTS - The record was provided with an action which required it not to exist, but the record was found. RELATED_DOES_NOT_EXIST - The record was provided without a required related relationship. INVALID - The record was invalid. Cases for this include: The record was provided as an ADD but included an ID. The record was provided as a DELETE or UPDATE but lacked an ID. The record was provided with an illegal/invalid field value. UNKNOWN - Some other unexpected exception occurred. Enum: [ CONFLICT, DOES_NOT_EXIST, ALREADY_EXISTS, RELATED_DOES_NOT_EXIST, INVALID, UNKNOWN ]

Response Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

For more information about the Mapper Error Data schema, see the Schema — Mapper Error Data section.

Reason Code: 413

Too many records were provided.

Reason Code: 500

An error occurred during persistence or the request failed for some other reason.

Queries for Webhook Records/Count — GET

This section describes the Queries for Webhook Records/Count API. This API returns a count of records matching the provided criteria.

Method

GET

URL

/api/delivery/v5/webhook/count

Allowed Scope(s)

webhook-rw

Request

This section describes the request parameters.

Table 4-97 Queries for Webhook Records/Count — Request Parameters

Parameter	Required	Data Type	Description
where	NA	object (query)	A JSON object containing query parameters for filtering results. Fields to be filtered on may be provided in the form of a dot-notated path named for the fields known to this resource, i.e. a delimited field named "child.id" would filter by the entity field of this resource named "child" and that entity has a field named "id". Querying is supported in 3 ways. If a single value is provided, it is treated as a baseline. If the single value is a character type, then the value is used as the basis for a "like" or startsWith-type comparison, for example {"child.name":"Jo"} would match Joe, John, and so on. For all other types, it serves as the lower bound of a >= comparison, {"minAmount":100.00}. If an array is provided, the values within it are treated as "equals" or "in" values depending upon the element count, for example {"id":[1, 2, 3]}. If an object is provided, fields named "from" and "to" within the object, will serve as lower and/or upper bounds for a range-based query, for example {"id":{"from":0,"to":100}}, a field named "singleValue" can be used to follow the single value pattern discussed above, a field named "in" can be used to follow the array pattern discussed above, or a field named "fieldPath" can be used to specify the path of a related field. Additionally, a field named "caseInsensitive" can be used to enable case-insensitive querying of character-based fields and a field named "invert" can be used to invert a predicate (that is as a NOT). Combining of criteria in "and" and "or" blocks is supported by providing specially named properties with names beginning with '"@and"' and '"@or"' with JSON object values. These can be used directly within the body for criteria grouping purposes, and also nested within each other. When using multiple @and/@or groupings within a given object, take care to suffix them with additional characters (that is '"@and1"', '"@and2"', and so on) to ensure that they are uniquely named since any duplicates will be eliminated.

Responses

This section describes the responses of the Queries for Webhook Records/Count API.

Response Code: 200

The count of requested records.

The media type is application/json.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Get a Webhook — GET

This section describes the Get a Webhook API.

Method

GET

URL

/api/delivery/v5/webhook/{id}

Allowed Scope(s)

webhook-rw

Request

This section describes the request parameters.

Table 4-98 Get a Webhook— Request Parameters

Parameter	Required	Data Type	Description
id	yes	integer($int64) (path)	ID
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.

Responses

This section describes responses of the Get a Webhook API.

Response Code: 200

The requested record.

The media type is applicaton/json.

Example Value

{
  "created": "2024-06-05T08:47:32.184Z",
  "createdBy": "string",
  "updated": "2024-06-05T08:47:32.184Z",
  "updatedBy": "string",
  "id": <id>,
  "credentialId": "string",
  "description": "string",
  "url": "string",
  "webhookId": "string",
  "webhookType": "STATUS_NOTIFICATION_V1"
}

Schema — Webhook

The following table describes the elements of a webhook used to send delivery status notifications to an external service.

Table 4-99 Webhook — Object

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
credentialId	Yes	string(32)	The credential ID.
description	NA	string(256)	The webhook description, if one has been defined.
url	Yes	string(1024)	The URL for the webhook.
webhookId	Yes	string(32)	The webhook ID. Webhook IDs must contain only letters, numbers, and underscores.
webhookType	Yes	string	Enum: STATUS_NOTIFICATION_V1, STATUS_NOTIFICATION_V2

Reason Code: 404

The record could not be found.

Reason Code: 500

An error occurred during persistence or the request failed for some other reason.

Update a Webhook — PUT

This section describes the Update a Webhook API.

Method

PUT

URL

/api/delivery/v5/webhook/{id}

Allowed Scope(s)

webhook-rw

Request

This section describes the request parameters.

The request body is application/json.

Table 4-100 Update a Webhook— Request Parameters

Parameter	Required	Data Type	Description
id	yes	integer($int64) (path)	ID
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.

Example Value

{
  "created": "2023-12-15T11:08:18.908Z",
  "createdBy": "string",
  "updated": "2023-12-15T11:08:18.908Z",
  "updatedBy": "string",
  "id": <id>,
  "credentialId": "string",
  "description": "string",
  "url": "string",
  "webhookId": "string",
  "webhookType": "STATUS_NOTIFICATION_V1"
}

Schema — Webhook

The following table describes the elements of a webhook used to send delivery status notifications to an external service.

Table 4-101 Webhook — Object

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
credentialId	Yes	string(32)	The credential ID.
description	NA	string(256)	The webhook description, if one has been defined.
url	Yes	string(1024)	The URL for the webhook.
webhookId	Yes	string(32)	The webhook ID. Webhook IDs must contain only letters, numbers, and underscores.
webhookType	Yes	string	Enum: STATUS_NOTIFICATION_V1, STATUS_NOTIFICATION_V2

Responses

This section describes the responses of the Update a Webhook API.

Reason Code: 200

The updated record.

The media type application/json.

Example Value

{
  "created": "2023-12-15T11:08:18.966Z",
  "createdBy": "string",
  "updated": "2023-12-15T11:08:18.966Z",
  "updatedBy": "string",
  "id": <id>,
  "credentialId": "string",
  "description": "string",
  "url": "string",
  "webhookId": "string",
  "webhookType": "STATUS_NOTIFICATION_V1"
}

Schema — Webhook

The following table describes the elements of a webhook used to send delivery status notifications to an external service.

Table 4-102 Webhook — Object

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
credentialId	Yes	string(32)	The credential ID.
description	NA	string(256)	The webhook description, if one has been defined.
url	Yes	string(1024)	The URL for the webhook.
webhookId	Yes	string(32)	The webhook ID. Webhook IDs must contain only letters, numbers, and underscores.
webhookType	Yes	string	Enum: STATUS_NOTIFICATION_V1, STATUS_NOTIFICATION_V2

Reason Code: 400

The specified ID is not consistent with the provided record, or the provided record is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

The table below describes the elements of the Mapper Error Data object.

Table 4-103 Mapper Error Data — Object

Element Name	Required	Data Type	Description
column	NA	integer <int32>	The JSON file column number the error occurred on if known
line	NA	integer <int32>	The JSON file line number the error occurred on if known
errorCode	NA	integer <int32>	A numeric identifier for the type of error
errorMessage	NA	string	The unlocalized error message
moreInfo	NA	object	Additional information pertaining to the error
field	NA	string	The field. This is the last part of the path
value	NA	string	The JSON value that caused the error if known
errorType	NA	string	enum: INTEGRATION, INTERNAL, MAPPING, PARSING, VALIDATION An enumeration of specific known error types.

The following table describes the elements of the additional information pertaining to the error.

Table 4-104 More Info — Object

Element Name	Required	Data Type	Description
code	NA	string	A code describing the error.
description	NA	string	An unlocalizable description describing the error.

Reason Code: 404

The provided record could not be found to update.

Reason Code: 409

A related record could not be found.

Reason Code: 500

An error occurred during persistence or the request failed for some other reason.

Delete a Webhook — DELETE

This section describes the Delete a Webhook API.

Method

DELETE

URL

/api/delivery/v5/webhook/{id}

Allowed Scope(s)

webhook-rw

Request

This section describes the request parameters.

Table 4-105 Delete a Webhook— Request Parameters

Parameter	Required	Data Type	Description
id	yes	integer($int64) (path)	ID

Responses

This section describes the responses of the Delete a Webhook API.

Response Code: 204

Deletion succeeded.

Response Code: 404

The record could not be found.

Reason Code: 500

An error occurred during persistence or the request failed for some other reason.

Checks If a Webhook Exists — HEAD

This section describes the Checks if a Webhook Exists API.

Method

HEAD

URL

/api/delivery/v5/webhook/{id}

Allowed Scope(s)

webhook-rw

Request

This section describes the request parameters.

Table 4-106 Checks if a Webhook Exists — Request Parameters

Parameter	Required	Data Type	Description
id	yes	integer($int64) (path)	ID

Responses

This section describes the responses of the Checks if a Webhook Exists API.

Response Code: 200

The requested record exists.

Response Code: 404

The record could not be found.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Queries for Webhook Records By Attributes — GET

This section describes the Queries for Webhook Records API. This API returns a list of records matching the provided attributes.

Method

GET

URL

/api/delivery/v5/webhook/byattributes

Allowed Scope(s)

webhook-rw

Request

This section describes the request parameters.

Table 4-107 Queries for Webhook Records By Attributes — Request Parameters

Parameter	Required	Data Type	Description
id	NA	integer($int64) (path)	ID
credentialId	NA	string (query)	credential ID
description	NA	string (query)	description
url	NA	string (query)	URL
webhookId	NA	string (query)	webhook ID
webhookType	NA	string (query)	webhook type; Available values: STATUS_NOTIFICATION_V1, STATUS_NOTIFICATION_V2
orderBy	NA	string (query)	A comma-delimited list of fields used to determine result ordering or a JSON array of complex sorting criteria. When supplied as strings, names are provided in the same format as the where argument - optionally followed by "asc" (default) or "desc" to control order direction. When supplied as a JSON array, a String fieldName field must be included in the object. Optional String order (asc or desc) and boolean caseInsensitive fields may also be provided.
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.
limit	NA	integer ($int32) (query)	Provides a maximum number of records to be returned.
offset	NA	integer ($int32) (query)	Provides the zero-based value for the position of the first value to be returned.

Responses

This section describes the responses of the Queries for Webhook Records By Attributes API.

Response Code: 200

The requested record exists.

The media type is application/json.

Example Value

[
  {
    "created": "2023-12-19T13:41:32.765Z",
    "createdBy": "string",
    "updated": "2023-12-19T13:41:32.765Z",
    "updatedBy": "string",
    "id": <id>,
    "credentialId": "string",
    "description": "string",
    "url": "string",
    "webhookId": "string",
    "webhookType": "STATUS_NOTIFICATION_V1"
  }
]

Schema — Webhook

The following table describes the elements of a webhook used to send delivery status notifications to an external service.

Table 4-108 Webhook — Object

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
credentialId	Yes	string(32)	The credential ID.
description	NA	string(256)	The webhook description, if one has been defined.
url	Yes	string(1024)	The URL for the webhook.
webhookId	Yes	string(32)	The webhook ID. Webhook IDs must contain only letters, numbers, and underscores.
webhookType	Yes	string	Enum: STATUS_NOTIFICATION_V1, STATUS_NOTIFICATION_V2

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Data Retention Configuration Service

This section describes the Data Retention Configuration Service.

Add a New DataRetentionConfig — POST

This section describes the Add a New DataRetentionConfig API.

Method

POST

URL

/api/job/v5/dataretentionconfig

Allowed Scope(s)

job-rw

Request

This section describes the request parameters.

The request body is application/json.

The ModelField is null.

Table 4-109 Add a New DataRetentionConfig — Request Parameters

Parameter	Required	Data Type	Description
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.

Example Value

{
  "created": "2024-06-05T06:49:20.451Z",
  "createdBy": "string",
  "updated": "2024-06-05T06:49:20.451Z",
  "updatedBy": "string",
  "id": <id>,
  "dataType": "DELIVERY",
  "days": 99999999,
  "triggerHour": 23
}

Schema — DataRetention Configuration

The following table describes the elements of a configuration value used to determine retention for a piece of information.

Table 4-110 Schema — DataRetention Configuration

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
dataType	Yes	string	The type of retained data. Enum: DELIVERY, QUOTE
days	NA	integer($int32)	The number of days to retain data of the assigned type.
triggerHour	Yes	integer($int32)	The hour each day, in UTC, when retained data beyond the retention interval should be removed.

Responses

This section describes the responses of the Add a New DataRetention Configuration API.

Reason Code: 200

The new record.

The media type is application/json.

Example Value

{
  "created": "2024-06-05T06:49:20.454Z",
  "createdBy": "string",
  "updated": "2024-06-05T06:49:20.454Z",
  "updatedBy": "string",
  "id": <id>,
  "dataType": "DELIVERY",
  "days": 99999999,
  "triggerHour": 23
}

Schema — DataRetention Configuration

The following table describes the elements of a configuration value used to determine retention for a piece of information.

Table 4-111 Schema — DataRetention Configuration

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
dataType	Yes	string	The type of retained data. Enum: DELIVERY, QUOTE
days	NA	integer($int32)	The number of days to retain data of the assigned type.
triggerHour	Yes	integer($int32)	The hour each day, in UTC, when retained data beyond the retention interval should be removed.

Reason Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

The table below describes the elements of the Mapper Error Data object.

Table 4-112 Mapper Error Data — Object

Element Name	Required	Data Type	Description
column	NA	integer <int32>	The JSON file column number the error occurred on if known
line	NA	integer <int32>	The JSON file line number the error occurred on if known
errorCode	NA	integer <int32>	A numeric identifier for the type of error
errorMessage	NA	string	The unlocalized error message
moreInfo	NA	object	Additional information pertaining to the error
field	NA	string	The field. This is the last part of the path
value	NA	string	The JSON value that caused the error if known
errorType	NA	string	enum: INTEGRATION, INTERNAL, MAPPING, PARSING, VALIDATION An enumeration of specific known error types.

The following table describes the elements of the additional information pertaining to the error.

Table 4-113 More Info — Object

Element Name	Required	Data Type	Description
code	NA	string	A code describing the error.
description	NA	string	An unlocalizable description describing the error.

Reason Code: 409

The record already exists or a related entity was not found.

Reason Code: 500

An error occurred during persistence or the request failed for some other reason.

Queries for DataRetention Configuration Records — GET

This section describes the Queries for DataRetention Configuration Records API. This API returns a list of records matching the provided criteria.

Method

GET

URL

/api/job/v5/dataretentionconfig

Allowed Scope(s)

job-rw

Request

This section describes the request parameters.

Table 4-114 Queries for DataRetention Configuration Records — Request Parameters

Parameter	Required	Data Type	Description
where	NA	object (query)	A JSON object containing query parameters for filtering results. Fields to be filtered on may be provided in the form of a dot-notated path named for the fields known to this resource, that is a delimited field named "child.id" would filter by the entity field of this resource named "child" and that entity has a field named "id". Querying is supported in 3 ways. If a single value is provided, it is treated as a baseline. If the single value is a character type, then the value is used as the basis for a "like" or startsWith-type comparison, for example {"child.name":"Jo"} would match Joe, John, and so on. For all other types, it serves as the lower bound of a >= comparison, {"minAmount":100.00}. If an array is provided, the values within it are treated as "equals" or "in" values depending upon the element count, for example {"id":[1, 2, 3]}. If an object is provided, fields named "from" and "to" within the object, will serve as lower and/or upper bounds for a range-based query, for example {"id":{"from":0,"to":100}}, a field named "singleValue" can be used to follow the single value pattern discussed above, a field named "in" can be used to follow the array pattern discussed above, or a field named "fieldPath" can be used to specify the path of a related field. Additionally, a field named "caseInsensitive" can be used to enable case-insensitive querying of character-based fields and a field named "invert" can be used to invert a predicate (that is as a NOT). Combining of criteria in "and" and "or" blocks is supported by providing specially named properties with names beginning with '"@and"' and '"@or"' with JSON object values. These can be used directly within the body for criteria grouping purposes, and also nested within each other. When using multiple @and/@or groupings within a given object, take care to suffix them with additional characters (that is '"@and1"', '"@and2"', and so on) to ensure that they are uniquely named since any duplicates will be eliminated.
orderBy	NA	string (query)	A comma-delimited list of fields used to determine result ordering or a JSON array of complex sorting criteria. When supplied as strings, names are provided in the same format as the where argument - optionally followed by "asc" (default) or "desc" to control order direction. When supplied as a JSON array, a String fieldName field must be included in the object. Optional String order (asc or desc) and boolean caseInsensitive fields may also be provided.
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.
limit	NA	integer($int32) (query)	Provides a maximum number of records to be returned.
offset	NA	integer($int32) (query)	Provides the zero-based value for the position of the first value to be returned.

Responses

This section describes the responses of the Queries for DataRetention Configuration Records API.

Response Code: 200

The requested records.

The media type is application/json.

Example Value

[
  {
    "created": "2023-12-14T13:29:34.113Z",
    "createdBy": "string",
    "updated": "2023-12-14T13:29:34.113Z",
    "updatedBy": "string",
    "id": <id>,
    "credentialId": "string",
    "description": "string",
    "url": "string",
    "webhookId": "string",
    "webhookType": "STATUS_NOTIFICATION_V1"
  }
]

Schema — DataRetention Configuration

The following table describes the elements of a configuration value used to determine retention for a piece of information.

Table 4-115 Schema — DataRetention Configuration

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
dataType	Yes	string	The type of retained data. Enum: DELIVERY, QUOTE
days	NA	integer($int32)	The number of days to retain data of the assigned type.
triggerHour	Yes	integer($int32)	The hour each day, in UTC, when retained data beyond the retention interval should be removed.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Queries for DataRetention Configuration Records/Count — GET

This section describes the Queries for DataRetention Configuration Records/Count API. This API returns a count of records matching the provided criteria.

Method

GET

URL

/api/job/v5/dataretentionconfig/count

Allowed Scope(s)

job-rw

Request

This section describes the request parameters.

Table 4-116 Queries for DataRetention Configuration Records/Count — Request Parameters

Parameter	Required	Data Type	Description
where	NA	object (query)	A JSON object containing query parameters for filtering results. Fields to be filtered on may be provided in the form of a dot-notated path named for the fields known to this resource, i.e. a delimited field named "child.id" would filter by the entity field of this resource named "child" and that entity has a field named "id". Querying is supported in 3 ways. If a single value is provided, it is treated as a baseline. If the single value is a character type, then the value is used as the basis for a "like" or startsWith-type comparison, for example {"child.name":"Jo"} would match Joe, John, and so on. For all other types, it serves as the lower bound of a >= comparison, {"minAmount":100.00}. If an array is provided, the values within it are treated as "equals" or "in" values depending upon the element count, for example {"id":[1, 2, 3]}. If an object is provided, fields named "from" and "to" within the object, will serve as lower and/or upper bounds for a range-based query, for example {"id":{"from":0,"to":100}}, a field named "singleValue" can be used to follow the single value pattern discussed above, a field named "in" can be used to follow the array pattern discussed above, or a field named "fieldPath" can be used to specify the path of a related field. Additionally, a field named "caseInsensitive" can be used to enable case-insensitive querying of character-based fields and a field named "invert" can be used to invert a predicate (that is as a NOT). Combining of criteria in "and" and "or" blocks is supported by providing specially named properties with names beginning with '"@and"' and '"@or"' with JSON object values. These can be used directly within the body for criteria grouping purposes, and also nested within each other. When using multiple @and/@or groupings within a given object, take care to suffix them with additional characters (that is '"@and1"', '"@and2"', and so on) to ensure that they are uniquely named since any duplicates will be eliminated.

Responses

This section describes the responses of the Queries for DataRetention Configuration Records/Count API.

Response Code: 200

The count of requested records.

The media type is application/json.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Get a DataRetention Configuration — GET

This section describes the Get a DataRetention Configuration API.

Method

GET

URL

/api/job/v5/dataretentionconfig/{id}

Allowed Scope(s)

job-rw

Request

This section describes the request parameters.

Table 4-117 Get a DataRetention Configuration — Request Parameters

Parameter	Required	Data Type	Description
id	yes	integer($int64) (path)	ID
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.

Responses

This section describes responses of the Get a DataRetention Configuration API.

Response Code: 200

The requested record.

The media type is applicaton/json.

Example Value

{
  "created": "2024-06-05T08:06:57.246Z",
  "createdBy": "string",
  "updated": "2024-06-05T08:06:57.246Z",
  "updatedBy": "string",
  "id": <id>,
  "dataType": "DELIVERY",
  "days": 99999999,
  "triggerHour": 23
}

Schema — DataRetention Configuration

The following table describes the elements of a configuration value used to determine retention for a piece of information.

Table 4-118 Schema — DataRetention Configuration

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
dataType	Yes	string	The type of retained data. Enum: DELIVERY, QUOTE
days	NA	integer($int32)	The number of days to retain data of the assigned type.
triggerHour	Yes	integer($int32)	The hour each day, in UTC, when retained data beyond the retention interval should be removed.

Reason Code: 404

The record could not be found.

Reason Code: 500

An error occurred during persistence or the request failed for some other reason.

Update a DataRetention Configuration — PUT

This section describes the Update a DataRetention Configuration API.

Method

PUT

URL

/api/job/v5/dataretentionconfig/{id}

Allowed Scope(s)

job-rw

Request

This section describes the request parameters.

The request body is application/json.

Table 4-119 Update a DataRetention Configuration — Request Parameters

Parameter	Required	Data Type	Description
id	yes	integer($int64) (path)	ID
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (that is "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.

Example Value

{
  "created": "2024-06-05T08:50:00.771Z",
  "createdBy": "string",
  "updated": "2024-06-05T08:50:00.771Z",
  "updatedBy": "string",
  "id": <id>,
  "dataType": "DELIVERY",
  "days": 99999999,
  "triggerHour": 23
}

Schema — DataRetention Configuration

The following table describes the elements of a configuration value used to determine retention for a piece of information.

Table 4-120 Schema — DataRetention Configuration

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
dataType	Yes	string	The type of retained data. Enum: DELIVERY, QUOTE
days	NA	integer($int32)	The number of days to retain data of the assigned type.
triggerHour	Yes	integer($int32)	The hour each day, in UTC, when retained data beyond the retention interval should be removed.

Responses

This section describes the responses of the Update a DataRetention Configuration API.

Reason Code: 200

The updated record.

The media type application/json.

Example Value

{
  "created": "2024-06-05T08:50:00.773Z",
  "createdBy": "string",
  "updated": "2024-06-05T08:50:00.773Z",
  "updatedBy": "string",
  "id": <id>,
  "dataType": "DELIVERY",
  "days": 99999999,
  "triggerHour": 23
}

Schema — DataRetention Configuration

The following table describes the elements of a configuration value used to determine retention for a piece of information.

Table 4-121 Schema — DataRetention Configuration

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
dataType	Yes	string	The type of retained data. Enum: DELIVERY, QUOTE
days	NA	integer($int32)	The number of days to retain data of the assigned type.
triggerHour	Yes	integer($int32)	The hour each day, in UTC, when retained data beyond the retention interval should be removed.

Reason Code: 400

The specified ID is not consistent with the provided record, or the provided record is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]

Schema — Mapper Error Data

The table below describes the elements of the Mapper Error Data object.

Table 4-122 Mapper Error Data — Object

Element Name	Required	Data Type	Description
column	NA	integer <int32>	The JSON file column number the error occurred on if known
line	NA	integer <int32>	The JSON file line number the error occurred on if known
errorCode	NA	integer <int32>	A numeric identifier for the type of error
errorMessage	NA	string	The unlocalized error message
moreInfo	NA	object	Additional information pertaining to the error
field	NA	string	The field. This is the last part of the path
value	NA	string	The JSON value that caused the error if known
errorType	NA	string	enum: INTEGRATION, INTERNAL, MAPPING, PARSING, VALIDATION An enumeration of specific known error types.

The following table describes the elements of the additional information pertaining to the error.

Table 4-123 More Info — Object

Element Name	Required	Data Type	Description
code	NA	string	A code describing the error.
description	NA	string	An unlocalizable description describing the error.

Reason Code: 404

The provided record could not be found to update.

Reason Code: 409

A related record could not be found.

Reason Code: 500

An error occurred during persistence or the request failed for some other reason.

Delete a DataRetention Configuration — DELETE

This section describes the Delete a DataRetention Configuration API.

Method

DELETE

URL

/api/job/v5/dataretentionconfig/{id}

Allowed Scope(s)

job-rw

Request

This section describes the request parameters.

Table 4-124 Delete a Webhook— Request Parameters

Parameter	Required	Data Type	Description
id	yes	integer($int64) (path)	ID

Responses

This section describes the responses of the Delete a DataRetention Configuration API.

Response Code: 204

Deletion succeeded.

Response Code: 404

The record could not be found.

Reason Code: 500

An error occurred during persistence or the request failed for some other reason.

Checks If a DataRetention Configuration Exists — HEAD

This section describes the Checks if a DataRetention Configuration Exists API.

Method

HEAD

URL

/api/job/v5/dataretentionconfig/{id}

Allowed Scope(s)

job-rw

Request

This section describes the request parameters.

Table 4-125 Checks if a DataRetention Configuration Exists — Request Parameters

Parameter	Required	Data Type	Description
id	yes	integer($int64) (path)	ID

Responses

This section describes the responses of the Checks if a DataRetention Configuration Exists API.

Response Code: 200

The requested record exists.

Response Code: 404

The record could not be found.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Queries for DataRetention Configuration Records By Attributes — GET

This section describes the Queries for DataRetention Configuration Records API. This API returns a list of records matching the provided attributes.

Method

GET

URL

/api/job/v5/dataretentionconfig/byattributes

Allowed Scope(s)

job-rw

Request

This section describes the request parameters.

Table 4-126 Queries for DataRetention Configuration Records By Attributes — Request Parameters

Parameter	Required	Data Type	Description
id	NA	integer($int64) (query)	ID
datatype	NA	string (query)	Available values : DELIVERY, QUOTE
days	NA	integer($int32) (query)	days
triggerHour	NA	integer($int32) (query)	trigger hour
orderBy	NA	string (query)	A comma-delimited list of fields used to determine result ordering or a JSON array of complex sorting criteria. When supplied as strings, names are provided in the same format as the where argument - optionally followed by "asc" (default) or "desc" to control order direction. When supplied as a JSON array, a String fieldName field must be included in the object. Optional String order (asc or desc) and boolean caseInsensitive fields may also be provided.
expands	NA	string (query)	A comma-delimited list of relationship paths, in dot-notated path form (i.e. "child.line" would return the relationship named "child", and its child relationship named "line"), on the resulting model which should be included in the response or "all" if all associated relationships should be included.
limit	NA	integer($int32) (query)	Provides a maximum number of records to be returned.
offset	NA	integer($int32) (query)	Provides the zero-based value for the position of the first value to be returned.

Responses

This section describes the responses of the Queries for DataRetention Configuration Records By Attributes API.

Response Code: 200

The requested record.

The media type is application/json.

Example Value

[
  {
    "created": "2024-06-05T09:43:29.656Z",
    "createdBy": "string",
    "updated": "2024-06-05T09:43:29.656Z",
    "updatedBy": "string",
    "id": <id>,
    "dataType": "DELIVERY",
    "days": 99999999,
    "triggerHour": 23
  }
]

Schema — DataRetention Configuration

The following table describes the elements of a configuration value used to determine retention for a piece of information.

Table 4-127 Schema — DataRetention Configuration

Element Name	Required	Data Type	Description
created	NA	string($date-time)	The timestamp at which the record was created.
createdBy	NA	string	The identity of the user who created the record.
updated	NA	string($date-time)	The timestamp at which the record was last updated.
updatedBy	NA	string	The identity of the user who last updated the record.
id	NA	integer($int64)	ID
dataType	Yes	string	The type of retained data. Enum: DELIVERY, QUOTE
days	NA	integer($int32)	The number of days to retain data of the assigned type.
triggerHour	Yes	integer($int32)	The hour each day, in UTC, when retained data beyond the retention interval should be removed.

Response Code: 500

An error occurred during persistence or the request failed for some other reason.

Error Handling

When limits have been specified on fields, they are enforced on models and service models that are accepted by the application. When a limit is defined, it may be enforced via Java Bean Validation annotations or by the database itself.

Bean Validations

Limits enforced on fields, which violated, result in a response containing a list of "MapperErrorData" objects. These objects include:

• If defined, an error code

• An error message

• If appropriate, the value associated with the error

• If appropriate, the name of the field associated with the error

• The type of the error, which will be VALIDATION (an enumerated value) in this case

Error Representation

Errors related to validation conditions are always represented to the user as an HTTP 400 including an array of one or more MapperErrorData objects. MapperErrorData objects include the following fields:

Table 4-128 Fields — MapperErrorData Objects

Field	Description
column	Returns the JSON file column number the error occurred on, if known.
line	Returns the JSON file line number the error occurred on, if known.
errorCode	Returns the application-specific error code associated with the error, if known.
errorMessage	Returns the error message (not localized).
field	Returns an identifier of the associated field if known.  This will be a path within a provided object, or some other field identifier.
value	Returns the JSON value that caused the error if known.
errorType	Return the error type. (one of INTEGRATION, INTERNAL, MAPPING, PARSING, VALIDATION)
targetType	Returns the type the system expected the JSON node to be, if known.

Error Codes

A number of standard error codes are included in the services to deal with various conditions, their identifiers and descriptive message templates and include the following:

• 100 - Add entity was null.

• 101 - Add entity must not include an ID.

• 102 - <0> already exists.

• 103 - Related entity was not found.

• 104 - A constraint violation occurred on this, or a descendant, entity.

• 105 - Add request <0> ID must be greater than zero.

• 106 - <0> parent was not found.

• 107 - Child could not be added to <0>.

• 108 - <0> was not found.

• 109 - Bulk request was null.

• 110 - This endpoint accepts, at most, 1000 records.

• 111 - A limit must be specified when specifying an offset.

• 112 - Update entity was null.

• 113 - Update request ID does not match entity ID.

• 114 - Delete failed due to dependent data.

• 115 - Persist failed due to conflict on <0>.

• 116 - Update failed due to conflict on <0>.

• 117 - JSON parameter <0> does not match a field definition for entity.

• 118 - OrderBy parameter <0> does not match a field definition for entity.

• 119 - OrderBy order <0> is not valid.

• 120 - Unable to delete.  At least one <0> is required.

• 199 - An error occurred during persistence.

• 200 - A JSON mapping error occurred.

• 201 - A JSON parsing error occurred.

• 202 - A validation error occurred.

• 203 - An invalid value was specified.

• 999 - Failed

Collect and Receive Error Codes

Additionally, Collect and Receive specific error codes have been defined. These codes may be returned to reflect transitive errors reaching carriers (transitive errors not detailed below utilize 999 from the list above):

• 1000 - Request could not be accepted as provided. (HTTP 400)

• 1002 - Request was not authorized. (HTTP 401)

• 1003 - A resource could not be found. (HTTP 404)

• 1004 - Too many requests have been submitted. (HTTP 429)

• 1005 - A server error occurred. (HTTP 500)

• 1006 - Service was unavailable. (HTTP 503)

• 1007 - Invalid or Missing Address

• 1008 - Invalid Pickup Time

• 1009 - Invalid Dropoff Time

• 1010 - Insufficient Couriers

• 1011 - Invalid Quote

• 1012 - Account Error

• 1013 - Request Timeout

• 1014 - Duplicate Delivery

• 1015 - Account not found

• 1016 - The entity was not in a status compatible with the requested action.

• 1017 - The delivery can not be canceled.

• 1018 - Delivery not found.