Turvo

The Turvo node calls the Turvo cloud transportation management system (TMS) REST API from within a Splice flow. It is the action node for working with Turvo on demand: retrieving and creating shipments, retrieving orders, customers, assets and documents, and searching or creating carriers and locations.

If you instead want a flow to start automatically when something changes in Turvo, use the separate Turvo Trigger node — that is documented on its own page.

Overview

The Turvo node is essential when you need to:

• Retrieve a shipment by its Turvo ID and use its details downstream.
• List shipments filtered by created date, status, custom ID, PO/BOL/PRO number, and many other criteria.
• Create a shipment in Turvo from upstream data.
• Look up related records — retrieve a customer, order, asset, or document by ID.
• Search and create supporting records — search carriers by SCAC, search locations by name, retrieve a location by ID, and create new locations.

Configuration

The node is driven by a Resource and an Action. The resource selects the kind of Turvo object; the action selects the operation, and the available actions depend on the chosen resource.

Resource

• Name: resource
• Type: Options
• Default: Shipments
• Description: Resource to consume.

Resource	Value
Shipments	shipments
Documents	documents
Assets	assets
Customers	customers
Locations	locations
Carriers	carriers
Orders	orders

Actions by resource

Resource	Action	Value
Shipments	Retrieve a shipment	retrieveShipment
Shipments	List shipments	getAllShipments
Shipments	Create a shipment	createShipment
Documents	Retrieve a document	retrieveDocument
Assets	Retrieve an asset	retrieveAsset
Customers	Retrieve a customer	retrieveCustomer
Locations	Search locations	searchLocations
Locations	Retrieve location	retrieveLocation
Locations	Create location	createLocation
Carriers	Search carriers	searchCarrier
Orders	Retrieve order	retrieveOrder

Parameters

