> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49-current-status.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?** Call [Auto-Detect
Carrier](/api-docs/api-reference/tracking-requests/auto-detect-carrier) first
to identify the shipping line from your tracking number.
## 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
paths:
/tracking_requests:
parameters: []
post:
tags:
- Tracking Requests
summary: Create a tracking request
description: >-
To track an ocean shipment, you create a new tracking request.
Two attributes are required to track a shipment. A `bill of
lading/booking number` and a shipping line `SCAC`.
Once a tracking request is created we will attempt to fetch the shipment
details and it's related containers from the shipping line. If the
attempt is successful we will create in 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
notificaiton will only be sent if you have atleast 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
example: MSCU
minLength: 4
maxLength: 4
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
required:
- request_type
- request_number
- scac
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
ref_numbers:
- PO12345
- HBL12345
- CUSREF1234
shipment_tags:
- camembert
scac: MSCU
relationships:
customer:
data:
id: f7cb530a-9e60-412c-a5bc-205a2f34ba54
type: party
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:
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
- null
description: >-
If the tracking request has failed, or is currently failing, the
last reason we were unable to complete the request
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: >-
`Token YOUR_API_TOKEN`
The APIs require authentication to be done using header-based API Key
and Secret Authentication.
API key and secret are sent va the `Authorization` request header.
You send your API key and secret in the following way:
`Authorization: Token YOUR_API_KEY`
````