---
name: documents
description: >
  Instructs AI agents how to manage Working Capital documents (invoices, purchase
  orders, credit notes, etc.) in Kyriba. Documents are the core financial
  instruments for early payment requests in the Working Capital module.
version: 1.0.0
scopes:
  - workcap-documents-scope
authors:
  - kyriba
tags:
  - kyriba
  - working-capital
  - workcap
  - documents
  - invoices
  - 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: Documents (Working Capital)

---

## Required Kyriba Permission

```
workcap-documents-scope
```

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

---

## What are Working Capital Documents?

Documents represent financial instruments (purchase orders, invoices, credit notes, debit notes, etc.) in the Working Capital module. They are uploaded by buyers and made available for supplier early payment requests.

>  This API is part of the **Working Capital** module. Endpoints return `404` if this module is not enabled on your environment.

---

##  Non-Standard Base URL

```
servers:
  url: /workcap/v2
```

Full base URL: `https://api.demo.kyriba.com/workcap/v2`

Note the version is **`v2`**, not `v1`.

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/workcap/v2/documents` | List documents |
| `POST` | `/workcap/v2/documents` | Create a document |
| `GET` | `/workcap/v2/documents/{uuid}` | Get a specific document |
| `PUT` | `/workcap/v2/documents/{uuid}` | Update a document |
| `DELETE` | `/workcap/v2/documents/{uuid}` | Delete a document |
| `GET` | `/workcap/v2/documents/documented-fields` | List all documented field names |
| `GET` | `/workcap/v2/documents/documented-fields/{field}` | Get valid enum values for a field |
| `GET` | `/workcap/v2/documents/searchable-fields` | List all filterable field names |

**Documented-fields values for `{field}`:** `categories`, `eligibleForEarlyPayment`, `paymentMethods`, `priorities`, `statuses`, `types`, `nextApprovals`, `creditNoteStatuses`

---

## Filterable & Sortable Fields

```
uuid, type, status, buyer.code, buyer.uuid,
thirdParty.code, thirdParty.uuid,
onBehalfOf.code, onBehalfOf.uuid,
reference, supplierReference, amount,
currency.code, currency.uuid,
batchId, invoiceDate, dueDate, paymentDueDate,
earlyPaymentReference, priority, actionId,
extendedDueDate, approvalDate,
prediction.lastModelTrainingDate, prediction.lastPredictionDate, prediction.paymentDate,
creationDate, lastModificationDate
```

---

##  Non-Standard Pagination

Uses flat `offset` / `limit` - **NOT** `page.offset` / `page.limit`.

```
GET /workcap/v2/documents?offset=0&limit=100
```

| Parameter | Default | Description |
|---|---|---|
| `limit` | 100 | Records per page |
| `offset` | 0 | Starting record index |

Response envelope:
```json
{
  "metadata": {
    "links": { "current": "...", "next": "...", "prev": "..." },
    "count": 100,
    "limit": 100,
    "offset": 0
  },
  "results": [ ... ]
}
```

Detect end of pages: stop when `count < limit` OR when `metadata.links.next` is absent.

---

## Example Requests

**List approved invoices for a supplier:**
```
GET /workcap/v2/documents?filter=thirdParty.code==SUPPLIER_A;type==INVOICE;status==APPROVED&sort=dueDate&offset=0&limit=100
```

**GET list response:**
```json
{
  "metadata": {
    "pageLimit": 100,
    "pageOffset": 0,
    "pageResults": 2,
    "numberOfTotalResults": 2
  },
  "results": [ ... ]
}
```
> Response key is always `results`. Stop paginating when `len(results) < pageLimit`.

**List documents for a buyer:**
```
GET /workcap/v2/documents?filter=buyer.code==COMP_FR&offset=0&limit=100
```

**Get valid status values:**
```
GET /workcap/v2/documents/documented-fields/statuses
```

**Get valid type values:**
```
GET /workcap/v2/documents/documented-fields/types
```

**Create a document:**
```http
POST /workcap/v2/documents
Content-Type: application/json

{
  "reference": "INV-2025-001",
  "type": "INVOICE",
  "invoiceDate": "2025-07-01",
  "dueDate": "2025-08-01",
  "amount": 15000.00,
  "currency": { "code": "EUR" },
  "thirdParty": { "code": "SUPPLIER_A" },
  "buyer": { "code": "COMP_FR" }
}
```

**Create response:** `{ "uuid": "..." }`

---

## Key Fields

| Field | Description |
|---|---|
| `uuid` | System-generated identifier |
| `reference` | Buyer's document reference number (not `documentNumber`) |
| `supplierReference` | Supplier's own reference |
| `type` | Document type - use `/documented-fields/types` for valid values |
| `status` | Document lifecycle status - use `/documented-fields/statuses` for valid values |
| `invoiceDate` | Invoice issue date `YYYY-MM-DD` (not `issueDate`) |
| `dueDate` | Payment due date `YYYY-MM-DD` |
| `paymentDueDate` | Adjusted payment due date |
| `earlyPaymentReference` | Reference for early payment request |
| `amount` | Document amount (number) |
| `currency` | `{ "code": "ISO3", "uuid": "..." }` |
| `thirdParty` | Supplier third party ref (not `supplier`) |
| `buyer` | Buyer company ref |
| `onBehalfOf` | Company on whose behalf the document is created |
| `batchId` | Batch upload identifier |
| `priority` | Processing priority - use `/documented-fields/priorities` for valid values |
| `documentCategory` | e.g. `BUYER_MANAGED_PAYABLE` |
| `eligibleForEarlyPayment` | e.g. `YES`, `NO` - use `/documented-fields/eligibleForEarlyPayment` |
| `prediction` | AI-predicted payment date `{ lastModelTrainingDate, lastPredictionDate, paymentDate }` |

---

##  Common Mistakes

| Wrong | Correct |
|---|---|
| Base path `/v1/supply-chain-finance/documents` | `/workcap/v2/documents` |
| Scope `document-scope` | `workcap-documents-scope` |
| Field `supplier` | Field `thirdParty` |
| Field `documentNumber` | Field `reference` |
| Field `issueDate` | Field `invoiceDate` |
| Pagination `page.limit` / `page.offset` | Flat `limit` / `offset` |

---

## Critical Rules

1. `uuid` is auto-generated - do not include in POST body
2. `thirdParty` and `buyer` are required on create
3. Use `GET /documents/documented-fields/statuses` and `/types` to get valid enum values - do not hardcode them
4. Immutability rules vary by status - check documented fields for allowed transitions
5. `404` on any endpoint = Working Capital module not enabled on this environment

---

## Error Reference

| Status | Meaning |
|---|---|
| `201` | Created - returns `{ "uuid": "..." }` |
| `400` | Missing required fields or invalid data |
| `401` | Authentication required |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Document not found or module not enabled |
| `409` | Reference already exists |

---

## OpenAPI Spec & Postman Collection

- OpenAPI: `https://developer.kyriba.com/static/apis/scf-documents/scf-documents.yaml`
- Postman: `https://developer.kyriba.com/static/apis/scf-documents/scf-documents-postman-collection.json`