5 Foundation Service

This section describes the Foundation Service. The Foundation Service includes:

• Location Service

• Package Dimension Service

  Note:

  The Package Dimension Service can be used to add, replace, edit or delete the default values.
• Reason Code Service

  Note:

  The Reason Code Service can be used to add, replace, edit or delete the default values.

The Foundation Service contains the following OpenAPI endpoint, which can be used to obtain the specification for the services it provides.

api/foundation/openapi

Location Service

This section describes the Location Service.

Add a New Location — POST

This section describes the Add a New Location API. Use this service to add a new location record. This service is commonly used to set up Locations for the Collect and Receive User Interface to leverage when creating deliveries and viewing deliveries.

Method

POST

URL

/api/foundation/v1/location

Allowed Scope(s)

foundation-r
foundation-rw

Request

This section describes the request parameters.

The request body is application/json.

The ModelField is null.

Table 5-1 Queries for Webhook Records By Attributes — Request Parameters

Parameter	Required	Data Type	Description
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.

Example Value

{
  "created": "2024-07-24T15:57:18.266Z",
  "createdBy": "string",
  "updated": "2024-07-24T15:57:18.266Z",
  "updatedBy": "string",
  "id": <id>,
  "address1": "string",
  "address2": "string",
  "address3": "string",
  "address4": "string",
  "addressType": "RESIDENTIAL",
  "apartment": "string",
  "city": "string",
  "country": "string",
  "deliveryInstructions": "string",
  "emailAddress": "string",
  "firstName": "string",
  "lastName": "string",
  "latitude": 999999999,
  "locTypeDescription": "string",
  "locationCode": "string",
  "locationDesc": "string",
  "longitude": 999999999,
  "operatingHours": "string",
  "phoneNumber": "string",
  "postalCode": "string",
  "state": "string",
  "timezone": "string"
}
 "string"
}

Schema — Location

This section describes the Location schema.

