PEAK Connect -Tender

PEAK Connect Tender allows for electronic booking of freight with your carrier selection. We have painstakingly worked with our carrier partners to provide you a single endpoint to submit your pickups. No need to go directly to carrier to call for pickup or have your IT team write individual API integrations by carriers. The tender does not need to be associated with a PEAK TMS Shipment although we recommend it.

How it works:

Submit an electronic pickup request to a carrier through our EDI system. The response contains an ID that can subsequently be used to request tracking updates for the shipment. This value should be retained by the client.

Resource URL

http(s)://connect.ascentgl.com/v1/tender

JSON Payload

All values in the JSON payload are passed as strings. The format column denotes any special restrictions on the values passed.

A note about EDI identifiers and trading partner data

Several of the properties for pickup requests are related to the EDI Trading Partner agreements with carriers. These properties are:

trading PartnerId

senderIdentifier

senderQualifier

senderIdentifierPadded

If these values are not provided in the pickup request, the tendering system will attempt to find them in its collection of trading partners. A failure to resolve these will result in the pickup request being rejected. In addition, the trading partner agreements with the carriers need to accommodate for EDI to be accepted from and delivered to Ascent in addition to or instead of any other EDI systems being used.

In addition to these, the fileSequenceNumber property can be generated by the Ascent system. Determining the correct sequence number to use is managed using the Ascent system’s trading partner collection, and in most cases should not be specified in pickup requests

A note about EDI control numbers

The EDI group identifier (control number) for each pickup request is provided by the Ascent system at the time the pickup request is created for the carrier. It is done in this manner to prevent sending duplicate EDI control numbers to carriers. If there is a history of EDI with a carrier at the time a client is added to the Ascent system the initial control number to use for each carrier can be adjusted to prevent duplicates.

A note about third party billing

For third party shipments (shipmentType == ‘P’), the Ascent system does not require that the third party details be provided in the pickup request. Depending on the EDI Trading Partner agreement in place with the carrier, this may be provided by the carrier when they process the pickup request. However, if third party billing details are not available, the result may be that the pickup request is rejected by the carrier, or that billing and invoicing is directed to an incorrect party

Property Name

Required

Format

Definition

authKey

Y

Client authentication supplied by Ascent

tradingPartnerId

Y

EDI Trading Partner identifier – see note about EDI Identifiers above

senderIdentifier

Y

15 character max

EDI Sender identifier – see note about EDI Identifiers above

senderIdentifierPadded

N

If not provided this will be constructed from the senderIdentifier and senderQualifier properties

senderQualifier

Y

2 characters

EDI Sender Qualifier – see note about EDI Identifiers above

fileSequenceNumber

N

Numeric

Sequence number used to generate the EDI filename for transmission to the carrier. This should be unique for a given carrier and date of pickup request submission

scac

Y

4 characters

SCAC code for the carrier

ediScac

N

4 characters

Alternative SCAC code for the carrier. If provided this will override the scac property

user

N

Deprecated – currently unused

companyId

Y

Ascent supplied identifier for the sender of the pickup request. Along with the scac property, this is used to lookup EDI trading partner data within the Ascent system

bolNumber

N

BOL number for the shipment

pro

N

Pro number for the shipment

products

Y

A collection of products included in the shipment. At least one valid product must be included in the pickup request. See below for product details.

pallets

N

A pallet detail object. See below for detail properties> Only needed if all the products for the shipment have been palletized

Interpreted as a boolean. Allowed values: Y (true), N (false). Defaults to false. If true, the EDI file sent to the carrier will contain the EDI test indicator, which is intended to prevent the EDI request from having any real actions taken by the carrier. Note that not all carriers honor this flag in the EDI system, so care should be taken before relying on this behavior.

internalTest

N

1 character

Interpreted as a boolean. Allowed values: Y (true), N (false). Defaults to false. If true, the scac and ediScac properties will be overridden by the special scac code TEST. The Ascent EDI system will not transmit such requests to carriers, and further handling of EDI for the shipment – such as tracking updates – will not occur. For testing purposes, setting this to Y is the safest course to follow

pickupName

N

Deprecated – currently unused

pickupCompany

Y

Company name for the pickup location

pickupStreet

Y

Street address line 1 for the pickup location

pickupStreet2

N

Street address line 2 for the pickup location

pickupCity

Y

City name for the pickup location

pickupState

Y

2 characters

State/province code for the pickup location

pickupZip

Y

5 digit US zip code or 6 character Canadian postal code

Postal code for the pickup location

pickupPhoneAreaCode

