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

# Reconcile your roster

> GET /v1/partners/sponsorships — list and inspect your sponsored seats for reconciliation.

<Note>
  **Restricted — requires a sponsorship program.** See the
  [Sponsorship API overview](/sponsorships/overview) for access and auth.
</Note>

Two read endpoints let you reconcile your program against your own records:
list the whole roster, or fetch one seat. Both are scoped to your partner —
you only ever see your own seats.

## List seats

```http theme={null}
GET /v1/partners/sponsorships
Authorization: Basic <base64(client_id:client_secret)>
```

Returns your seats, newest first, keyset-paginated.

### Query parameters

| Parameter | Type    | Default | Notes                                                                                   |
| --------- | ------- | ------- | --------------------------------------------------------------------------------------- |
| `status`  | string  | —       | Filter to one [lifecycle status](/sponsorships/overview#seat-lifecycle), e.g. `active`. |
| `limit`   | integer | `50`    | Page size, `1`–`200`.                                                                   |
| `cursor`  | string  | —       | Opaque cursor from a prior page's `next_cursor`. Omit for the first page.               |

### Response

| Field         | Type           | Notes                                                             |
| ------------- | -------------- | ----------------------------------------------------------------- |
| `items`       | array          | The seats on this page (see fields below).                        |
| `next_cursor` | string \| null | Pass back as `cursor` for the next page. `null` on the last page. |

Each item:

| Field            | Type           | Notes                                                      |
| ---------------- | -------------- | ---------------------------------------------------------- |
| `sponsorship_id` | string         | The seat id.                                               |
| `email`          | string         | Normalised member email.                                   |
| `crew_name`      | string \| null | Member's display name, once known.                         |
| `status`         | string         | [Lifecycle status](/sponsorships/overview#seat-lifecycle). |
| `external_ref`   | string \| null | The reference you supplied at provision time.              |
| `invited_at`     | string \| null | When the seat record was created.                          |
| `activated_at`   | string \| null | When Premium was granted.                                  |
| `expires_at`     | string \| null | The member's sponsored term end.                           |

```json theme={null}
{
  "items": [
    {
      "sponsorship_id": "665f00000000000000000042",
      "email": "jane@example.com",
      "crew_name": "Jane Doe",
      "status": "active",
      "external_ref": "ref-0042",
      "invited_at": "2026-07-03T09:00:00Z",
      "activated_at": "2026-07-04T10:30:00Z",
      "expires_at": "2027-07-04T10:30:00Z"
    }
  ],
  "next_cursor": null
}
```

### Paging through the whole roster

```bash theme={null}
cursor=""
while :; do
  page=$(curl -s -u "$DSS_CLIENT_ID:$DSS_CLIENT_SECRET" \
    "https://api.digitalseaservice.com/v1/partners/sponsorships?limit=200&cursor=$cursor")
  echo "$page" | jq -c '.items[]'
  cursor=$(echo "$page" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done
```

<Tip>
  Filter by `status=active` to reconcile exactly the seats you're currently
  being billed for. Match rows to your own records on `external_ref`.
</Tip>

## Get one seat

```http theme={null}
GET /v1/partners/sponsorships/{sponsorship_id}
Authorization: Basic <base64(client_id:client_secret)>
```

Returns a single seat in the same item shape as the list. A `sponsorship_id`
that belongs to a different partner resolves to
[`not_found` (404)](/errors/not_found), never `403` — we don't confirm the
existence of another partner's seats.

```json theme={null}
{
  "sponsorship_id": "665f00000000000000000042",
  "email": "jane@example.com",
  "crew_name": "Jane Doe",
  "status": "active",
  "external_ref": "ref-0042",
  "invited_at": "2026-07-03T09:00:00Z",
  "activated_at": "2026-07-04T10:30:00Z",
  "expires_at": "2027-07-04T10:30:00Z"
}
```

## Errors

| Status | `type`                                             | When                                          |
| ------ | -------------------------------------------------- | --------------------------------------------- |
| 401    | [`invalid_token`](/errors/invalid_token)           | Missing or bad Basic credentials.             |
| 403    | [`insufficient_scope`](/errors/insufficient_scope) | The partner account is suspended.             |
| 404    | [`not_found`](/errors/not_found)                   | No such seat for this partner (get-one only). |

## Related

* [Provision a seat](/sponsorships/provision)
* [Remove a seat](/sponsorships/remove)
* [Sponsorship API overview](/sponsorships/overview)