> For the complete documentation index, see [llms.txt](https://docs.parcellab.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parcellab.com/docs/developers/getting-started/quickstart-guide.md).

# Quickstart Guide

Integrate the parcelLab API into your system and begin tracking shipments and sending status updates to your customers.

## parcelLab API <a href="#gitbook-api" id="gitbook-api"></a>

The parcelLab API can be used from outside the parcelLab platform, and can be accessed via its RESTful endpoints using the `https://api.parcellab.com/` URL.

API requests are geographically routed to the nearest endpoint. If you’d like to explicitly target a region, you may substitute [api.parcellab.com](https://api.parcellab.com) with either [api.us.parcellab.com](https://api.us.parcellab.com) or [api.eu.parcellab.com](https://api.eu.parcellab.com).

The API processes requests and responses in JSON format and adheres to common HTTP methods and response codes. All interactions with the API must occur through HTTPS for security.

Check out the full list of endpoints in the parcelLab API v4 Enhanced.

{% content-ref url="/pages/cp62v9Dyn4pKa7RRHTv2" %}
[API Reference](/docs/developers/getting-started/api-reference.md)
{% endcontent-ref %}

## Access Token <a href="#personal-access-token" id="personal-access-token"></a>

In order to use the parcelLab platform, you'll need an access token to make calls to the API.

When you are onboarded with parcelLab, we will send you the API credentials and inform you which fields should be used so you can transmit and display the data correctly.

{% hint style="info" %}
Access tokens can also be created in your [account settings in the parcelLab App](https://app.parcellab.com/service/account/apitoken/).
{% endhint %}

Once you have your personal access token, you're able to start making your first API call. To authorize your API requests, include your API token in the request header.

```python
Authorization: Parcellab-API-Token <your-base64-encoded-api-key>
```

## Making Requests

When making an API call, the client interacts with the server by sending requests to access or update the data it holds. An API request consists of:

* HTTP verb - defines the type of operation (for example: GET, POST, PUT, and DELETE)
* Header - contains authorization and request information
* Path - identifies the resource being interacted with
* Message body - optional content used when sending data (for example: creating or updating resources)

### HTTP Verbs

The following HTTP verbs are generally used to interact with resources in the parcelLab API:

* GET — retrieve a specific resource or a collection of resources
* POST — create a new resource
* PUT — update an existing resource
* PATCH - partially modify an existing resource
* DELETE — remove a resource

### Best Practices for API Requests

When making API calls, it’s important to consider the following:

* Always include the mandatory request fields in your API call and handle the required fields in the response
* Avoid using spaces in field names
* Store and reuse values using variables (for example: your parcelLab user ID)

## Test a v4 Integration

Use an account prepared for integration testing. Confirm the account, API host, token scopes, test carrier, and notification destinations with your parcelLab implementation contact. A `TEST-` order number or a dummy tracking number does not select a sandbox or suppress notifications.

1. Use a token for the test account with the required read and write scopes. Route test notifications and webhooks to destinations controlled by your team.
2. Start with the [minimal order request](/docs/developers/orders/create-orders-trackings.md). Use a unique order number, such as `DOCS-TEST-001`, and replace all example account values. For delivery tests, use an inbox your team controls.
3. Send the request to `PUT /v4/track/orders/`. This writes data to the selected account. The legacy `/order/mock` and `/track/mock` routes do not validate v4 payloads.
4. Check the HTTP status. If the PUT response includes `mutations[].result`, check each result for failures and warnings.

   Read the order back with `GET /v4/track/orders/{order_number}/?lookup_by=order-number&account={account_id}`. Use the `order_number` and `account` submitted in step 3; `account` is required for this lookup. An order number that contains `.` or `/`, or starts with `info`, cannot be used in this path. In that case, use `GET /v4/track/orders/{external_id}/` with the `external_id` from the PUT response. Read `external_id` from this GET response and verify the stored order and tracking data. The GET response does not return results from earlier mutation requests. See [Full Order API Spec](/docs/developers/orders/full-order-api-spec.md#retrieve-orders-by-id).
5. For status tests, use the carrier interface or shop-event integration configured for your test account. Review the [checkpoint validation limitation](/docs/developers/orders/create-orders-trackings.md#checkpoint-schema-and-validation-errors) before sending checkpoints in an order mutation. Check [Order Status](/docs/developers/status-updates/order-status.md) after asynchronous tracking processing.
6. Verify the received message or webhook in the test destination. An accepted order mutation alone does not verify delivery of a notification.
7. Record the test identifiers and agree on cleanup with the account owner. Cancelling an order is a business event; it is not a general test-data deletion operation.

### Exception Test Data

An `Exception` checkpoint should include a reason code such as `AddressIssue`, as defined by the [delivery status model](/docs/developers/data-elements/lifecycle-model/status-model.md). Use a carrier event or test scenario configured for your test account, then inspect the returned tracking checkpoints for the status and reason.

The tracking-level `is_exception` field in the [Order Status](/docs/developers/status-updates/order-status.md) response reports an escalated or forgotten tracking; it is not a direct copy of `status_code == "Exception"`. To test `is_exception: true`, have your implementation contact select a scenario that satisfies the account’s escalation rules. Do not use that flag alone to check whether a checkpoint was accepted.

## API Versions

The parcelLab API is used to interact with the parcelLab platform. As changes are made as part of API development, versioning ensures that these changes are rolled out successfully to keep the API secure and high performing.

At parcelLab, we have the API v4 Enhanced for new integrations, which is the recommended and standard integration path, allowing for more enhanced and standardized interaction with our platform

{% hint style="warning" %}
We also have the API v2 LTS (Long-Term Support) for existing integrations only, which is stable and will continue to be maintained, providing flexible and robust integrations with our platform.
{% endhint %}

### Download API v4 Specification

You can download a sample OpenAPI specification of the API v4 Enhanced here. The current specification is always available at <https://api.parcellab.com/v4/openapi/>.

{% file src="/files/zqENC8zXK0eXPHaskYna" %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.parcellab.com/docs/developers/getting-started/quickstart-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.