# API Documentation

Build integrations with the Basecomp API. Update prize fulfilment, sync data, and automate your workflows.

## Introduction

The Basecomp API is organised around REST. It uses predictable resource-oriented URLs, accepts and returns JSON, and uses standard HTTP response codes and verbs. Field names are camelCase; requests may send either camelCase or snake_case.

## Base URL

All requests are made to the following base URL, over HTTPS.

```
https://basecomp.io/api/v1
```

## Authentication

Authenticate every request with a secret API key in the Authorization header as a Bearer token. Create and manage keys in your dashboard under Settings → API Keys. A key is shown only once at creation, so store it securely and never expose it in client-side code.

```bash
curl https://basecomp.io/api/v1/private/me \
  -H "Authorization: Bearer sk_your_api_key"
```

A missing or invalid key returns 401.

## Scopes

Each key carries a set of scopes that limit what it can do. Give a third party (e.g. a supplier automating dispatch in Zapier) a fulfilment-only key so a leak can never touch the rest of your store. A request whose key lacks the required scope returns 403 with code INSUFFICIENT_SCOPE.

**Scopes**

| Name | Type | Description |
| --- | --- | --- |
| `winners:read` | scope | List and fetch winners. |
| `winners:write` | scope | Update a winner's prize fulfilment status. |
| `orders:read` | scope | List and fetch orders. |
| `customers:read` | scope | List and fetch customers. |
| `competitions:read` | scope | List and fetch competitions. |
| `*` | scope | Full access to every endpoint. Use only for your own server-side integrations. |

## Pagination

List endpoints return newest-first and use cursor pagination. Pass ?limit (1-100, default 25) to size each page, and ?cursor with the meta.nextCursor value to fetch the next page. meta.hasMore is false on the last page. Cursors are stable as new records are created, which makes them safe for polling.

```json
{
  "data": [ /* ... */ ],
  "meta": {
    "perPage": 25,
    "nextCursor": "eyJpZCI6...",
    "prevCursor": null,
    "hasMore": true
  }
}
```

## Rate limits

Authenticated endpoints are limited to 120 requests per minute, per key. Exceeding the limit returns 429 with code RATE_LIMITED.

## Errors

The API uses conventional HTTP status codes: 2xx for success, 4xx for a problem with the request, and 5xx for a server error. Every error returns the same JSON shape with a stable, machine-readable code.

```json
{
  "error": {
    "message": "The given data was invalid.",
    "code": "VALIDATION_ERROR",
    "details": { "validationErrors": { "fulfillment_status": ["..."] } }
  }
}
```

**Common codes**

| Name | Type | Description |
| --- | --- | --- |
| `UNAUTHENTICATED` | 401 | Missing or invalid API key. |
| `INSUFFICIENT_SCOPE` | 403 | The key lacks the scope this endpoint requires. |
| `NOT_FOUND` | 404 | The resource does not exist, or does not belong to your store. |
| `VALIDATION_ERROR` | 422 | The request body failed validation. See details.validationErrors. |
| `WINNER_NOT_FULFILLABLE` | 422 | The winner cannot be fulfilled (not claimed, converted to cash/credit, or has no shipping address). |
| `RATE_LIMITED` | 429 | Too many requests. |

## List winners

`GET /api/v1/private/winners` · 120 requests / minute

Returns the store's winners, newest first, each with its prize, competition and customer. Cursor-paginated.

**Query parameters**

| Name | Type | Description |
| --- | --- | --- |
| `fulfillment_status` | string | Filter by pending, processing, shipped, delivered or unfillable. |
| `status` | string | Filter by winner status (e.g. won, claimed). |
| `type` | string | Filter by instant_win or main_prize. |
| `since` | string | Only winners created on or after this date. |
| `limit` | integer | Page size, 1-100 (default 25). |
| `cursor` | string | meta.nextCursor from the previous page. |

```bash
curl "https://basecomp.io/api/v1/private/winners?fulfillment_status=shipped&limit=25" \
  -H "Authorization: Bearer sk_your_api_key"
```

