---
name: third-party-categories
description: >
  Instructs AI agents how to create, read, update, and delete third party
  categories in Kyriba, and how to add or remove third party members from them.
  Used for access control and filtering third parties in payments.
version: 1.0.0
scopes:
  - third-party-category-scope
authors:
  - kyriba
tags:
  - kyriba
  - platform
  - third-party-categories
  - api
---

> **Auth** — POST {AUTH_BASE_URL}/oauth/token · Basic base64(CLIENT_ID:CLIENT_SECRET) · no scope.
> Use token_type verbatim — do not hardcode `Bearer`. On 401: retry once with the other scheme (`token` vs `Bearer`). On 429: wait Kyriba-Customer-Rate-Limit-Reset.

# Kyriba API Skill: Third Party Categories

---

## Required Kyriba Permission

```
third-party-category-scope
```

This is a Kyriba access permission — not an OAuth scope parameter. Do NOT add `scope=` to the token request.

>  Note: scope is `third-party-category-scope` (singular).

---

##  Non-Standard Base URL

This API uses a **different base path** from all other Kyriba APIs:

```
https://api.demo.kyriba.com/api/core/third-party-categories/v1
```

All other APIs have paths under `/api/v1/...`. This API is routed under `/api/core/third-party-categories/v1/...`.

---

##  Non-Standard Pagination Parameters

This API uses `limit`/`offset` - **not** `page.limit`/`page.offset`:

```
GET /third-party-categories?limit=100&offset=0
```

---

## Endpoints

`{ref}` accepts either `uuid` or `code`.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/third-party-categories` | List categories |
| `POST` | `/third-party-categories` | Create a new category |
| `GET` | `/third-party-categories/{ref}` | Get a specific category |
| `PUT` | `/third-party-categories/{ref}` | Update a specific category |
| `DELETE` | `/third-party-categories/{ref}` | Delete a specific category |
| `POST` | `/third-party-categories/{ref}/third-parties/add` | Add third parties to a category |
| `DELETE` | `/third-party-categories/{ref}/third-parties/{thirdPartyRef}` | Remove a third party from a category |
| `GET` | `/third-party-categories/searchable-fields` | List fields available for filter/sort |
| `GET` | `/third-party-categories/documented-fields/{field}` | List valid values for a specific field |

---

## Example Requests

**List categories:**
```
GET /third-party-categories?limit=100&offset=0
```

**Create a category:**
```http
POST /third-party-categories
Content-Type: application/json

{
  "code": "CAT_SUPPLIERS",
  "description": "Approved suppliers"
}
```

**Add third parties to a category:**
```http
POST /third-party-categories/{ref}/third-parties/add
Content-Type: application/json

{
  "thirdParties": [
    { "code": "SUPPLIER_A" },
    { "code": "SUPPLIER_B" }
  ]
}
```

**Remove a third party from a category:**
```
DELETE /third-party-categories/{ref}/third-parties/{thirdPartyRef}
```

**List response:**
```json
{
  "metadata": { "total": 5, "count": 5, "limit": 100, "offset": 0 },
  "results": [
    {
      "code": "CAT_SUPPLIERS",
      "uuid": "...",
      "description": "Approved suppliers",
      "thirdParties": [
        { "code": "SUPPLIER_A", "uuid": "..." }
      ]
    }
  ]
}
```

---

## Key Fields

| Field | Description |
|---|---|
| `code` | Unique category code |
| `uuid` | System-generated identifier |
| `description` | Human-readable label. **Can be `null`**. |
| `thirdParties` | Array of member third parties |

---

## Critical Rules

1. **Different base URL** - use `https://api.demo.kyriba.com/api/core/third-party-categories/v1` (includes `/api/` before `/core/`)
2. **Different pagination** - use `limit`/`offset` not `page.limit`/`page.offset`
3. Add/remove members via dedicated sub-resource endpoints - not via PUT on the category
4. `DELETE` on a category removes it and all its third party references

---

## Use Cases

- **Data permissions:** restrict which third parties a user can see in payments
- **Payment filtering:** filter available third parties when creating a transfer
- **Segmentation:** group suppliers, customers, or financial institutions by category

---

## Error Reference

| Status | Meaning |
|---|---|
| `200` / `201` | Success |
| `400` | Invalid request |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Category or third party not found |

---

## OpenAPI Spec & Postman Collection

- OpenAPI: `https://developer.kyriba.com/static/apis/third-party-categories/third-party-categories.yaml`
- Postman: `https://developer.kyriba.com/static/apis/third-party-categories/thirdpartiescategories-postman-collection.json`