# Quickstart (/quickstart)

Read your first ticket and its messages over REST in a few minutes.

Use `curl` to find a ticket, read it, and retrieve its messages.
Prefer to work from an AI assistant? [Connect with MCP](/mcp) instead.

## Before you begin [#before-you-begin]

You need:

* A terminal or server environment with `curl`.
* An [API key](/api-keys) with `context:read` and access to the mailbox and store.
* At least one ticket: a stored conversation the support classifier judged a
  support request.

This walkthrough reads stored data without contacting providers.

## Read a ticket [#read-a-ticket]

### Set your connection details [#set-your-connection-details]

Load `ECOMSQUAD_API_KEY` from your secret manager into this environment.

```sh title="Terminal"
export ECOMSQUAD_API_BASE_URL='https://api.meetwillow.cx/api/v1'
# Set ECOMSQUAD_API_KEY securely in this environment before continuing.
```

The organization is resolved from the key. You do not send an organization ID.
API keys are for server-side use; do not embed one in frontend JavaScript.

### Find a ticket [#find-a-ticket]

```sh title="Terminal"
curl --fail-with-body --silent --show-error \
  --header "x-api-key: ${ECOMSQUAD_API_KEY:?Set ECOMSQUAD_API_KEY first}" \
  "${ECOMSQUAD_API_BASE_URL}/tickets?limit=5"
```

The response contains `items` and `nextCursor`. This is a synthetic example;
the IDs are illustrative and will not exist in your organization:

```json title="Example response — synthetic data"
{
  "items": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "conversationId": "11111111-1111-4111-8111-111111111111",
      "customer": {
        "email": "customer@example.invalid",
        "name": "Example customer",
        "stores": [],
        "orderHistory": {
          "orders": [],
          "ordersOmitted": 0,
          "omittedForAccess": 0,
          "ordersSince": [],
          "totalSpend": []
        },
        "conversationHistory": { "conversations": [], "omitted": 0 }
      },
      "conversation": {
        "subject": "Where is my order?",
        "customerName": "Example customer",
        "status": "open",
        "messageCount": 1,
        "lastMessageAt": "2026-09-01T10:00:00.000Z",
        "archivedAt": null
      },
      "orders": [],
      "checkedAt": "2026-09-01T10:02:00.000Z",
      "createdAt": "2026-09-01T10:02:00.000Z",
      "updatedAt": "2026-09-01T10:02:00.000Z"
    }
  ],
  "nextCursor": null
}
```

Choose an `items[].id` from your actual response. If `items` is empty, check the
mailbox's data and your key's connection access before continuing; see
[List tickets](/reference/tickets#list-tickets) for which conversations have a ticket.

### Read the ticket [#read-the-ticket]

Replace this example ID with the one you received:

```sh title="Terminal"
export ECOMSQUAD_TICKET_ID='33333333-3333-4333-8333-333333333333'

curl --fail-with-body --silent --show-error \
  --header "x-api-key: ${ECOMSQUAD_API_KEY:?Set ECOMSQUAD_API_KEY first}" \
  "${ECOMSQUAD_API_BASE_URL}/tickets/${ECOMSQUAD_TICKET_ID}"
```

The response is the ticket with its `orders`. Check each order's `matchedBy`,
`verified` and `details` before relying on it. An HTTP success means the read
succeeded; it does not mean an order was found or recently checked. See
[Tickets](/tickets#linked-orders).

### Read its messages [#read-its-messages]

```sh title="Terminal"
curl --fail-with-body --silent --show-error \
  --header "x-api-key: ${ECOMSQUAD_API_KEY:?Set ECOMSQUAD_API_KEY first}" \
  "${ECOMSQUAD_API_BASE_URL}/tickets/${ECOMSQUAD_TICKET_ID}/messages?limit=20"
```

You should receive a `conversation` summary, an `items` array of messages in
oldest-first order, and a `nextCursor` for another page.

<Callout type="success" title="Check your result">
  You can list tickets, read one, and retrieve its available messages with the same key. Check each
  order's `verified` and `details` before relying on order information.
</Callout>

## Common problems [#common-problems]

* **HTTP 401 or 403:** check the `x-api-key` value, expiry, and `context:read`
  permission. Use an EcomSquad API key, not an EcomConnect agent key.
* **An empty ticket list:** check mailbox data and the key's connection limits.
  Use an ID returned by your own request rather than the synthetic ID above.

For other responses, see [API troubleshooting](/troubleshooting#api-requests-fail).

## Next steps [#next-steps]

* [Tickets](/tickets) explains linked and verified orders before you rely on
  them, and when to [refresh](/tickets#refresh-a-ticket) a ticket.
* The [API Reference](/reference) lists every endpoint, field, and error, including
  [pagination](/reference#pagination).