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

# Partner API reference

> Implemented partner endpoints, scopes, pagination, and response behavior.

All paths below are relative to the API base URL supplied by Already. Send `Authorization: Bearer <partner key>` from your server. JSON request bodies use `Content-Type: application/json`. Responses are scoped to the key's partner.

| Method | Path | Required scope | Result |
| - | - | - | - |
| `POST` | `/partner/v1/obligation-submissions` | `obligations:write` | Create or replay a candidate submission |
| `GET` | `/partner/v1/obligation-submissions` | `obligations:read` | `{ "data": [...] }` for this partner |
| `GET` | `/partner/v1/obligations` | `obligations:read` | `{ "data": [...] }` after operator approval |
| `GET` | `/partner/v1/obligations/:id` | `obligations:read` | `{ "data": {...} }`; another partner's ID returns `404` |
| `GET` | `/partner/v1/events?after=<id>&limit=50` | `events:read` | `{ "data": [...], "nextCursor": "...", "hasMore": false }` |
| `GET` | `/partner/v1/webhooks` | `webhooks:manage` | Endpoints without signing secrets |
| `POST` | `/partner/v1/webhooks` | `webhooks:manage` | Register callback; signing secret returned once |
| `DELETE` | `/partner/v1/webhooks/:id` | `webhooks:manage` | Disable this partner's endpoint; `204` |
| `POST` | `/partner/v1/webhooks/test` | `webhooks:manage` | Queue `integration.test` event |

## Submission response

New submissions return HTTP `201`; a replay with the same key returns `200` and `idempotentReplay: true`:

```json theme={null}
{
  "data": {
    "id": "<submission UUID>",
    "externalId": "INV-1001",
    "status": "received",
    "obligationId": null
  },
  "idempotentReplay": false
}
```

The actual `data` object also includes the submitted parties, amount, currency, dates, evidence reference, and review metadata. See [required submission fields](https://docs.already.finance/integrate/submissions.md).

## Event pagination

`limit` defaults to 50 and is capped at 100. Events are returned oldest first. `after` is the last processed event UUID for **this partner**. Save `nextCursor` only after processing the page. An unknown cursor returns `400`. `hasMore` tells you whether to request another page.

## Error handling

| HTTP status | Meaning | Client action |
| - | - | - |
| `400` | Invalid cursor or request shape | Correct the request |
| `401` | Missing, invalid, or revoked bearer key | Check key and environment |
| `403` | Missing scope or disallowed browser origin | Ask for correct scope; do not treat origin as authentication |
| `404` | Record not found in this partner's scope | Check the ID and partner |
| `422` | Invalid submission or callback URL | Correct the reported field |
| `429` | Per-client rate limit exceeded | Wait for `Retry-After` before retrying |

See [webhooks](https://docs.already.finance/integrate/webhooks.md) for delivery authentication and [troubleshooting](https://docs.already.finance/reference/troubleshooting.md) for common setup mistakes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.