Table 5-2 Location — 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
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	The address type identifier. Enum: RESIDENTIAL, BUSINESS
apartment	NA	string(254)	The apartment at the location.
city	Yes	string(254)	The city of the location.
country	Yes	string(254)	The ISO-3166 country code.
deliveryInstructions	NA	string(254)	Instructions for courier providers when picking up/delivering.
emailAddress	NA	string(254)	The email address.
firstName	NA	string(254)	The first (i.e. given) name.
lastName	NA	string(254)	The last (i.e. family) name.
latitude	NA	number	The latitude of the location.
locTypeDescription	NA	string(40	The type of location (i.e. store, warehouse, office, etc.).
locationCode	Yes	string(10)	The unique code for the location.
locationDesc	Yes	string(254)	The location description.
longitude	NA	number	The longitude of the location.
operatingHours	NA	string(254)	The operating hours of the location.
phoneNumber	NA	string(50)	The phone contact number.
postalCode	NA	string(20)	The postal code of the location.
state	NA	string(254)	The ISO 3166 state, province, or territory code.
timezone	Yes	string(40)	Identifies the timezone by continent/region and area of the user.

Responses

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

Response Code: 200

The new record.

The media type is application/json.

Example Value

{
  "created": "2024-07-24T15:57:18.272Z",
  "createdBy": "string",
  "updated": "2024-07-24T15:57:18.272Z",
  "updatedBy": "string",
  "id": <id>,
  "address1": "string",
  "address2": "string",
  "address3": "string",
  "address4": "string",
  "addressType": "RESIDENTIAL",
  "apartment": "string",
  "city": "string",
  "country": "string",
  "deliveryInstructions": "string",
  "emailAddress": "string",
  "firstName": "string",
  "lastName": "string",
  "latitude": 999999999,
  "locTypeDescription": "string",
  "locationCode": "string",
  "locationDesc": "string",
  "longitude": 999999999,
  "operatingHours": "string",
  "phoneNumber": "string",
  "postalCode": "string",
  "state": "string",
  "timezone": "string"
}

Schema — Location

This section describes the Location schema.

Table 5-3 Location — 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
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	The address type identifier. Enum: RESIDENTIAL, BUSINESS
apartment	NA	string(254)	The apartment at the location.
city	Yes	string(254)	The city of the location.
country	Yes	string(254)	The ISO-3166 country code.
deliveryInstructions	NA	string(254)	Instructions for courier providers when picking up/delivering.
emailAddress	NA	string(254)	The email address.
firstName	NA	string(254)	The first (i.e. given) name.
lastName	NA	string(254)	The last (i.e. family) name.
latitude	NA	number	The latitude of the location.
locTypeDescription	NA	string(40	The type of location (i.e. store, warehouse, office, etc.).
locationCode	Yes	string(10)	The unique code for the location.
locationDesc	Yes	string(254)	The location description.
longitude	NA	number	The longitude of the location.
operatingHours	NA	string(254)	The operating hours of the location.
phoneNumber	NA	string(50)	The phone contact number.
postalCode	NA	string(20)	The postal code of the location.
state	NA	string(254)	The ISO 3166 state, province, or territory code.
timezone	Yes	string(40)	Identifies the timezone by continent/region and area of the user.

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 5-4 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 5-5 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 Location Records — GET

This section describes the Queries for Location Records API. This This service returns a list of location records and associated location details matching the provided criteria.

Method

GET

URL

/api/foundation/v1/location

Allowed Scope(s)

foundation-r

Request

Table 5-6 Queries for Location Records— Request Parameters

where	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, e.g. {"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 (i.e. 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 (i.e. '"@and1"', '"@and2"', and so on) to ensure that they are uniquely named since any duplicates will be eliminated.
orderBy	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.
expand	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	integer($int32) (query)	Provides a maximum number of records to be returned.
offset	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 Count endpoint.

Response Code: 200

The requested records.

The media type is application/json.

Example Value

[
  {
    "created": "2024-07-24T15:59:42.587Z",
    "createdBy": "string",
    "updated": "2024-07-24T15:59:42.587Z",
    "updatedBy": "string",
    "id": <id>,
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "deliveryInstructions": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "latitude": 999999999,
    "locTypeDescription": "string",
    "locationCode": "string",
    "locationDesc": "string",
    "longitude": 999999999,
    "operatingHours": "string",
    "phoneNumber": "string",
    "postalCode": "string",
    "state": "string",
    "timezone": "string"
  }
]

Schema — Location

This section describes the Location schema.

Table 5-7 Location — 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
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	The address type identifier. Enum: RESIDENTIAL, BUSINESS
apartment	NA	string(254)	The apartment at the location.
city	Yes	string(254)	The city of the location.
country	Yes	string(254)	The ISO-3166 country code.
deliveryInstructions	NA	string(254)	Instructions for courier providers when picking up/delivering.
emailAddress	NA	string(254)	The email address.
firstName	NA	string(254)	The first (i.e. given) name.
lastName	NA	string(254)	The last (i.e. family) name.
latitude	NA	number	The latitude of the location.
locTypeDescription	NA	string(40	The type of location (i.e. store, warehouse, office, etc.).
locationCode	Yes	string(10)	The unique code for the location.
locationDesc	Yes	string(254)	The location description.
longitude	NA	number	The longitude of the location.
operatingHours	NA	string(254)	The operating hours of the location.
phoneNumber	NA	string(50)	The phone contact number.
postalCode	NA	string(20)	The postal code of the location.
state	NA	string(254)	The ISO 3166 state, province, or territory code.
timezone	Yes	string(40)	Identifies the timezone by continent/region and area of the user.

Reason Code: 500

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

Performs a Bulk Action Using a Collection of Locations — POST

This section describes the Performs a Bulk Action Using a Collection of Locations API. This service performs a bulk action (Add, Add or Update, Delete, Update) using a Collection of Locations services.

Method

POST

URL

/api/foundation/v1/location/bulk

Allowed Scope(s)

foundation-r
foundation-rw

Request

The request body is application/json.

Requests a lists of records to be loaded.

Table 5-8 Performs a Bulk Action Using a Collection of Locations — 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": "2024-07-24T16:00:54.793Z",
    "createdBy": "string",
    "updated": "2024-07-24T16:00:54.793Z",
    "updatedBy": "string",
    "id": <id>,
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "deliveryInstructions": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "latitude": 999999999,
    "locTypeDescription": "string",
    "locationCode": "string",
    "locationDesc": "string",
    "longitude": 999999999,
    "operatingHours": "string",
    "phoneNumber": "string",
    "postalCode": "string",
    "state": "string",
    "timezone": "string"
  }
]

Schema — Location

This section describes the Location schema.

Table 5-9 Location — 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
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	The address type identifier. Enum: RESIDENTIAL, BUSINESS
apartment	NA	string(254)	The apartment at the location.
city	Yes	string(254)	The city of the location.
country	Yes	string(254)	The ISO-3166 country code.
deliveryInstructions	NA	string(254)	Instructions for courier providers when picking up/delivering.
emailAddress	NA	string(254)	The email address.
firstName	NA	string(254)	The first (i.e. given) name.
lastName	NA	string(254)	The last (i.e. family) name.
latitude	NA	number	The latitude of the location.
locTypeDescription	NA	string(40	The type of location (i.e. store, warehouse, office, etc.).
locationCode	Yes	string(10)	The unique code for the location.
locationDesc	Yes	string(254)	The location description.
longitude	NA	number	The longitude of the location.
operatingHours	NA	string(254)	The operating hours of the location.
phoneNumber	NA	string(50)	The phone contact number.
postalCode	NA	string(20)	The postal code of the location.
state	NA	string(254)	The ISO 3166 state, province, or territory code.
timezone	Yes	string(40)	Identifies the timezone by continent/region and area of the user.

Responses

This section describes the responses of the Performs a Bulk Action Using a Collection of Locations endpoint.

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 5-10 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 5-11 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

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

Table 5-12 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 5-13 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: 413

Too many records were provided.

Reason Code: 500

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

Queries for Location Records/Count — GET

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

Method

GET

URL

/api/foundation/v1/location/count

Allowed Scope(s)

foundation-r

Request

Table 5-14 Queries for Location 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, 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 (i.e. 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 (i.e. '"@and1"', '"@and2"', etc.) to ensure that they are uniquely named since any duplicates will be eliminated

Responses

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

Response Code: 200

The count of the requested records.

The media type is application/json.

Reason Code: 500

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

Get a Location — GET

This section describes the Get a Location API. Use this service to retrieve a specific location record and the associated details.

Method

GET

URL

/api/foundation/v1/location/{id}

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

Table 5-15 Get a Location — Request Parameters

Parameter	Required	Data Type	Description
id	Yes	integer($int64)	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 the responses of the Get a Location API.

Response Code: 200

The requested record.

The media type is application/json.

Example Value

{
  "created": "2024-07-24T16:02:05.369Z",
  "createdBy": "string",
  "updated": "2024-07-24T16:02:05.369Z",
  "updatedBy": "string",
  "id": <id>,
  "address1": "string",
  "address2": "string",
  "address3": "string",
  "address4": "string",
  "addressType": "RESIDENTIAL",
  "apartment": "string",
  "city": "string",
  "country": "string",
  "deliveryInstructions": "string",
  "emailAddress": "string",
  "firstName": "string",
  "lastName": "string",
  "latitude": 999999999,
  "locTypeDescription": "string",
  "locationCode": "string",
  "locationDesc": "string",
  "longitude": 999999999,
  "operatingHours": "string",
  "phoneNumber": "string",
  "postalCode": "string",
  "state": "string",
  "timezone": "string"
}

Schema — Location

This section describes the Location schema.

Table 5-16 Location — 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
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	The address type identifier. Enum: RESIDENTIAL, BUSINESS
apartment	NA	string(254)	The apartment at the location.
city	Yes	string(254)	The city of the location.
country	Yes	string(254)	The ISO-3166 country code.
deliveryInstructions	NA	string(254)	Instructions for courier providers when picking up/delivering.
emailAddress	NA	string(254)	The email address.
firstName	NA	string(254)	The first (i.e. given) name.
lastName	NA	string(254)	The last (i.e. family) name.
latitude	NA	number	The latitude of the location.
locTypeDescription	NA	string(40	The type of location (i.e. store, warehouse, office, etc.).
locationCode	Yes	string(10)	The unique code for the location.
locationDesc	Yes	string(254)	The location description.
longitude	NA	number	The longitude of the location.
operatingHours	NA	string(254)	The operating hours of the location.
phoneNumber	NA	string(50)	The phone contact number.
postalCode	NA	string(20)	The postal code of the location.
state	NA	string(254)	The ISO 3166 state, province, or territory code.
timezone	Yes	string(40)	Identifies the timezone by continent/region and area of the user.

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 Location — PUT

This section describes the Update a Location API. Use this service to update a specific location's attributes.

Method

PUT

URL

/api/foundation/v1/location/{id}

Allowed Scope(s)

foundation-r
foundation-rw

Request

This section describes the request parameters.

The request body is application/json.

Table 5-17 Update a Location — 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-07-24T16:02:58.049Z",
  "createdBy": "string",
  "updated": "2024-07-24T16:02:58.049Z",
  "updatedBy": "string",
  "id": <id>,
  "address1": "string",
  "address2": "string",
  "address3": "string",
  "address4": "string",
  "addressType": "RESIDENTIAL",
  "apartment": "string",
  "city": "string",
  "country": "string",
  "deliveryInstructions": "string",
  "emailAddress": "string",
  "firstName": "string",
  "lastName": "string",
  "latitude": 999999999,
  "locTypeDescription": "string",
  "locationCode": "string",
  "locationDesc": "string",
  "longitude": 999999999,
  "operatingHours": "string",
  "phoneNumber": "string",
  "postalCode": "string",
  "state": "string",
  "timezone": "string"
}

Schema — Location

This section describes the Location schema.

Table 5-18 Location — 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
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	The address type identifier. Enum: RESIDENTIAL, BUSINESS
apartment	NA	string(254)	The apartment at the location.
city	Yes	string(254)	The city of the location.
country	Yes	string(254)	The ISO-3166 country code.
deliveryInstructions	NA	string(254)	Instructions for courier providers when picking up/delivering.
emailAddress	NA	string(254)	The email address.
firstName	NA	string(254)	The first (i.e. given) name.
lastName	NA	string(254)	The last (i.e. family) name.
latitude	NA	number	The latitude of the location.
locTypeDescription	NA	string(40	The type of location (i.e. store, warehouse, office, etc.).
locationCode	Yes	string(10)	The unique code for the location.
locationDesc	Yes	string(254)	The location description.
longitude	NA	number	The longitude of the location.
operatingHours	NA	string(254)	The operating hours of the location.
phoneNumber	NA	string(50)	The phone contact number.
postalCode	NA	string(20)	The postal code of the location.
state	NA	string(254)	The ISO 3166 state, province, or territory code.
timezone	Yes	string(40)	Identifies the timezone by continent/region and area of the user.

Responses

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

Response Code: 200

The updated record.

The media type is application/json.

Example Value

{
  "created": "2024-07-24T16:02:58.056Z",
  "createdBy": "string",
  "updated": "2024-07-24T16:02:58.056Z",
  "updatedBy": "string",
  "id": <id>,
  "address1": "string",
  "address2": "string",
  "address3": "string",
  "address4": "string",
  "addressType": "RESIDENTIAL",
  "apartment": "string",
  "city": "string",
  "country": "string",
  "deliveryInstructions": "string",
  "emailAddress": "string",
  "firstName": "string",
  "lastName": "string",
  "latitude": 999999999,
  "locTypeDescription": "string",
  "locationCode": "string",
  "locationDesc": "string",
  "longitude": 999999999,
  "operatingHours": "string",
  "phoneNumber": "string",
  "postalCode": "string",
  "state": "string",
  "timezone": "string"
}

Schema — Location

This section describes the Location schema.

Table 5-19 Location — 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
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	The address type identifier. Enum: RESIDENTIAL, BUSINESS
apartment	NA	string(254)	The apartment at the location.
city	Yes	string(254)	The city of the location.
country	Yes	string(254)	The ISO-3166 country code.
deliveryInstructions	NA	string(254)	Instructions for courier providers when picking up/delivering.
emailAddress	NA	string(254)	The email address.
firstName	NA	string(254)	The first (i.e. given) name.
lastName	NA	string(254)	The last (i.e. family) name.
latitude	NA	number	The latitude of the location.
locTypeDescription	NA	string(40	The type of location (i.e. store, warehouse, office, etc.).
locationCode	Yes	string(10)	The unique code for the location.
locationDesc	Yes	string(254)	The location description.
longitude	NA	number	The longitude of the location.
operatingHours	NA	string(254)	The operating hours of the location.
phoneNumber	NA	string(50)	The phone contact number.
postalCode	NA	string(20)	The postal code of the location.
state	NA	string(254)	The ISO 3166 state, province, or territory code.
timezone	Yes	string(40)	Identifies the timezone by continent/region and area of the user.

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 5-20 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 5-21 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 Location — DELETE

This section describes the Delete a Location API. Use this service to delete a location record and the associated details.

Method

DELETE

URL

/api/foundation/v1/location/{id}

Allowed Scope(s)

foundation-r
foundation-rw

Request

This section describes the request parameters.

Table 5-22 Delete a Location — Request Parameters

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

Responses

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

Reason Code: 204

Deletion succeeded.

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.

Checks if a Location Exists — HEAD

This section describes the Checks if a Location Exists API.

Method

HEAD

URL

/api/foundation/v1/location/{id}

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

Table 5-23 Checks if a Location 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 Location Exists API.

Reason Code: 200

The requested record exists.

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.

Queries for Location Records by Attributes— GET

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

Method

GET

URL

/api/foundation/v1/location/byattributes

Allowed Scope(s)

foundation-r

Request

Table 5-24 Queries for Location Records by Attributes — Request Parameters

Parameter	Required	Data Type	Description
id	NA	integer($int64) (query)	id
address1	NA	string (query)	address1
address2	NA	string (query)	address2
address3	NA	string (query)	address3
address4	NA	string (query)	address4
addressType	NA	string (query)	Available values : RESIDENTIAL, BUSINESS
city	NA	string (query)	city
country	NA	string (query)	country
deliveryInstructions	NA	string (query)	deliveryInstructions
email	NA	string (query)	email
firstName	NA	string (query)	firstName
lastName	NA	string (query)	lastName
latitude	NA	number (query)	latitude
locTypeDescription	NA	string (query)	locTypeDescription
locationCode	NA	string (query)	locationCode
locationDesc	NA	string (query)	locationDesc
longitude	NA	number (query)	longitude
operatingHours	NA	string (query)	operatingHours
phoneNumber	NA	string (query)	phoneNumber
postalCode	NA	string (query)	postalCode
state	NA	string (query)	state
suite	NA	string (query)	suite
timezone	NA	string (query)	timezone
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 Location Records by Attributes endpoint.

Response Code: 200

The requested records.

The media type is application/json.

Example Value

[
  {
    "created": "2024-07-24T16:05:15.787Z",
    "createdBy": "string",
    "updated": "2024-07-24T16:05:15.787Z",
    "updatedBy": "string",
    "id": <id>,
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "deliveryInstructions": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "latitude": 999999999,
    "locTypeDescription": "string",
    "locationCode": "string",
    "locationDesc": "string",
    "longitude": 999999999,
    "operatingHours": "string",
    "phoneNumber": "string",
    "postalCode": "string",
    "state": "string",
    "timezone": "string"
  }
]

Schema — Location

This section describes the Location schema.

Table 5-25 Location — 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
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	The address type identifier. Enum: RESIDENTIAL, BUSINESS
apartment	NA	string(254)	The apartment at the location.
city	Yes	string(254)	The city of the location.
country	Yes	string(254)	The ISO-3166 country code.
deliveryInstructions	NA	string(254)	Instructions for courier providers when picking up/delivering.
emailAddress	NA	string(254)	The email address.
firstName	NA	string(254)	The first (i.e. given) name.
lastName	NA	string(254)	The last (i.e. family) name.
latitude	NA	number	The latitude of the location.
locTypeDescription	NA	string(40	The type of location (i.e. store, warehouse, office, etc.).
locationCode	Yes	string(10)	The unique code for the location.
locationDesc	Yes	string(254)	The location description.
longitude	NA	number	The longitude of the location.
operatingHours	NA	string(254)	The operating hours of the location.
phoneNumber	NA	string(50)	The phone contact number.
postalCode	NA	string(20)	The postal code of the location.
state	NA	string(254)	The ISO 3166 state, province, or territory code.
timezone	Yes	string(40)	Identifies the timezone by continent/region and area of the user.

Reason Code: 500

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

Package Dimension Service

This section describes the Package Dimension Service.

Note:

The Package Dimension Service can be used to add, replace, edit or delete the default values.

Add a New PackageDimension — POST

This section describes the Add a New PackageDimension API. This service creates a package dimension code which associates a set of dimensions to a package description that can be configured by locale. This is also leveraged by the Collect and Receive user interface to allow users to select a package size description when creating a delivery, instead of entering specific dimensions.

Method

POST

URL

/api/foundation/v1/package/dimension

Allowed Scope(s)

foundation-r
foundation-rw

Request

This section describes the request parameters.

The request body is application/json.

The ModelField is null.

Table 5-26 Add a New PackageDimension — 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.

Responses

This section describes the responses of the Add a PackageDimension API.

Response Code: 200

The new record.

The media type is application/json.

Example Value

{
  "created": "2024-05-29T13:29:25.265Z",
  "createdBy": "string",
  "updated": "2024-05-29T13:29:25.265Z",
  "updatedBy": "string",
  "id": <id>,
  "descriptions": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "height": 9999,
  "length": 9999,
  "packDimensionCode": "string",
  "weight": 10000000000000000,
  "width": 9999
}

Schema — Package Dimension

This section describes the Package Dimension schema.

Table 5-27 Package Dimension — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
height	Yes	integer($int32)	The height of the package in centimeters.
length	Yes	integer($int32)	The length of the package in centimeters.
packDimensionCode	Yes	string	The package dimension code.
weight	Yes	number	The weight of the package in kilograms.
width	Yes	integer($int32)	The width of the package in centimeters.

Table 5-28 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions. For example, { "en-US": "small", "de-DE": "klein", "fr-FR": "petit" }

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 5-29 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 5-30 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 PackageDimension Records— GET

This section describes the Queries for PackageDimension Records API. This service returns a list of package dimension records with associated package dimension details and descriptions matching the provided criteria.

Method

GET

URL

/api/foundation/v1/package/dimension

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

Table 5-31 Queries for PackageDimension 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, 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, 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"
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 PackageDimension Records API.

Response Code: 200

The requested record.

The media type is application/json.

Example Value

[
  {
    "created": "2024-05-28T09:14:28.643Z",
    "createdBy": "string",
    "updated": "2024-05-28T09:14:28.643Z",
    "updatedBy": "string",
    "id": <id>,
    "descriptions": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "height": 9999,
    "length": 9999,
    "packDimensionCode": "string",
    "weight": 10000000000000000,
    "width": 9999
  }
]

Schema — Package Dimension

This section describes the Package Dimension schema.

Table 5-32 Package Dimension — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
height	Yes	integer($int32)	The height of the package in centimeters.
length	Yes	integer($int32)	The length of the package in centimeters.
packDimensionCode	Yes	string	The package dimension code.
weight	Yes	number	The weight of the package in kilograms.
width	Yes	integer($int32)	The width of the package in centimeters.

Table 5-33 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions. For example, { "en-US": "small", "de-DE": "klein", "fr-FR": "petit" }

Reason Code: 500

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

Performs a Bulk Action Using a Collection of PackageDimension — GET

This section describes the Performs a Bulk Action Using a Collection of PackageDimension API. This service performs a bulk action (Add, Add or Update, Delete, Update) using a collection of PackageDimension services.

Method

POST

URL

/api/foundation/v1/package/dimension/bulk

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

The request body is application/json.

A list of records to be loaded.

Table 5-34 Performs a Bulk Action Using a Collection of PackageDimension — 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": "2024-05-28T10:26:04.369Z",
    "createdBy": "string",
    "updated": "2024-05-28T10:26:04.369Z",
    "updatedBy": "string",
    "id": <id>,
    "descriptions": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "height": 9999,
    "length": 9999,
    "packDimensionCode": "string",
    "weight": 10000000000000000,
    "width": 9999
  }
]

Schema — Package Dimension

This section describes the Package Dimension schema.

Table 5-35 Package Dimension — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
height	Yes	integer($int32)	The height of the package in centimeters.
length	Yes	integer($int32)	The length of the package in centimeters.
packDimensionCode	Yes	string	The package dimension code.
weight	Yes	number	The weight of the package in kilograms.
width	Yes	integer($int32)	The width of the package in centimeters.

Table 5-36 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions. For example, { "en-US": "small", "de-DE": "klein", "fr-FR": "petit" }

Responses

This section describes the responses of the Performs a Bulk Action using a Collection of PackageDimension 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 5-37 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 5-38 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 ]

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 5-39 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 5-40 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: 413

Too many records were provided.

Reason Code: 500

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

Queries for PackageDimension Records/Count— GET

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

Method

GET

URL

/api/foundation/v1/package/dimension/count

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

Table 5-41 Queries for PackageDimension 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 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 PackageDimensions Records/Count API.

Response Code: 200

The count of requested records.

The media type is application/json.

Reason Code: 500

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

Get a PackageDimension — GET

This section describes the Get a PackageDimension API. Use this service to retrieve a specific package dimension record and the associated dimensions and descriptions.

Method

GET

URL

/api/foundation/v1/package/dimension/{id}

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

Table 5-42 Get a PackageDimension — 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 the responses of the Get a PackageDimension API.

Response Code: 200

The requested record.

The media type is application/json.

Example Value

{
  "created": "2024-05-29T13:29:25.265Z",
  "createdBy": "string",
  "updated": "2024-05-29T13:29:25.265Z",
  "updatedBy": "string",
  "id": <id>,
  "descriptions": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "height": 9999,
  "length": 9999,
  "packDimensionCode": "string",
  "weight": 10000000000000000,
  "width": 9999
}

Schema — Package Dimension

This section describes the Package Dimension schema.

Table 5-43 Package Dimension — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
height	Yes	integer($int32)	The height of the package in centimeters.
length	Yes	integer($int32)	The length of the package in centimeters.
packDimensionCode	Yes	string	The package dimension code.
weight	Yes	number	The weight of the package in kilograms.
width	Yes	integer($int32)	The width of the package in centimeters.

Table 5-44 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions. For example, { "en-US": "small", "de-DE": "klein", "fr-FR": "petit" }

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 PackageDimension — PUT

This section describes the Update PackageDimension API. Use this service to update a specific package dimension record's dimensions or locale descriptions.

Method

PUT

URL

/api/foundation/v1/package/dimension/{id}

Allowed Scope(s)

foundation-r
foundation-rw

Request

This section describes the request parameters.

The media type is application/json.

Table 5-45 Update a PackageDimension — 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-05-28T14:04:26.076Z",
  "createdBy": "string",
  "updated": "2024-05-28T14:04:26.076Z",
  "updatedBy": "string",
  "id": <id>,
  "descriptions": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "height": 9999,
  "length": 9999,
  "packDimensionCode": "string",
  "weight": 10000000000000000,
  "width": 9999
}

Schema — Package Dimension

This section describes the Package Dimension schema.

Table 5-46 Package Dimension — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
height	Yes	integer($int32)	The height of the package in centimeters.
length	Yes	integer($int32)	The length of the package in centimeters.
packDimensionCode	Yes	string	The package dimension code.
weight	Yes	number	The weight of the package in kilograms.
width	Yes	integer($int32)	The width of the package in centimeters.

Table 5-47 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions. For example, { "en-US": "small", "de-DE": "klein", "fr-FR": "petit" }

Responses

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

Response Code: 200

The updated record.

The media type is application/json.

Example Value

{
  "created": "2024-05-28T14:04:26.163Z",
  "createdBy": "string",
  "updated": "2024-05-28T14:04:26.163Z",
  "updatedBy": "string",
  "id": <id>,
  "descriptions": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "height": 9999,
  "length": 9999,
  "packDimensionCode": "string",
  "weight": 10000000000000000,
  "width": 9999
}

Schema — Package Dimension

This section describes the Package Dimension schema.

Table 5-48 Package Dimension — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
height	Yes	integer($int32)	The height of the package in centimeters.
length	Yes	integer($int32)	The length of the package in centimeters.
packDimensionCode	Yes	string	The package dimension code.
weight	Yes	number	The weight of the package in kilograms.
width	Yes	integer($int32)	The width of the package in centimeters.

Table 5-49 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions. For example, { "en-US": "small", "de-DE": "klein", "fr-FR": "petit" }

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 5-50 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 5-51 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 PackageDimension — DELETE

This section describes the Delete a PackageDimension API. This service deletes a package dimension code and all of the associated dimensions and descriptions configured by locale.

Method

DELETE

URL

/api/foundation/v1/package/dimension/{id}

Allowed Scope(s)

foundation-r
foundation-rw

Request

This section describes the request parameters.

Table 5-52 Delete a PackageDimension— Request Parameters

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

Responses

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

Reason Code: 204

Deletion succeeded.

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.

Checks if a PackageDimension Exists — HEAD

This section describes the Checks if a PackageDimensionn Exists API.

Method

HEAD

URL

/api/foundation/v1/package/dimension/{id}

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

Table 5-53 Checks if a PackageDimension 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 PackageDimension Exists API.

Reason Code: 200

The requested record exists.

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.

Queries for PackageDimension Records by Attributes — GET

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

Method

GET

URL

/api/foundation/v1/package/dimension/byattributes

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

Table 5-54 Queries for PackageDimension Records by Attributes — Request Parameters

Parameter	Required	Data Type	Description
id	NA	integer($int64) (query)	id
height	NA	integer($int32) (query)	height
length	NA	integer($int32) (query)	length
packDimensionCode	NA	string (query)	packDimensionCode
weight	NA	number (query)	weight
width	NA	integer($int32) (query)	width
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 PackageDimension Records by Attributes API.

Response Code: 200

The requested record.

The media type is application/json.

Example Value

[
  {
    "created": "2024-07-24T16:05:15.787Z",
    "createdBy": "string",
    "updated": "2024-07-24T16:05:15.787Z",
    "updatedBy": "string",
    "id": <id>,
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "addressType": "RESIDENTIAL",
    "apartment": "string",
    "city": "string",
    "country": "string",
    "deliveryInstructions": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "latitude": 999999999,
    "locTypeDescription": "string",
    "locationCode": "string",
    "locationDesc": "string",
    "longitude": 999999999,
    "operatingHours": "string",
    "phoneNumber": "string",
    "postalCode": "string",
    "state": "string",
    "timezone": "string"
  }
]

Schema — Package Dimension

This section describes the Package Dimension schema.

Table 5-55 Package Dimension — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
height	Yes	integer($int32)	The height of the package in centimeters.
length	Yes	integer($int32)	The length of the package in centimeters.
packDimensionCode	Yes	string	The package dimension code.
weight	Yes	number	The weight of the package in kilograms.
width	Yes	integer($int32)	The width of the package in centimeters.

Table 5-56 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions. For example, { "en-US": "small", "de-DE": "klein", "fr-FR": "petit" }

Reason Code: 500

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

Reason Code Service

This section describes the Reason Code Service.

Note:

The Reason Code Service can be used to add, replace, edit or delete the default values.

Add a New Reason — POST

This section describes the Add a New Reason API. This service creates a reason code which associates a reason type to a reason description that can be configured by locale. This is also leveraged by the Collect and Receive user interface to allow users to configure a list of reasons for canceling a delivery.

Method

POST

URL

/api/foundation/v1/reason

Allowed Scope(s)

foundation-r
foundation-rw

Request

This section describes the request parameters.

The request body is application/json.

The ModelField is null.

Table 5-57 Add a New Reason— 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-03T12:13:49.444Z",
  "createdBy": "string",
  "updated": "2024-06-03T12:13:49.444Z",
  "updatedBy": "string",
  "id": <id>,
  "descriptions": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "reasonCode": "string",
  "reasonType": "CANCEL"
}

Schema — Reason

Table 5-58 Reason — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
reasonCode	Yes	string(15)	The unique code for the reason.
reasonType	Yes	string	The reason type as to why the action is needed. ENUM: CANCEL

Table 5-59 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions.

Responses

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

Response Code: 200

The new record.

The media type is application/json.

Example Value

{
  "created": "2024-07-24T06:08:23.004Z",
  "createdBy": "string",
  "updated": "2024-07-24T06:08:23.004Z",
  "updatedBy": "string",
  "id": <id>,
  "idcsId": "string",
  "locale": "en-US",
  "preferredLocationCode": "string"
}

Schema — Reason

Table 5-60 Reason — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
reasonCode	Yes	string(15)	The unique code for the reason.
reasonType	Yes	string	The reason type as to why the action is needed. ENUM: CANCEL

Table 5-61 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions.

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 5-62 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 5-63 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 Reason Records— GET

This section describes the Queries for Reason Records API. This service returns a list of reason code records with associated reason type and descriptions matching the provided criteria.

Method

GET

URL

/api/foundation/v1/reason

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

Table 5-64 Queries for Reason 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 Reason Records API.

Response Code: 200

The requested record.

The media type is application/json.

Example Value

[
  {
    "created": "2024-05-29T11:38:19.704Z",
    "createdBy": "string",
    "updated": "2024-05-29T11:38:19.704Z",
    "updatedBy": "string",
    "id": <id>,
    "descriptions": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "reasonCode": "string",
    "reasonType": "string"
  }
]

Schema — Reason

Table 5-65 Reason — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
reasonCode	Yes	string(15)	The unique code for the reason.
reasonType	Yes	string	The reason type as to why the action is needed. ENUM: CANCEL

Table 5-66 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions.

Reason Code: 500

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

Performs a Bulk Action Using a Collection of Reason — GET

This section describes the Performs a Bulk Action Using a Collection of Reason API. This service performs a bulk action (Add, Add or Update, Delete, Update) using a collection of Reason services.

Method

POST

URL

/api/foundation/v1/reason/bulk

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

The request body is application/json.

A list of records to be loaded.

Table 5-67 Performs a Bulk Action Using a Collection of Reason — Request Parameters

Parameter	Required	Data Type	Desciption
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": "2024-05-29T12:03:45.657Z",
    "createdBy": "string",
    "updated": "2024-05-29T12:03:45.657Z",
    "updatedBy": "string",
    "id": <id>,
    "descriptions": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "reasonCode": "string",
    "reasonType": "string"
  }
]

