> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primefreight.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a tracking request

> Endpoint for creating new shipment tracking requests

# Create a tracking request

The create tracking request endpoint allows you to initiate monitoring for ocean freight shipments. This endpoint accepts bill of lading numbers, or container numbers along with shipping line SCAC codes to begin tracking shipment progress.

## Endpoint Overview

**POST** `/tracking_requests`

This endpoint creates a new tracking request that will attempt to fetch shipment details from the specified shipping line.

## Request Process

When a tracking request is created, the following process occurs:

1. **Request Validation**: The API validates the tracking number and shipping line SCAC code
2. **Data Retrieval**: The system attempts to fetch shipment data from the shipping line
3. **Status Update**: The tracking request status is updated to reflect the outcome
4. **Webhook Notification**: A webhook event is sent to notify of success or failure

## Request Format

### Headers

| Header         | Type   | Required | Description                     |
| -------------- | ------ | -------- | ------------------------------- |
| `X-API-Key`    | string | Yes      | Your API key for authentication |
| `Content-Type` | string | Yes      | Must be `application/json`      |

### Request Body

```json theme={null}
{
  "data": {
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "MEDUFR030802",
      "shipping_line_scac": "MSCU",
      "ref_numbers": [
        "PO12345",
        "HBL12345"
      ],
      "shipment_tags": [
        "camembert"
      ]
    },
    "type": "tracking_request"
  }
}
```

### Required Parameters

| Parameter            | Type   | Description                                                 |
| -------------------- | ------ | ----------------------------------------------------------- |
| `request_type`       | string | Type of tracking request: "bill\_of\_lading" or "container" |
| `request_number`     | string | The bill of lading number, or container number to track     |
| `shipping_line_scac` | string | The SCAC code of the shipping line                          |

### Optional Parameters

| Parameter       | Type  | Description                                             |
| --------------- | ----- | ------------------------------------------------------- |
| `ref_numbers`   | array | Array of reference numbers associated with the shipment |
| `shipment_tags` | array | Array of tags for categorizing shipments                |

## Response Format

### Success Response (201 Created)

```json theme={null}
{
  "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"
    }
  }
}
```

### Response Fields

| Field                                | Type   | Description                                     |
| ------------------------------------ | ------ | ----------------------------------------------- |
| `data.id`                            | string | Unique identifier for the tracking request      |
| `data.type`                          | string | Resource type (always "tracking\_request")      |
| `data.attributes.request_type`       | string | Type of tracking request                        |
| `data.attributes.request_number`     | string | The tracking number being monitored             |
| `data.attributes.shipping_line_scac` | string | The SCAC code of the shipping line              |
| `data.attributes.ref_numbers`        | array  | Array of reference numbers                      |
| `data.attributes.shipment_tags`      | array  | Array of tags                                   |
| `data.attributes.created_at`         | string | ISO 8601 timestamp when created                 |
| `data.attributes.updated_at`         | string | ISO 8601 timestamp when last updated            |
| `data.attributes.status`             | string | Current status ("pending", "created", "failed") |
| `data.attributes.failed_reason`      | string | Reason for failure if failed, null otherwise    |

## Status Codes

| Code | Description                                 |
| ---- | ------------------------------------------- |
| 201  | Tracking request created successfully       |
| 400  | Bad request - invalid parameters            |
| 401  | Authentication failed - invalid API key     |
| 422  | Validation error - check request parameters |
| 429  | Rate limit exceeded                         |

## Tracking Request Types

The API supports two types of tracking requests:

* **bill\_of\_lading**: Track shipments using bill of lading numbers
* **container**: Track shipments using container numbers

## Tracking Request Statuses

The tracking request can have the following statuses:

* **pending**: The tracking request has been created and the system is attempting to fetch shipment data
* **created**: The tracking request was successful and a shipment object has been created
* **failed**: The tracking request failed to fetch shipment data

## Webhook Events

When a tracking request is created, the following webhook events may be sent:

* **tracking\_request.succeeded**: Sent when shipment data is successfully retrieved
* **tracking\_request.failed**: Sent when the tracking request fails to fetch data