Parameters are shown or hidden based on the selected resource and action (the node's displayOptions). The relevant inputs for each action are described below.

Shipments → Retrieve a shipment (retrieveShipment)

Parameter	Name	Type	Description
ID	id	String	Turvo ID of the shipment to retrieve.

Shipments → List shipments (getAllShipments)

All of the following are optional query filters. Only the populated ones are sent to Turvo.

Parameter	Name	Type	Description
Create Date	created	String	Shipments after the specified created date.
Custom ID	customId	String	CustomId of the shipment.
Status	status	String	Status of the shipment.
Location ID	locationId	String	Location associated with the shipment.
Pickup Date	pickupDate	String	Shipments after the specified pickup date.
Container	containerNumber	String	Shipment container number.
Delivery Date	deliveryDate	String	Filter by delivery date.
Customer ID	customerId	String	Customer ID of the shipment.
Start	start	String	Start index of the next page to skip (e.g. start=25 skips the first 25 entities).
Page Size	pageSizeNum	String	Number of records per page.
PO Number	poNumber	String	Purchase order number of the shipment.
BOL Number	bolNumber	String	Master bill of lading number of the customer order.
PRO Number	proNumber	String	PRO number of the customer order.
Route Number	routeNumber	String	Route number of the shipment.
Other	other	String	Other search value.
Truck Number	truckNumber	String	Truck number of the carrier order.
Parent Account	parentAccount	String	Associated parent account ID.
Tracking Provider	trackingProvider	String	Tracking provider of the shipment.
Service Area Key	serviceAreaKey	String	Service area key of the LTL shipment.
Sort By	sortBy	String	Sort the results. Pass sortBy=date to sort by created date; otherwise results are sorted by updated date.

For the filters that support it, a comma-separated value is sent to Turvo as an [in] list, while a single value is sent as an [eq] match.

Shipments → Create a shipment (createShipment)

Create takes a large structured payload that mirrors the Turvo shipment object. Key inputs include:

• Full Response (fullResponse, boolean) — request the full Turvo response.
• ltlShipment (ltlShipment, boolean) — mark the shipment as LTL.
• startDate / endDate (fixed collections) — date and timezone.
• status — a Turvo code key/value pair plus notes.
• equipment — type, weight, weight units, temperature, size, description, length.
• lane — start and end.
• globalRoute — the stops (location, stop type, scheduling type, appointment, attributes such as arrival/departed, dwell time, distance, services, PO numbers, notes, contact, and more).
• transportation / modeInfo — mode, service type, container/booking/voyage/vessel/rail details.
• customerOrder — customer, line items (name, category, quantity, dimensions, weights, volume, pickup/delivery location), costs (line items, totals, tax, currency), and externalIds.
• carrierOrder — carrier, drivers, contacts, equipment, rate confirmation, externalIds, and flex attributes.
• party, margin, services, groups, contributors, flexAttributes.
• skipDistanceCalculation and use_routing_guide booleans.

Most fixed-collection fields use Turvo's standard { key, value } shape (a code and its display value).

Documents → Retrieve a document (retrieveDocument)

Parameter	Name	Type	Description
ID	id	String	Document ID.

Assets → Retrieve an asset (retrieveAsset)

Parameter	Name	Type	Description
ID	id	String	Asset of the corresponding ID to return.

Customers → Retrieve a customer (retrieveCustomer)

Parameter	Name	Type	Description
ID	id	String	ID of the customer to return.

Locations → Search locations (searchLocations)

Parameter	Name	Type	Description
Location name	name	String	Location name to search for.

Locations → Retrieve location (retrieveLocation)

Parameter	Name	Type	Description
Location id	id	String	Location ID.

Locations → Create location (createLocation)

Parameter	Name	Type	Required	Description
Location name	name	String	Yes	Name of the location.
Address line 1	addressLine1	String	Yes	Street address.
City	city	String	No	City.
State	state	String	No	State.
Zip	zip	String	No	Zip code.
Country	country	String	No	Country code (default US).
Timezone	timezone	String	No	Timezone (e.g. America/Detroit).

Although City, State, and Zip are not marked required in the node metadata, the handler rejects the request if Location name, Address line 1, City, State, or Zip is missing.

Carriers → Search carriers (searchCarrier)

Parameter	Name	Type	Description
Standard Carrier Alpha Code	scac	String	SCAC to search by.

Orders → Retrieve order (retrieveOrder)

Parameter	Name	Type	Required	Description
Order id	id	String	Yes	Order ID.

Credential

The Turvo node requires the Turvo API credential (turvoAuth). Configure it with the fields defined in the credential metadata:

Field	Name	Description
Environment	environment	Selects the Turvo environment / base URL. Options are Sandbox (default) and Production.
Client ID	clientId	OAuth client ID issued by Turvo.
Client secret	clientSecret	OAuth client secret issued by Turvo.
Username	username	Turvo user name used for the password grant.
Password	password	Turvo user password used for the password grant.
API Key	apiKey	Turvo API key. Sent as the x-api-key header on every request.

The Environment selects the Turvo base URL:

• Sandbox → https://my-sandbox-publicapi.turvo.com/v1
• Production → https://publicapi.turvo.com/v1

Authentication uses the OAuth 2.0 password grant. The node POSTs the client ID, client secret, username, password, grant_type=password, scope=read+trust+write, and type=business to Turvo's authentication endpoint (with the API key in the x-api-key header) to obtain an access token. If the response contains a linked tenant named SEND, that tenant's token is used; otherwise the returned access_token is used. The token is then sent as a Bearer token alongside the API key on every subsequent API call.

Tokens are cached (with a 5-minute expiry buffer) and reused until they expire, so repeated calls do not re-authenticate every time.

Output

The output shape depends on the resource and action:

• Retrieve operations (shipment, document, asset, customer, order, location) return the Turvo API response body for that single record. Turvo nests the record under a details object.
• List shipments (getAllShipments) returns a flat array of the matching shipment records. The handler pages through Turvo's results automatically — it repeatedly requests the next page while details.pagination.moreAvailable is true and collects every details.shipments entry — so the node returns the combined shipments, not the raw paginated response. Date filters (Create Date, Pickup Date, Delivery Date) are normalized to ISO 8601 before being sent.
• Search operations (carriers by SCAC, locations by name) return Turvo's list response body containing the matching records.
• Create a shipment (createShipment) returns the Turvo response body for the created shipment. The Full Response flag is passed through to Turvo to request the full record. The submitted payload is assembled and validated against Turvo's create-shipment JSON schema before sending.
• Create location (createLocation) returns the Turvo response body for the created location.

Apart from the list-shipments flattening, the node passes the Turvo response through largely unchanged, so downstream nodes work against Turvo's native object structure.

Example Usage & Common Use Cases

Retrieve a shipment by ID

1. Provide a shipment ID from an upstream node or trigger.
2. Add the Turvo node with Resource: Shipments, Action: Retrieve a shipment.
3. Set ID to the shipment's Turvo ID.
4. Use the returned shipment downstream.

List shipments created after a date

1. Add the Turvo node with Resource: Shipments, Action: List shipments.
2. Set Create Date (and optionally Status, Customer ID, or other filters).
3. The node pages through and returns all matching shipments as an array.

Create a location

1. Add the Turvo node with Resource: Locations, Action: Create location.
2. Provide Location name, Address line 1, City, State, and Zip (all required by the handler), plus Country and Timezone as needed.
3. Use the returned location in a subsequent shipment.

Search a carrier by SCAC

1. Add the Turvo node with Resource: Carriers, Action: Search carriers.
2. Set Standard Carrier Alpha Code to the carrier's SCAC.
3. Use the matched carrier downstream.

How It Works

1. Read parameters — the node reads the selected Resource and Action along with the inputs shown for that combination. If no parameters are present it fails with Error: No parameters found.
2. Authenticate — it resolves the base URL from the credential's environment (Production or Sandbox), then obtains (or reuses a cached) OAuth bearer token via the password grant. The token is sent as Authorization: Bearer <token> and the API key as x-api-key on every request.
3. Dispatch to a handler — the resource/action pair is routed to the matching handler (retrieveShipment, getAllShipments, createShipment, retrieveCustomer, searchCarrier, searchLocations, retrieveLocation, createLocation, retrieveOrder, retrieveAsset, retrieveDocument).
4. Build the request —
   • Retrieve handlers issue a GET for the given ID.
   • List shipments builds query parameters from the populated filters (using Turvo's [eq] / [in] operators, with comma-separated values treated as an [in] list), normalizes dates to ISO 8601, and pages through all results.
   • Search handlers issue a GET with the search term (SCAC or location name) as a query parameter.
   • Create a shipment processes and validates the assembled body against Turvo's create-shipment schema, then POSTs it.
   • Create location assembles a Turvo location body (the address is tagged with the Physical address type) and POSTs it.
5. Send and return — the request is sent with the bearer token and API-key headers, and the Turvo response data is returned to the flow.

Best Practices

• Pick the right Resource first — the available Actions and parameters change with the resource, so set Resource before Action.
• Provide the correct ID for retrieve actions; each resource uses its own ID input.
• Use list filters — narrow List shipments with the available filters rather than retrieving everything; the node already pages through all matching results for you.
• Use Full Response when you need the whole body on Create a shipment; leave it off for a lighter response.
• Store credentials in Splice's credential manager rather than hard-coding the client secret, password, or API key.
• Validate in Sandbox first by pointing the credential's Environment at Sandbox before switching to Production.

Troubleshooting

This operation requires a credential / Credential [<id>] not found No credential was attached, or the configured Turvo credential could not be found. Attach a valid Turvo API credential to the node.

Unknown Turvo environment: <value> The credential's Environment is not sandbox or production. Re-select Sandbox or Production on the credential.

Authentication errors The OAuth token request was rejected. Confirm the Client ID, Client secret, Username, Password, and API Key are correct and that the Environment matches the credentials you were issued.

Missing required ID parameter / Missing required name parameter / Missing required SCAC parameter A retrieve or search action ran without its required input. Populate the ID (Retrieve location/order), Location name (Search locations), or SCAC (Search carriers).

Missing required parameters. (Create location) Create location requires Location name, Address line 1, City, State, and Zip. Provide all five.

404 / record not found A retrieve action returned no record. Verify the ID is correct and exists in the selected environment.

Empty list or search results Confirm the filters (for List shipments) or the SCAC / location name (for searches) actually match records in Turvo, and that the account has data in the selected environment.

Create a shipment rejected Turvo validates the shipment payload (the node also validates it against the create-shipment schema beforehand). Check that required nested fields (for example status code, lane, stops, customer order) are populated and that Turvo { key, value } code pairs use valid codes. A missing start date, for instance, returns a Turvo error such as Shipment start date can't be blank.

Wrong environment If calls succeed against test data but not production data (or vice versa), check the credential's Environment setting — it selects the base URL Turvo requests are sent to.

Related

• Turvo Trigger
• Service Nodes Overview