Schema — Reason

Table 5-68 Reason — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
reasonCode	Yes	string(15)	The unique code for the reason.
reasonType	Yes	string	The reason type as to why the action is needed. ENUM: CANCEL

Table 5-69 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions.

Responses

This section describes the responses of the Performs a Bulk Action using a Collection of Reason 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 5-70 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 5-71 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 ]

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 5-72 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 5-73 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: 413

Too many records were provided.

Reason Code: 500

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

Queries for Reason Records/Count— GET

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

Method

GET

URL

/api/foundation/v1/reason/count

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

Table 5-74 Queries for Reason Records/Count — Request Parameters

Parameter	Required	Data Type	Desciption
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.

Responses

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

Response Code: 200

The count of requested records.

The media type is application/json.

Reason Code: 500

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

Get a Reason — GET

This section describes the Get a Reason API. Use this service to retrieve a specific reason record and the associated reason type and descriptions.

Method

GET

URL

/api/foundation/v1/reason/{id}

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

Table 5-75 Get a Reason — 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 the responses of the Get a Reason API.

Response Code: 200

The requested record.

The media type is application/json.

Example Value

{
  "created": "2024-06-03T13:08:23.275Z",
  "createdBy": "string",
  "updated": "2024-06-03T13:08:23.275Z",
  "updatedBy": "string",
  "id": <id>,
  "descriptions": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "reasonCode": "string",
  "reasonType": "CANCEL"
}

