--- updatedAt: 2026-05-04T09:12:31.000Z agentTools: projectIndex: https://developer.candis.io/llms.txt --- # Candis Purchase Requests Data API > 🚧 Beta > > This API is a beta feature and is subject to possible changes. The API response and functionality will be updated in the future. The purchase requests endpoint allows you to retrieve purchase requests from your organization with flexible filtering, sorting, and pagination options. This guide covers both practical usage and the detailed response structure.
# List Purchase Requests - API Guide & Response Structure The `GET /v1/organizations/{organizationId}/purchase-requests` endpoint lets you retrieve purchase requests for an organization, including status/date filters and pagination controls. ## API Usage ### Basic Usage **Endpoint:** `GET /v1/organizations/{organizationId}/purchase-requests` **Authentication:** Bearer token required **Authorization:** Admin role required ### Common Use Cases #### 1. Get Recent Purchase Requests (Default) ```curl curl -X GET \ "https://api.candis.io/v1/organizations/alpha-organization/purchase-requests" \ -H "Authorization: Bearer YOUR_TOKEN" ``` This returns the first 50 purchase requests (`offset=0`, `limit=50`) sorted by `CREATED_AT` in `ASC` order. #### 2. Filter by Status and Creation Date Range ```curl curl -X GET \ "https://api.candis.io/v1/organizations/alpha-organization/purchase-requests?status=APPROVING,APPROVED&createdAtFrom=2024-01-01T00:00:00.000Z&createdAtTo=2024-01-31T23:59:59.999Z" \ -H "Authorization: Bearer YOUR_TOKEN" ``` #### 3. Filter by Last Update Range ```curl curl -X GET \ "https://api.candis.io/v1/organizations/alpha-organization/purchase-requests?updatedAtFrom=2024-02-01T00:00:00.000Z&updatedAtTo=2024-02-29T23:59:59.999Z" \ -H "Authorization: Bearer YOUR_TOKEN" ``` #### 4. Pagination with Sorting ```curl curl -X GET \ "https://api.candis.io/v1/organizations/alpha-organization/purchase-requests?offset=50&limit=25&sortField=UPDATED_AT&sortDirection=DESC" \ -H "Authorization: Bearer YOUR_TOKEN" ``` ### Query Parameters | Parameter | Type | Description | Example | | --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | `offset` | number | Skip this many records (default: `0`) | `offset=50` | | `limit` | number | Maximum records to return (default: `50`) | `limit=25` | | `status` | string | Filter by one or more statuses (comma-separated): `APPROVING`, `APPROVED`, `REJECTED`, `FULFILLED`, `PARTIALLY_FULFILLED`, `CANCELLED` | `status=APPROVING,APPROVED` | | `sortField` | string | Sort field: `CREATED_AT`, `UPDATED_AT` (default: `CREATED_AT`) | `sortField=UPDATED_AT` | | `sortDirection` | string | Sort direction: `ASC`, `DESC` (default: `ASC`) | `sortDirection=DESC` | | `createdAtFrom` | string | Filter by creation timestamp from this value (ISO 8601 datetime) | `createdAtFrom=2024-01-01T00:00:00.000Z` | | `createdAtTo` | string | Filter by creation timestamp up to this value (ISO 8601 datetime) | `createdAtTo=2024-01-31T23:59:59.999Z` | | `updatedAtFrom` | string | Filter by update timestamp from this value (ISO 8601 datetime) | `updatedAtFrom=2024-02-01T00:00:00.000Z` | | `updatedAtTo` | string | Filter by update timestamp up to this value (ISO 8601 datetime) | `updatedAtTo=2024-02-29T23:59:59.999Z` | *** ## Response Overview The response object (`PurchaseRequestsResponseDto`) contains: ```json { "purchaseRequests": [...], "pagination": {...} } ``` ## Pagination Object The `pagination` object provides information about paging and totals: | Field | Type | Description | | ------------ | ------ | --------------------------------- | | `pageCount` | number | Total number of available pages | | `pageSize` | number | Number of records in this page | | `totalCount` | number | Total number of purchase requests | **Example:** ```json { "pageCount": 3, "pageSize": 25, "totalCount": 63 } ``` ## Purchase Requests Array Each item in `purchaseRequests` contains normalized purchase request data. ### Fields | Field | Type | Description | | ---------------------- | ------ | ----------------------------------------------------------------- | | `id` | string | Unique purchase request ID | | `status` | string | Current status | | `supplier` | object | Supplier details (optional) | | `title` | string | Purchase request title (optional) | | `description` | string | Purchase request description (optional) | | `requestNumber` | string | Human-readable request number (optional) | | `grossAmount` | object | Gross amount (optional) | | `netAmount` | object | Net amount (optional) | | `deliveryDate` | string | Delivery date in ISO 8601 format (optional) | | `notes` | string | Additional notes (optional) | | `costCenter` | object | Cost center information (optional) | | `costObject` | object | Cost object information (optional) | | `extraCostInfo` | object | Extra cost information (optional) | | `generalLedgerAccount` | object | General ledger account information (optional) | | `customCategory` | object | Custom category information (optional) | | `outstandingNetAmount` | object | Remaining net amount after deducting linked invoices' net amounts | | `createdAt` | string | Creation timestamp (ISO 8601) | | `updatedAt` | string | Last update timestamp (ISO 8601) | ### Status Values `status` can be one of: * `APPROVING` * `APPROVED` * `REJECTED` * `FULFILLED` * `PARTIALLY_FULFILLED` * `CANCELLED` ### Object Field Shapes The following section documents every object shape returned by this endpoint. #### 1. `PurchaseRequestsResponseDto` (top-level response) | Field | Type | Required | Description | | ------------------ | ------ | -------- | --------------------------------- | | `purchaseRequests` | array | yes | Array of purchase request records | | `pagination` | object | yes | Pagination metadata | ```json { "purchaseRequests": [ { "id": "pr-1", "status": "APPROVED", "createdAt": "2024-01-02T03:04:05.000Z", "updatedAt": "2024-01-03T04:05:06.000Z" } ], "pagination": { "pageCount": 1, "pageSize": 50, "totalCount": 1 } } ``` #### 2. `PurchaseRequestResponseDto` (item in `purchaseRequests`) | Field | Type | Required | Description | | ---------------------- | ------ | -------- | -------------------------------- | | `id` | string | yes | Unique purchase request ID | | `status` | string | yes | Purchase request status | | `supplier` | object | no | Supplier details | | `title` | string | no | Purchase request title | | `description` | string | no | Purchase request description | | `requestNumber` | string | no | Human-readable request number | | `grossAmount` | object | no | Gross amount object | | `netAmount` | object | no | Net amount object | | `deliveryDate` | string | no | ISO 8601 datetime | | `notes` | string | no | Additional notes | | `costCenter` | object | no | Cost center object | | `costObject` | object | no | Cost object object | | `extraCostInfo` | object | no | Extra cost info | | `generalLedgerAccount` | object | no | General ledger account | | `customCategory` | object | no | Custom category | | `outstandingNetAmount` | object | no | Remaining net amount | | `createdAt` | string | yes | Creation timestamp (ISO 8601) | | `updatedAt` | string | yes | Last update timestamp (ISO 8601) | ```json { "id": "pr-1", "status": "APPROVED", "supplier": { "name": "Candis GmbH", "accountPayableNumber": "AP-1001", "accountReceivableNumber": "AR-1001" }, "title": "Office Chairs", "description": "Ergonomic chairs for the Berlin office", "requestNumber": "PR-2024-001", "grossAmount": { "value": 12.34, "currencyCode": "EUR" }, "netAmount": { "value": 10, "currencyCode": "EUR" }, "deliveryDate": "2024-02-03T04:05:06.000Z", "notes": "Please prioritize delivery this week.", "costCenter": { "code": "CC-1000", "name": "Operations" }, "costObject": { "code": "CO-1000" }, "extraCostInfo": { "code": "EX-1000", "name": "Office Supplies" }, "generalLedgerAccount": { "code": "GLA-1000", "name": "Assets" }, "customCategory": { "id": "aa8145d2-422c-4934-b6e2-29c219ab09a0", "value": "Office" }, "outstandingNetAmount": { "value": 6, "currencyCode": "EUR" }, "createdAt": "2024-01-02T03:04:05.000Z", "updatedAt": "2024-01-03T04:05:06.000Z" } ``` #### 3. `PurchaseRequestSupplierResponseDto` (`supplier`) | Field | Type | Required | Description | | ------------------------- | ------ | -------- | -------------------------- | | `name` | string | yes | Supplier name | | `accountPayableNumber` | string | no | Accounts payable number | | `accountReceivableNumber` | string | no | Accounts receivable number | ### Amount Structure #### 4. `PurchaseRequestAmountResponseDto` (`grossAmount`, `netAmount`, `outstandingNetAmount`) | Field | Type | Required | Description | | -------------- | ------ | -------- | -------------------- | | `value` | number | yes | Decimal amount value | | `currencyCode` | string | yes | ISO currency code | `grossAmount`, `netAmount`, `outstandingNetAmount` use this structure: ```json { "value": 123.12, "currencyCode": "EUR" } ``` ### Supplier Structure ```json { "name": "Candis GmbH", "accountPayableNumber": "AP-1001", "accountReceivableNumber": "AR-1001" } ``` ### Core Data Entity Structure #### 5. `PurchaseRequestCostEntityResponseDto` (`costCenter`, `costObject`, `extraCostInfo`, `generalLedgerAccount`) | Field | Type | Required | Description | | ------ | ------ | -------- | ----------- | | `code` | string | yes | Entity code | | `name` | string | no | Entity name | Used by `costCenter`, `costObject`, `extraCostInfo`, and `generalLedgerAccount`: ```json { "code": "CC-1000", "name": "Operations" } ``` ### Custom Category Structure #### 5. `PurchaseRequestCustomCategoryEntityResponseDto` (`customCategory`) | Field | Type | Required | Description | | ------- | ------------- | -------- | -------------------- | | `id` | string (UUID) | yes | Custom category id | | `value` | string | yes | Custom category name | Used by `customCategory` field: ```json { "id": "8f3d40cc-8f7c-4ee5-8ee4-f9e125934091", "name": "Office" } ``` #### 6. `PageInfo` (`pagination`) | Field | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------- | | `pageCount` | number | yes | Total pages available | | `pageSize` | number | yes | Number of items in current page | | `totalCount` | number | yes | Total available records | ## Full Example Response ```json { "purchaseRequests": [ { "id": "pr-1", "status": "APPROVED", "supplier": { "name": "Candis GmbH", "accountPayableNumber": "AP-1001", "accountReceivableNumber": "AR-1001" }, "title": "Office Chairs", "description": "Ergonomic chairs for the Berlin office", "requestNumber": "PR-2024-001", "grossAmount": { "value": 12.34, "currencyCode": "EUR" }, "netAmount": { "value": 10, "currencyCode": "EUR" }, "deliveryDate": "2024-02-03T04:05:06.000Z", "notes": "Please prioritize delivery this week.", "costCenter": { "code": "CC-1000", "name": "Operations" }, "costObject": { "code": "CO-1000" }, "extraCostInfo": { "code": "EX-1000", "name": "Office Supplies" }, "generalLedgerAccount": { "code": "GLA-1000", "name": "Assets" }, "customCategory": { "id": "aa8145d2-422c-4934-b6e2-29c219ab09a0", "value": "Office" }, "outstandingNetAmount": { "value": 6, "currencyCode": "EUR" }, "createdAt": "2024-01-02T03:04:05.000Z", "updatedAt": "2024-01-03T04:05:06.000Z" } ], "pagination": { "pageCount": 1, "pageSize": 50, "totalCount": 1 } } ``` ## Best Practices 1. If you only need finalized purchase requests, filter the status field to `APPROVED,FULFILLED,PARTIALLY_FULFILLED,CANCELLED` to prevent status changes between sync cycles. 2. Use `status` filters when syncing workflow-specific records (for example, only `APPROVING` and `APPROVED`). 3. Use `updatedAtFrom` and `updatedAtTo` for incremental sync jobs. 4. Keep `limit` moderate (for example 25-100) to balance throughput and response size. 5. Always handle optional fields defensively because supplier, amount, and cost fields may be missing. 6. Persist `id` and `updatedAt` to support idempotent, resumable processing. This structure gives you everything needed to list and process purchase requests reliably.