Guides
llms.txtMCP
Start typing to searchā€¦

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 -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 -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 -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 -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

ParameterTypeDescriptionExample
offsetnumberSkip this many records (default: 0)offset=50
limitnumberMaximum records to return (default: 50)limit=25
statusstringFilter by one or more statuses (comma-separated): APPROVING, APPROVED, REJECTED, FULFILLED, PARTIALLY_FULFILLED, CANCELLEDstatus=APPROVING,APPROVED
sortFieldstringSort field: CREATED_AT, UPDATED_AT (default: CREATED_AT)sortField=UPDATED_AT
sortDirectionstringSort direction: ASC, DESC (default: ASC)sortDirection=DESC
createdAtFromstringFilter by creation timestamp from this value (ISO 8601 datetime)createdAtFrom=2024-01-01T00:00:00.000Z
createdAtTostringFilter by creation timestamp up to this value (ISO 8601 datetime)createdAtTo=2024-01-31T23:59:59.999Z
updatedAtFromstringFilter by update timestamp from this value (ISO 8601 datetime)updatedAtFrom=2024-02-01T00:00:00.000Z
updatedAtTostringFilter by update timestamp up to this value (ISO 8601 datetime)updatedAtTo=2024-02-29T23:59:59.999Z

Response Overview

The response object (PurchaseRequestsResponseDto) contains:

{
  "purchaseRequests": [...],
  "pagination": {...}
}

Pagination Object

The pagination object provides information about paging and totals:

FieldTypeDescription
pageCountnumberTotal number of available pages
pageSizenumberNumber of records in this page
totalCountnumberTotal number of purchase requests

Example:

{
  "pageCount": 3,
  "pageSize": 25,
  "totalCount": 63
}

Purchase Requests Array

Each item in purchaseRequests contains normalized purchase request data.

Fields

FieldTypeDescription
idstringUnique purchase request ID
statusstringCurrent status
supplierobjectSupplier details (optional)
titlestringPurchase request title (optional)
descriptionstringPurchase request description (optional)
requestNumberstringHuman-readable request number (optional)
grossAmountobjectGross amount (optional)
netAmountobjectNet amount (optional)
deliveryDatestringDelivery date in ISO 8601 format (optional)
notesstringAdditional notes (optional)
costCenterobjectCost center information (optional)
costObjectobjectCost object information (optional)
createdAtstringCreation timestamp (ISO 8601)
updatedAtstringLast 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)

FieldTypeRequiredDescription
purchaseRequestsarrayyesArray of purchase request records
paginationobjectyesPagination metadata
{
  "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)

FieldTypeRequiredDescription
idstringyesUnique purchase request ID
statusstringyesPurchase request status
supplierobjectnoSupplier details
titlestringnoPurchase request title
descriptionstringnoPurchase request description
requestNumberstringnoHuman-readable request number
grossAmountobjectnoGross amount object
netAmountobjectnoNet amount object
deliveryDatestringnoISO 8601 datetime
notesstringnoAdditional notes
costCenterobjectnoCost center object
costObjectobjectnoCost object object
createdAtstringyesCreation timestamp (ISO 8601)
updatedAtstringyesLast update timestamp (ISO 8601)
{
  "id": "pr-1",
  "status": "APPROVED",
  "supplier": {
    "name": "ACME Supplies 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"
  },
  "createdAt": "2024-01-02T03:04:05.000Z",
  "updatedAt": "2024-01-03T04:05:06.000Z"
}

3. PurchaseRequestSupplierResponseDto (supplier)

FieldTypeRequiredDescription
namestringyesSupplier name
accountPayableNumberstringnoAccounts payable number
accountReceivableNumberstringnoAccounts receivable number

Amount Structure

4. PurchaseRequestAmountResponseDto (grossAmount, netAmount)

FieldTypeRequiredDescription
valuenumberyesDecimal amount value
currencyCodestringyesISO currency code

grossAmount and netAmount use this structure:

{
  "value": 123.12,
  "currencyCode": "EUR"
}

Supplier Structure

{
  "name": "ACME Supplies GmbH",
  "accountPayableNumber": "AP-1001",
  "accountReceivableNumber": "AR-1001"
}

Cost Entity Structure

5. PurchaseRequestCostEntityResponseDto (costCenter, costObject)

FieldTypeRequiredDescription
codestringyesCost dimension code
namestringnoCost dimension name

Used by both costCenter and costObject:

{
  "code": "CC-1000",
  "name": "Operations"
}

6. PageInfo (pagination)

FieldTypeRequiredDescription
pageCountnumberyesTotal pages available
pageSizenumberyesNumber of items in current page
totalCountnumberyesTotal available records

Full Example Response

{
  "purchaseRequests": [
    {
      "id": "pr-1",
      "status": "APPROVED",
      "supplier": {
        "name": "ACME Supplies 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"
      },
      "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.

Updated 9 days ago