Schema — Reason

Table 5-76 Reason — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
reasonCode	Yes	string(15)	The unique code for the reason.
reasonType	Yes	string	The reason type as to why the action is needed. ENUM: CANCEL

Table 5-77 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions.

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 Reason — PUT

This section describes the Update a Reason API. Use this service to update a specific reason record's type or locale descriptions.

Method

PUT

URL

/api/foundation/v1/reason/{id}

Allowed Scope(s)

foundation-r
foundation-rw

Request

This section describes the request parameters.

The media type is application/json.

Table 5-78 Update a Reason — 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-05-29T13:34:47.398Z",
  "createdBy": "string",
  "updated": "2024-05-29T13:34:47.398Z",
  "updatedBy": "string",
  "id": <id>,
  "descriptions": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "reasonCode": "string",
  "reasonType": "string"
}

Schema — Reason

Table 5-79 Reason — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
reasonCode	Yes	string(15)	The unique code for the reason.
reasonType	Yes	string	The reason type as to why the action is needed. ENUM: CANCEL

Table 5-80 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions.

Responses

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

Response Code: 200

The updated record.

The media type is application/json.

Example Value

{
  "created": "2024-05-29T13:34:47.403Z",
  "createdBy": "string",
  "updated": "2024-05-29T13:34:47.404Z",
  "updatedBy": "string",
  "id": <id>,
  "descriptions": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "reasonCode": "string",
  "reasonType": "string"
}

