# Partner administration

Provision and maintain partner accounts with administrative credentials.



[Authentication](/build/authentication/) · [Errors](/build/errors/) · [Amounts and units](/build/units/)


Response examples below come from a local test account. IDs, balances and timestamps are sample data. Replace IDs and credentials with values from your account.


## Create partner

`POST /partners`


Creates a partner and generates a scoped API key.


**Access:** `partner:admin`.


**SDK methods:** TypeScript `client.partners.create(…)`; Python `client.partners.create(…)`.



### Request body

Schema: [CreatePartnerInputDto](/api/partner-models/#createpartnerinputdto)


### Request example

```bash
curl --fail-with-body -X POST "$THESAUROS_API_BASE/partners" \
  -H "Authorization: Bearer $THESAUROS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Documentation fixture partner"}'
```

### Response · 201

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [PartnerCreated](/api/partner-models/#partnercreated) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "partner",
  "data": {
    "partner": {
      "id": "ptn_e9b3d67ffd98fe8d",
      "object": "partner",
      "name": "Documentation fixture partner",
      "slug": "documentation-fixture-partner",
      "contact_email": null,
      "webhook_url": null,
      "revenue_share_pct": 0.15,
      "status": "active",
      "metadata": {},
      "created_at": "2026-09-07T14:42:43.808Z",
      "updated_at": "2026-09-07T14:42:43.808Z"
    },
    "api_key": {
      "id": "key_44f85b49a1faf5b6",
      "label": "Documentation fixture partner partner key",
      "secret": "REDACTED_EXAMPLE"
    }
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## List partners

`GET /partners`


**Access:** `partner:admin`.


**SDK methods:** TypeScript `client.partners.list(…)`; Python `client.partners.list(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `status` | query | `"active"`, `"disabled"` | No |  |

### Request example

```bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/partners" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [PartnerOutputDto](/api/partner-models/#partneroutputdto)[] | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "list",
  "data": [
    {
      "id": "ptn_seed_acme",
      "object": "partner",
      "name": "Acme Wallet",
      "slug": "acme-wallet",
      "contact_email": "dev@acmewallet.example",
      "webhook_url": null,
      "revenue_share_pct": 0.15,
      "status": "active",
      "metadata": {},
      "created_at": "2026-05-29T12:00:00.000Z",
      "updated_at": "2026-07-26T12:00:00.000Z"
    },
    {
      "id": "ptn_seed_orbit",
      "object": "partner",
      "name": "Orbit Finance",
      "slug": "orbit-finance",
      "contact_email": "integrations@orbitfinance.example",
      "webhook_url": "https://orbitfinance.example/webhooks/thesauros",
      "revenue_share_pct": 0.2,
      "status": "active",
      "metadata": {},
      "created_at": "2026-06-13T12:00:00.000Z",
      "updated_at": "2026-07-23T12:00:00.000Z"
    },
    {
      "id": "ptn_e9b3d67ffd98fe8d",
      "object": "partner",
      "name": "Documentation fixture partner",
      "slug": "documentation-fixture-partner",
      "contact_email": null,
      "webhook_url": null,
      "revenue_share_pct": 0.15,
      "status": "active",
      "metadata": {},
      "created_at": "2026-09-07T14:42:43.808Z",
      "updated_at": "2026-09-07T14:42:43.808Z"
    }
  ]
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Get partner by ID

`GET /partners/{id}`


**Access:** `partner:admin`.


**SDK methods:** TypeScript `client.partners.retrieve(…)`; Python `client.partners.retrieve(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes |  |

### Request example

```bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/partners/ptn_e9b3d67ffd98fe8d" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [PartnerOutputDto](/api/partner-models/#partneroutputdto) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "partner",
  "data": {
    "id": "ptn_e9b3d67ffd98fe8d",
    "object": "partner",
    "name": "Documentation fixture partner",
    "slug": "documentation-fixture-partner",
    "contact_email": null,
    "webhook_url": null,
    "revenue_share_pct": 0.15,
    "status": "active",
    "metadata": {},
    "created_at": "2026-09-07T14:42:43.808Z",
    "updated_at": "2026-09-07T14:42:43.808Z"
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Update partner

`PATCH /partners/{id}`


Partial update. Pass status:"disabled" to soft-disable without deleting history/attributions. Disabling a partner immediately revokes all of its API keys; re-enabling does not restore them, issue a new key instead.


**Access:** `partner:admin`.


**SDK methods:** TypeScript `client.partners.update(…)`; Python `client.partners.update(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes |  |


### Request body

Schema: [UpdatePartnerInputDto](/api/partner-models/#updatepartnerinputdto)


### Request example

```bash
curl --fail-with-body -X PATCH "$THESAUROS_API_BASE/partners/ptn_e9b3d67ffd98fe8d" \
  -H "Authorization: Bearer $THESAUROS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Documentation updated partner"}'
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [PartnerOutputDto](/api/partner-models/#partneroutputdto) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "partner",
  "data": {
    "id": "ptn_e9b3d67ffd98fe8d",
    "object": "partner",
    "name": "Documentation updated partner",
    "slug": "documentation-fixture-partner",
    "contact_email": null,
    "webhook_url": null,
    "revenue_share_pct": 0.15,
    "status": "active",
    "metadata": {},
    "created_at": "2026-09-07T14:42:43.808Z",
    "updated_at": "2026-09-07T14:42:44.062Z"
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).