## Get winner

`GET /api/v1/private/winners/{id}` · 120 requests / minute

Fetch a single winner by id, scoped to your store.

```bash
curl https://basecomp.io/api/v1/private/winners/win_abc123 \
  -H "Authorization: Bearer sk_your_api_key"
```

## Update fulfilment status

`PATCH /api/v1/private/winners/{id}` · 120 requests / minute

Update a winner's prize fulfilment status. The most common use is marking a claim as shipped from a supplier's system: when the status becomes shipped, the winner is automatically emailed (once) with any tracking details, and a prize.shipped webhook fires.

The winner must belong to your store, and be a claimed, non-converted physical prize with a shipping address.

**Body**

| Name | Type | Description |
| --- | --- | --- |
| `fulfillment_status` | string | One of: processing, shipped, delivered, unfillable. Required unless supplier_order_number is supplied, in which case the winner is marked shipped automatically. |
| `supplier_order_number` | string | The supplier's own order reference. Recording one (with no fulfillment_status) marks the prize shipped and emails the winner. |
| `tracking_number` | string | Carrier tracking number. |
| `tracking_url` | string | Carrier tracking URL. |
| `notes` | string | Internal fulfilment note. |
| `unfillable_reason` | string | Required when fulfillment_status is unfillable. |
| `notify_customer` | boolean | Whether to email the winner when shipping. Defaults to true. Does not affect the webhook. |

```bash
curl -X PATCH https://basecomp.io/api/v1/private/winners/win_abc123 \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "fulfillment_status": "shipped",
    "tracking_number": "AB123456789GB",
    "tracking_url": "https://royalmail.com/track/AB123456789GB"
  }'
```

## List orders

`GET /api/v1/private/orders` · 120 requests / minute

Returns the store's orders, newest first. Cursor-paginated. Amounts are integers in the smallest currency unit (e.g. pence).

**Query parameters**

| Name | Type | Description |
| --- | --- | --- |
| `status` | string | Filter by order status. |
| `since` | string | Only orders created on or after this date. |
| `limit` | integer | Page size, 1-100 (default 25). |
| `cursor` | string | meta.nextCursor from the previous page. |

```bash
curl "https://basecomp.io/api/v1/private/orders?status=completed" \
  -H "Authorization: Bearer sk_your_api_key"
```

## Get order

`GET /api/v1/private/orders/{id}` · 120 requests / minute

Fetch a single order by id, scoped to your store.

## List customers

`GET /api/v1/private/customers` · 120 requests / minute

Returns the store's customers, newest first. Cursor-paginated.

**Query parameters**

| Name | Type | Description |
| --- | --- | --- |
| `status` | string | Filter by customer status. |
| `email` | string | Filter by exact email address. |
| `since` | string | Only customers created on or after this date. |
| `limit` | integer | Page size, 1-100 (default 25). |
| `cursor` | string | meta.nextCursor from the previous page. |

```bash
curl "https://basecomp.io/api/v1/private/customers?email=jane@example.com" \
  -H "Authorization: Bearer sk_your_api_key"
```

## Get customer

`GET /api/v1/private/customers/{id}` · 120 requests / minute

Fetch a single customer by id, scoped to your store.

## List competitions

`GET /api/v1/private/competitions` · 120 requests / minute

Returns the store's competitions, newest first. Cursor-paginated.

**Query parameters**

| Name | Type | Description |
| --- | --- | --- |
| `status` | string | Filter by competition status. |
| `since` | string | Only competitions created on or after this date. |
| `limit` | integer | Page size, 1-100 (default 25). |
| `cursor` | string | meta.nextCursor from the previous page. |

```bash
curl "https://basecomp.io/api/v1/private/competitions?status=active" \
  -H "Authorization: Bearer sk_your_api_key"
```

## Get competition

`GET /api/v1/private/competitions/{id}` · 120 requests / minute

Fetch a single competition by id, scoped to your store.
