> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49-sinan-dev-10929-support-initial-shipment-and-per.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a tracking request
> Create a new tracking request in the Terminal49 API with a bill of lading, booking, or container number plus a carrier SCAC to start tracking a shipment.
**Don't know the SCAC?** Set `auto_detect_vocc_scac` to `true` and omit `scac`,
and Terminal49 will infer the carrier SCAC for you. Detection runs
asynchronously: the request is created immediately with `status: "pending"` and
`scac: null`, then resolves to `created` (with the detected `scac` populated) or
`failed` (`failed_reason: "scac_auto_detect_failed"`) — poll the tracking request
or use webhooks to observe the outcome. Use [Auto-Detect
Carrier](/api-docs/api-reference/tracking-requests/auto-detect-carrier) first
when your workflow needs to preview or confirm carrier candidates before
submitting.
This endpoint has its own rate-limit bucket: 100 tracking requests per minute per API key/account.
## Setting custom field values before the shipment exists
Use `initial_custom_fields` to stage custom field values at creation time, before the shipment and containers exist. Terminal49 applies `shipment` entries to the shipment and `containers` entries to their containers once the tracking request resolves.
Each `api_slug` must match an existing [custom field definition](/api-docs/api-reference/custom-fields/create-a-custom-field-definition) on your account — a `Shipment`-scoped definition for `shipment` entries, a `Container`-scoped definition for `containers` entries. Container entries without a `number` — or with `number` set to an empty string — are applied to every container on the shipment; include a non-empty `number` to target one specific container.
```json theme={null}
{
"data": {
"type": "tracking_request",
"attributes": {
"request_number": "MEDUAI047070",
"request_type": "bill_of_lading",
"scac": "MEDU",
"initial_custom_fields": {
"shipment": [
{ "api_slug": "booking_reference", "value": "BOOK-2026-001" }
],
"containers": [
{ "api_slug": "po_number", "value": "PO-123", "number": "MSCU1234567" },
{ "api_slug": "po_number", "value": "PO-999", "number": "TCLU7654321" },
{ "api_slug": "customs_broker", "value": "Acme Brokerage" },
{ "api_slug": "seal_number", "value": "SEAL-0001", "number": "" }
]
}
}
}
}
```
In this example, `booking_reference` is set on the shipment; `po_number` is set per container by `number`; and `customs_broker` and `seal_number` — which omit `number` or pass an empty string — are applied to every container on the shipment.
## OpenAPI
````yaml post /tracking_requests
openapi: 3.0.0
info:
title: Terminal49 API Reference
version: 0.2.0
contact:
name: Terminal49 API support
url: https://www.terminal49.com
email: support@terminal49.com
description: >-
The Terminal 49 API offers a convenient way to programmatically track your
shipments from origin to destination.
Please enter your API key into the "Variables" tab before using these
endpoints within Postman.
x-label: Beta
termsOfService: https://www.terminal49.com/terms
servers:
- url: https://api.terminal49.com/v2
description: Production
security:
- authorization: []
tags:
- name: Containers
- name: Custom Field Definitions
- name: Custom Field Options
- name: Custom Fields
- name: Shipments
- name: Locations
- name: Events
- name: Tracking Requests
- name: Webhooks
- name: Webhook Notifications
- name: Ports
- name: Metro Areas
- name: Terminals
- name: Routing (Paid)
- name: Documents
- name: Email Submissions
- name: Document Schemas
- name: Search
paths:
/tracking_requests:
parameters: []
post:
tags:
- Tracking Requests
summary: Create a tracking request
description: >-
To track an ocean shipment, create a new tracking request.
`request_type` and `request_number` are always required. Supply either a
shipping line `scac` or set `auto_detect_vocc_scac` to `true` to have
Terminal49 infer the SCAC from the request number before creating the
tracking request.
Auto-detection uses the same carrier prediction capability as the Infer
Tracking Number endpoint and runs asynchronously. The tracking request
is created immediately (HTTP `201`) with `status: "pending"`; if no
supported carrier can be inferred it transitions to `status: "failed"`
with `failed_reason: "scac_auto_detect_failed"` and no shipment is
created. Once a tracking request is created we will attempt to fetch the
shipment details and its related containers from the shipping line. If
the attempt is successful we will create a new shipment object including
any related container objects. We will send a
`tracking_request.succeeded` webhook notification to your webhooks.
If the attempt to fetch fails then we will send a
`tracking_request.failed` webhook notification to your `webhooks`.
A `tracking_request.succeeded` or `tracking_request.failed` webhook
notification will only be sent if you have at least one active webhook.
This endpoint is limited to 100 tracking requests per
minute.
operationId: post-track
parameters: []
requestBody:
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
request_type:
type: string
example: bill_of_lading
enum:
- bill_of_lading
- booking_number
- container
description: ' The type of document number to be supplied. Container number support is currently in BETA.'
request_number:
type: string
example: MEDUFR030802
scac:
type: string
description: >-
The carrier SCAC to use for this tracking request.
Required unless `auto_detect_vocc_scac` is `true`.
example: MSCU
minLength: 4
maxLength: 4
auto_detect_vocc_scac:
type: boolean
description: >-
Set to `true` to have Terminal49 infer the carrier
SCAC from `request_number` when `scac` is not
supplied. Detection is asynchronous: the tracking
request is created immediately (HTTP `201`) with
`status: "pending"` and `scac: null`. If a carrier
is inferred, the request transitions to `status:
"created"` with the detected `scac` populated. If no
supported carrier can be inferred, it transitions to
`status: "failed"` with `failed_reason:
"scac_auto_detect_failed"` and no shipment is
created. Poll the tracking request or use webhooks
to observe the outcome — the create response does
not include the detected `scac`.
default: false
example: true
ref_numbers:
type: array
description: >-
Optional list of reference numbers to be added to
the shipment when tracking request completes
items:
type: string
shipment_tags:
type: array
description: >-
Optional list of tags to be added to the shipment
when tracking request completes
items:
type: string
initial_custom_fields:
type: object
description: >-
Optional custom field values to stage before the
shipment and containers exist. Terminal49 applies
`shipment` entries to the shipment and `containers`
entries to matching containers once the tracking
request resolves. Each `api_slug` must reference an
existing custom field definition on your account.
properties:
shipment:
type: array
description: >-
Custom field values to apply to the shipment
created by this tracking request.
items:
type: object
required:
- api_slug
- value
properties:
api_slug:
type: string
description: >-
The `api_slug` of a custom field
definition scoped to the `Shipment` entity
type.
value:
$ref: '#/components/schemas/custom_field_value'
containers:
type: array
description: >-
Custom field values to apply to the containers
created by this tracking request. Include
`number` to target one specific container; omit
it (or pass an empty string) to apply the value
to every container on the shipment.
items:
type: object
required:
- api_slug
- value
properties:
api_slug:
type: string
description: >-
The `api_slug` of a custom field
definition scoped to the `Container`
entity type.
value:
$ref: '#/components/schemas/custom_field_value'
number:
type: string
description: >-
Container number to target. Omit this
field, or pass an empty string, to
broadcast this value to every container on
the shipment.
example: MSCU1234567
required:
- request_type
- request_number
relationships:
type: object
properties:
customer:
type: object
properties:
data:
type: object
properties:
id:
type: string
format: uuid
type:
type: string
enum:
- party
type:
type: string
enum:
- tracking_request
required:
- type
examples:
'Example: MSC BL':
value:
data:
attributes:
request_type: bill_of_lading
request_number: MEDUFR030802
initial_custom_fields:
shipment:
- api_slug: booking_reference
value: BOOK-2026-001
containers:
- api_slug: po_number
value: PO-123
number: MSCU1234567
- api_slug: po_number
value: PO-999
number: TCLU7654321
- api_slug: customs_broker
value: Acme Brokerage
- api_slug: seal_number
value: SEAL-0001
number: ''
ref_numbers:
- PO12345
- HBL12345
- CUSREF1234
shipment_tags:
- camembert
scac: MSCU
relationships:
customer:
data:
id: f7cb530a-9e60-412c-a5bc-205a2f34ba54
type: party
type: tracking_request
'Example: Auto-detect carrier SCAC':
value:
data:
attributes:
request_type: bill_of_lading
request_number: MEDUFR030802
auto_detect_vocc_scac: true
ref_numbers:
- PO12345
type: tracking_request
description: Create a shipment tracking request
responses:
'201':
description: Tracking Request Created
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/tracking_request'
included:
type: array
items:
anyOf:
- $ref: '#/components/schemas/account'
- $ref: '#/components/schemas/shipping_line'
examples:
Pending Tracking Request:
value:
data:
id: ba4cb904-827f-4038-8e31-1e92b3356218
type: tracking_request
attributes:
request_number: MEDUFR030802
request_type: bill_of_lading
scac: MSCU
ref_numbers: []
created_at: '2020-04-04T16:13:35-07:00'
updated_at: '2020-04-04T17:13:35-07:00'
status: pending
failed_reason: null
relationships:
tracked_object:
data: null
customer:
data:
id: f7cb530a-9e60-412c-a5bc-205a2f34ba54
type: party
links:
self: >-
/v2/tracking_requests/ba4cb904-827f-4038-8e31-1e92b3356218
headers: {}
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/error'
examples:
Error Examples:
value:
errors:
- status: '422'
source:
pointer: /data/attributes/scac
title: Unprocessable Entity
detail: Scac can't be blank
code: blank
- status: '422'
source:
pointer: /data/attributes/scac
title: Unprocessable Entity
detail: Scac 'XXXX' is not recognized
code: blank
- status: '422'
source:
pointer: /data/attributes/scac
title: Unprocessable Entity
detail: >-
Scac 'UALC' is not supported. We do not currently
integrate with Universal Africa Lines
code: blank
- status: '422'
source:
pointer: /data/attributes/request_number
title: Unprocessable Entity
detail: Request number can't be blank
code: blank
'429':
description: >-
Too Many Requests - You've hit the create tracking requests limit.
Please try again in a minute.
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: string
example: '429'
title:
type: string
example: Too Many Requests
detail:
type: string
example: >-
You've hit the create tracking requests limit.
Please try again in a minute.
headers:
Retry-After:
description: Number of seconds to wait before making another request
schema:
type: integer
example: 60
security:
- authorization: []
components:
schemas:
custom_field_value:
description: Raw custom field value (type depends on definition)
nullable: true
oneOf:
- type: string
- type: number
- type: boolean
- type: array
items:
type: string
- type: object
tracking_request:
title: Tracking Request
type: object
properties:
id:
type: string
format: uuid
type:
type: string
enum:
- tracking_request
attributes:
type: object
properties:
request_number:
type: string
example: ONEYSH9AME650500
ref_numbers:
type: array
items:
type: string
nullable: true
tags:
type: array
items:
type: string
status:
type: string
enum:
- pending
- awaiting_manifest
- created
- failed
- tracking_stopped
failed_reason:
type: string
enum:
- booking_cancelled
- duplicate
- expired
- internal_processing_error
- invalid_number
- not_found
- retries_exhausted
- shipping_line_unreachable
- unrecognized_response
- data_unavailable
- scac_auto_detect_failed
- null
description: >-
If the tracking request has failed, or is currently failing, the
last reason we were unable to complete the request.
`scac_auto_detect_failed` means `auto_detect_vocc_scac` was set
but no supported carrier SCAC could be inferred from the request
number.
nullable: true
request_type:
type: string
enum:
- bill_of_lading
- booking_number
- container
example: bill_of_lading
scac:
type: string
example: ONEY
minLength: 4
maxLength: 4
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
is_retrying:
type: boolean
retry_count:
type: integer
description: >-
How many times T49 has attempted to get the shipment from the
shipping line
nullable: true
required:
- request_number
- status
- request_type
- scac
- created_at
relationships:
type: object
properties:
tracked_object:
type: object
properties:
data:
type: object
nullable: true
properties:
id:
type: string
format: uuid
type:
type: string
enum:
- shipment
customer:
type: object
properties:
data:
type: object
properties:
id:
type: string
format: uuid
type:
type: string
enum:
- party
required:
- id
- type
account:
title: Account model
type: object
properties:
id:
type: string
format: uuid
type:
type: string
enum:
- account
attributes:
type: object
required:
- company_name
properties:
company_name:
type: string
required:
- id
- type
- attributes
x-examples: {}
shipping_line:
title: Shipping line model
type: object
properties:
id:
type: string
format: uuid
attributes:
type: object
required:
- scac
- name
- alternative_scacs
- short_name
- bill_of_lading_tracking_support
- booking_number_tracking_support
- container_number_tracking_support
properties:
scac:
type: string
minLength: 4
maxLength: 4
name:
type: string
alternative_scacs:
type: array
x-stoplight:
id: jwf70hnip0xwb
description: Additional SCACs which will be accepted in tracking requests
items:
x-stoplight:
id: nrqnwg5y2u0ni
type: string
minLength: 4
maxLength: 4
short_name:
type: string
bill_of_lading_tracking_support:
type: boolean
booking_number_tracking_support:
type: boolean
container_number_tracking_support:
type: boolean
type:
type: string
enum:
- shipping_line
required:
- id
- attributes
- type
error:
title: Error model
type: object
properties:
detail:
type: string
nullable: true
title:
type: string
nullable: true
source:
type: object
nullable: true
properties:
pointer:
type: string
nullable: true
parameter:
type: string
nullable: true
code:
type: string
nullable: true
status:
type: string
nullable: true
meta:
type: object
nullable: true
additionalProperties: true
required:
- title
securitySchemes:
authorization:
name: Authorization
type: apiKey
in: header
description: >-
Use a Terminal49 API key in the `Authorization` header with the `Token`
prefix.
`Authorization: Token YOUR_API_KEY`
````