N`

Company name for the pickup location

pickupPhonePrefix

N

Company name for the pickup location

pickupPhonePhone

N

Company name for the pickup location

pickupPhoneExt

N

Company name for the pickup location

contactName

N

Contact name at the pickup location

contactCompany

N

Contact company name at the pickup location

contactPhoneAreaCode

N

3 characters – numeric

Contact area code at the pickup location

contactPhone Prefix

N

3 characters – numeric

Contact phone prefix at the pickup location

contactPhonePhone

N

4 characters – numeric

Contact phone number at the pickup location

contactPhoneExt

N

Contact phone extension at the pickup location

contactFaxAreaCode

N

3 characters – numeric

Contact fax line area code at the pickup location

contactFaxPrefix

N

3 characters – numeric

Contact fax line phone prefix at the pickup location

contactFaxPhone

N

4 characters – numeric

Contact fax line phone number at the pickup location

contactEmail

Y

Contact email address at the pickup location

pickupMonth

Y

2 characters – month number 01 – 12

A collection of pallet details when a shipment is loaded on pallets by the shipper. If supplied, pallet based pricing will be used to determine the shipping rates, for any carriers that support them. See below for pallet details.

pickupDay

Y

2 characters – day number 01 – 31

A collection of pallet details when a shipment is loaded on pallets by the shipper. If supplied, pallet based pricing will be used to determine the shipping rates, for any carriers that support them. See below for pallet details.

pickupYear

Y

4 characters – 4 digit year

A collection of pallet details when a shipment is loaded on pallets by the shipper. If supplied, pallet based pricing will be used to determine the shipping rates, for any carriers that support them. See below for pallet details.

pickupTime

Y

String – time of day formatted as hh:mm A|P or hh:mm (for 24 hour clock)

Earliest time at which the shipment can be picked up

dockCloseTime

Y

String – time of day formatted as hh:mm A|P or hh:mm (for 24 hour clock)

Latest time at which the shipment can be picked up

accessorials

N

String array

An array of string codes identified accessorials or services required for the shipment. Currently, only the code HAZM – hazardous materials – is honored.

pieces

Y

Numeric

Total number of items in the shipment.

weight

Y

Numeric

Total weight of items in the shipment

comment

N

88 characters maximum

Any additional notes or special instructions for the shipment

destName

N

Contact name at the delivery location

destCompany

Y

Company name at the delivery location

destStreet

Y

Street address line 1 for the delivery location

destStreet2

N

Street address line 2 for the delivery location

destCity

Y

City name for the delivery location

destState

Y

2 characters

State/province code for the delivery location

destZip

Y

5 digit US zip code or 6 character Canadian postal code

Postal code for the delivery location

destPhoneAreaCode

N

3 characters – numeric

Contact area code at the delivery location

destPhonePrefix

N

3 characters – numeric

Contact phone prefix at the delivery location

destPhonePhone

N

4 characters – numeric

Contact phone number at the delivery location

destPhoneExt

N

Contact phone extension at the delivery location

destEmail

N

Contact email address at the delivery location

thirdPartyName

N

Name for the 3rd party billing entity

thirdPartyStreet

N

Street address line 1 for the 3rd party billing entity

thirdPartyStreet2

N

Street address line 2 for the 3rd party billing entity

thirdPartyCity

N

City for the 3rd party billing entity

thirdPartyState

N

2 characters

State/province code for the 3rd party billing entity

thirdPartyZip

N

5 digit US zip code or 6 character Canadian postal code

Postal code for the 3rd party billing entity

additionalContactEmail

N

Email address for any additional shipment contact

supportContactURL

N

Support URL for the shipment

Product Details

Property Name

Required

Format

Definition

name

N

Product description

nmfc

N

NMFC Item Code

nmfcClass

N

Integer digits

NMFC Class Number

weight

Y

Integer digits

Total weight in pounds for this product

pcs

Y

Integer digits

Number of pieces for this product

handlingUnitCount

N

Integer digits

Number of handling units for this product

Pallet Details

Property Name

Required

Format

Definition

palletCount

N

Integer digits

Total number of pallets in shipment, if products are palletized

weight

N

Integer digits

Total weight of pallets in shipment, if products are palletized

Response Codes

Responses come with one of the following status codes:

HTTP Codes

Definition

200

Success. See response body for result payload.

400

Bad input. Required fields missing from input, are malformed or are too numerous.

401

Unauthorized. Authentication failure; invalid credentials.

500

Internal server error. General service failure; retry request.

JSON Response

Property Name

Data Type

Definition

tenderId

Integer

Unique pickup request identifier

authKey

String

Client authentication from the original pickup request

tenderStatusCode

String

Is the shipment going intrastate (origin and destination in the same state or province)?

tenderStatusmessage

String

Does the shipment originate or terminate in Canada?

ediFileName

String

Postal service standard place name for the origin postal code

ediArchiveFileName

String

Postal service standard state/province code for the origin postal code

originalRequet

PickupRequest

Copy of the original pickup request with changes made regarding the EDI identifier properties. This reflects the actual data used to generate the carrier EDI file

messages

A collection of messages regarding any validation problems with the pickup request. See below for message details

Response Message Details

Property Name

Data Type

Definition

level

String

Values: Error, Warning, Info

code

String

Validation message code

description

String

Validation message description

Validation Message Codes and Descriptions

Message Code

Message Description

INVALID_NO_SCAC

Scac must be provided

INVALID_SCAC_DISABLED

Electronic pickup requests for this carrier have been disabled

INVALID_NO_TRADING_PARTNER

Trading Partner Identifier must be provided

INVALID_NO_SENDER_ID

Sender Identifier must be provided

INVALID_SENDER_ID_TOO_LONG)

Sender Identifier must <= 15 characters

INVALID_NO_CONTROL_NUMBER

EDI group control number could not be generated – contact Ascent support

INVALID_CONTROL_NUMBER

EDI group control number must be an integer

INVALID_CTL_NUMBER_TOO_LARGE

EDI group control number must be <= 999999999

INVALID_NO_CONTROL_NUMBER

EDI file sequence number could not be generated – contact MESCA support