Schema — Reason

Table 5-81 Reason — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
reasonCode	Yes	string(15)	The unique code for the reason.
reasonType	Yes	string	The reason type as to why the action is needed. ENUM: CANCEL

Table 5-82 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions.

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 5-83 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 5-84 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 Reason — DELETE

This section describes the Delete a Reason API. This service deletes a reason code and it's associated reason type and descriptions configured by locale.

Method

DELETE

URL

/api/foundation/v1/package/dimension/{id}

Allowed Scope(s)

foundation-r
foundation-rw

Request

This section describes the request parameters.

Table 5-85 Delete a PackageDimension— Request Parameters

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

Responses

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

Reason Code: 204

Deletion succeeded.

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.

Checks if a Reason Exists — HEAD

This section describes the Checks if a Reason Exists API.

Method

HEAD

URL

/api/foundation/v1/reason/{id}

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

Table 5-86 Checks if a Reason 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 Reason Exists API.

Reason Code: 200

The requested record exists.

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.

Queries for Reason Records by Attributes — GET

This section describes the Queries for Reason Records by Attributes API.

Method

GET

URL

/api/foundation/v1/reason/byattributes

Allowed Scope(s)

foundation-r

Request

This section describes the request parameters.

Table 5-87 Queries for Reason Records by Attributes — Request Parameters

Parameter	Required	Data Type	Description
id	NA	integer($int64) (query)	id
reasonCode	NA	string (query)	reasonCode
reasonType	NA	string (query)	reasonType, Available value: CANCEL
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 Queries for Reason Records by Attributes the API.

Response Code: 200

The requested record.

The media type is application/json.

Example Value

[
  {
    "created": "2024-06-03T08:23:26.454Z",
    "createdBy": "string",
    "updated": "2024-06-03T08:23:26.455Z",
    "updatedBy": "string",
    "id": <id>,
    "descriptions": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "reasonCode": "string",
    "reasonType": "string"
  }
]

Schema — Reason

Table 5-88 Reason — 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
descriptions	Yes	object	Locale types as IETF BCP47 language tags and their descriptions.
reasonCode	Yes	string(15)	The unique code for the reason.
reasonType	Yes	string	The reason type as to why the action is needed. ENUM: CANCEL

Table 5-89 Descriptions — Object

Element Name	Required	Data Type	Description
description	NA	string	Locale types as IETF BCP47 language tags and their descriptions.

Reason Code: 500

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