# Instellix core API research

Verified 2026-10-12 against official production reference pages unless expressly marked preview. Base URL shown by production docs: `https://api.instellix.io`. Paths below include `/v2`. No live API requests made.

## Customers / Identity

- `POST /v2/customers` → 201. Customer requires unique `ident` and at least one address. `ident` is an external reference, 1–100 characters, pattern `[a-zA-Z0-9_.~-]{1,100}`. Other entities link through it. Addresses have `INVOICE` or `SHIPPING` type; type cannot change after creation. `addressIdent` is optional; omission generates a UUID. Country is required. Invoice address + delivery `EMAIL` requires email. Use `customerType` B2B/B2C/AFFILIATED and ISO 639-1 language matching business segment. [Create customer](https://docs.instellix.io/reference/createcustomer)
- `GET /v2/customers/{ident}` → 200. Looks up the external reference. `slimResponse=false` by default; true omits nested collections such as addresses. [Retrieve customer](https://docs.instellix.io/reference/getcustomer)
- `GET /v2/customers/pageable` → 200. RSQL `search`, example `ident==client123`. Defaults: `pageNumber=0`, `pageSize=100`, `orderBy=ident`, `direction=DESC`, `slimResponse=true`. Full responses include nested collections and are explicitly discouraged for lists. [Query customers](https://docs.instellix.io/reference/querycustomers)
- Portal: Billing → Customers → Customer Overview. “Debtor Ident” is the external customer identifier; debtor account number and contractor reference are separate concepts. [Manage customers](https://docs.instellix.io/docs/manage-customers)

## Contracts

- `POST /v2/contracts` → 201. Connects an existing customer with a configured plan. `contractIdent` is unique, immutable, 1–100 characters with `[a-zA-Z0-9_.~-]{1,100}`. Prefer `debtorIdent`, `planIdent`, `invoiceAddressIdent`, `shippingAddressIdent`, `businessSegmentIdent` over deprecated numeric references. `billingStartDate` defaults to `startDate` when omitted. Explicit termination is preferred over deprecated `endDate`. [Create contract](https://docs.instellix.io/reference/createcontract)
- `GET /v2/contracts/pageable` → 200. RSQL search. Defaults: `pageNumber=0`, `pageSize=100`, `orderBy=contractId`, `direction=DESC`, `slimResponse=true`. Slim omits attachments and purchase items. Searches on `taxLocation` or `performanceLocation` also include historic values. [Query contracts](https://docs.instellix.io/reference/querycontractspageable)
- `PATCH /v2/contracts/{contractId}` → 200. Numeric ID is used by this update route. Do not use a patch of plan/start/end fields to start a subscription. `startDate` is deprecated here: use activation. `endDate` is deprecated: use termination. Updating `properties` replaces the whole list. [Update contract](https://docs.instellix.io/reference/updatecontract)
- Portal: Billing → Contracts → Contract Overview → Add; choose plan then customer. Plan supplies billing terms and options. Automatic collection requires selecting a customer payment account. [Contracts guide](https://docs.instellix.io/docs/create-contracts)
- Preview-only verification: `GET /v2/contracts/{contractId}` retrieves numeric ID; docs suggest RSQL `contractIdent==...` for external reference. Production route page could not be fetched, so avoid presenting this as independently verified production. [Preview retrieve contract](https://docs.instellix.io/v2-preview/reference/retrievecontract)
- Preview-only verification: `POST /v2/contracts/{contractIdent}/actions/activate` → 204, accepts new `startDate` and optional `billingStartDate`. [Preview activation](https://docs.instellix.io/v2-preview/reference/activatecontract)

## Documents

- `GET /v2/documents` → 200. RSQL example `type==INVOICE`. Defaults: `page=0`, `size=20` (max 100), `sort=ident` ascending. Repeatable sorting criteria use `property,asc` / `property,desc`; direction is case-insensitive. Notice pagination differs from customers/contracts. [Query documents](https://docs.instellix.io/reference/querydocuments)
- `GET /v2/documents/{documentIdent}` → 200. Retrieves structured document by ident. [Retrieve document](https://docs.instellix.io/reference/getdocument)
- A billable item is a charge awaiting billing. Billing runs collect due items by processing date and create structured documents; grouping/splitting follows billing-group configuration. File creation/delivery follows afterward in document provisioning. [Billing run](https://docs.instellix.io/docs/start-a-billing-run)
- Portal: Billing → Documents; choose Invoices, Credit Notes, Deposit Invoices, Deposit Credit Notes, Self-Billing Invoices, or Self-Billing Invoice Corrections. Invoice details provide payment intent and address correction; the guide says an invoice can be corrected only once. [Manage documents](https://docs.instellix.io/docs/manage-documents)

## Files / PDF

- `GET /v2/files/{fileIdent}` → 200. `fileIdent` equals document ident / invoiceIdent. Explicit `Accept: application/pdf` for PDF download; supported Accept values also include application/json, application/octet-stream and text/xml. Default Accept in docs is application/json. [Retrieve a file](https://docs.instellix.io/reference/getfile)
- Event source: [Webhook reference](https://docs.instellix.io/reference/notificationswebhooks)
- PDF accessibility and template selection are maintained in Configuration → Billing → Document Provisioning; no dedicated public configuration API. Download generated output through Files API. [PDF output](https://docs.instellix.io/docs/pdf-output)
- Upload attachments on contract/order details, open/download them on document details. Upload max 1 MB. Attachments do not change document amounts. [Document attachments](https://docs.instellix.io/docs/document-attachments)
- File upload uses a whitelist including PDF, csv/xml/json and supported Office/text formats. [File type whitelisting](https://docs.instellix.io/docs/file-type-whitelisting)

## Copy examples (placeholders, not executable credentials)

```text
GET /v2/customers/pageable?search=ident%3D%3Dclient123&pageNumber=0&pageSize=100
GET /v2/contracts/pageable?pageNumber=0&pageSize=100&orderBy=contractId&direction=DESC
GET /v2/documents?search=type%3D%3DINVOICE&page=0&size=20&sort=ident,asc
GET /v2/documents/{documentIdent}
GET /v2/files/{documentIdent}
Accept: application/pdf
```

Do not confuse `ident` / `debtorIdent` (external customer key), `contractIdent` (external contract key), `contractId` (numeric internal ID), or `documentIdent` / `fileIdent`. Use the specific route's parameter names. Stage/preview references use a different base (`https://api.isx-stage-westeurope.instellix.io`) and should remain visibly separated from production docs.