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

# Quickstart

> Make your first Perform.AI API calls: generate a token, create a shipment, and retrieve its details.

This guide takes you from credentials to a tracked shipment in three API calls.

## Before you start

Get your **Client ID** and **Client Secret** from **Integrations > API** in your Perform.AI account. If no credentials exist yet, select **Request Credentials**. See the [authentication guide](/authentication) for details.

<Steps>
  <Step title="Generate a Bearer token">
    Send your credentials as HTTP Basic authentication with a form-encoded body:

    ```bash theme={null}
    curl --request POST \
      --url https://api.perform.ai/auth/oauth/token/ \
      --header "Authorization: Basic $(echo -n 'your_client_id:your_client_secret' | base64)" \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data 'grant_type=client_credentials'
    ```

    The response contains your token, valid for 1 hour:

    ```json theme={null}
    {
      "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
      "expires_in": 3600,
      "token_type": "Bearer"
    }
    ```
  </Step>

  <Step title="Create a shipment">
    Only `shipment_id` — your own unique identifier — is required to create a shipment:

    ```bash theme={null}
    curl --request POST \
      --url https://api.perform.ai/v5/shipment/ \
      --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
      --header 'Content-Type: application/json' \
      --data '{
        "shipment_id": "SHP-2026-000001"
      }'
    ```

    A successful response returns the identifiers Perform.AI assigned:

    ```json theme={null}
    {
      "api_response": "200",
      "data": {
        "shipment_uuid": "0d9b917b-74f7-4b0e-a2d6-6a1b7f3f2f11",
        "order_uuid": null,
        "documents": [],
        "created_date": "2026-09-18T08:30:00+00:00"
      }
    }
    ```

    <Note>
      `shipment_id` must be unique across your account and cannot be changed after creation, so use a stable identifier from your own system.
    </Note>

    To have Perform.AI track the shipment with a carrier, also provide `tracking_number` and `carrier_reference`. The `carrier_reference` must first be configured under **Settings > Carriers** in your account — an unconfigured value blocks creation:

    ```json theme={null}
    {
      "shipment_id": "SHP-2026-000002",
      "tracking_number": "00340434616780000001",
      "carrier_reference": "dhl-ecommerce-de"
    }
    ```
  </Step>

  <Step title="Retrieve the shipment">
    Fetch the shipment you created, by your ID or the returned UUID:

    ```bash theme={null}
    curl --request GET \
      --url 'https://api.perform.ai/v5/shipment/details/?shipment_id=SHP-2026-000002' \
      --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
    ```

    <Check>
      The response includes the shipment's status, carrier, and an `all_events` array that fills with tracking events as Perform.AI retrieves them from the carrier.
    </Check>
  </Step>
</Steps>

## Next steps

<Columns cols={2}>
  <Card title="Create shipments in full" href="/guides/create-shipment" icon="box">
    Addresses, line items, costs, documents, and notification settings.
  </Card>

  <Card title="Receive webhooks" href="/guides/webhooks" icon="webhook">
    Push shipment updates to your systems instead of polling.
  </Card>

  <Card title="Search shipments" href="/guides/list-shipments" icon="list">
    Filter and paginate across your shipment data.
  </Card>

  <Card title="API reference" href="/api-reference/overview" icon="code">
    Every endpoint, parameter, and response, with a live playground.
  </Card>
</Columns>