canonical: https://jentic.com/apis/candis.io/candis

# Candis API

Jentic publishes the only available OpenAPI specification for Candis API, keeping it validated and agent-ready. The Candis API exposes the AP automation platform's accounting data: it exports approved invoices and their postings for downstream ledgers, lets external systems import and update core master data such as general ledger accounts, contacts, cost dimensions, tax codes, payment conditions, and additional delivery costs, and provides direct file downloads for archived invoice documents. Nineteen endpoints span 10 resources and use bearer-JWT authentication tied to a single Candis organisation.

## For AI agents

Export approved invoice postings from Candis, sync master data such as ledger accounts and contacts, and download invoice files.

## Scope

Does not handle invoice capture UI, approval-workflow configuration, or payment execution - use for exporting approved invoice postings and syncing accounting master data only.

## Capabilities

- Export approved invoice batches for posting to a downstream accounting ledger via `/organizations/{organizationId}/exports`
- Retrieve the line-item postings for a specific export via `/exports/{exportId}/postings`
- Sync master data including general ledger accounts, contacts, cost dimensions, tax codes, and payment conditions via the /imports/* endpoints
- Update existing master-data records via PUT on the same /imports/* endpoints
- Track the status of import jobs via `/organizations/{organizationId}/imports/{processId}`
- Download archived invoice files by ID via `/organizations/{organizationId}/files/{fileId}`
- Read organisation metadata via `/organizations/info` to scope subsequent calls

## Use cases

### Approved Invoice Export to ERP

Finance teams using Candis for invoice capture and approval need to push approved invoices into their general ledger system on a schedule. POST `/organizations/{organizationId}/exports` creates an export batch, GET `/exports/{exportId}/postings` returns the booked postings, and the resulting payload feeds directly into ERPs such as DATEV, SAP, or NetSuite.

Example prompt: POST `/organizations/{organizationId}/exports` to create the daily export, then GET `/exports/{exportId}/postings` and write each posting to the ERP's journal-entry endpoint.

### Master Data Synchronisation from ERP

When master data changes in the ERP (new vendors, ledger accounts, cost centres, tax codes), those updates must flow into Candis so AP coding stays consistent. The /imports/* endpoints accept POST to seed and PUT to update, and `/imports/{processId}` reports per-job processing status so the integration can retry failures.

Example prompt: POST `/organizations/{organizationId}/imports/contacts` with the latest vendor list from the ERP, then poll GET `/imports/{processId}` until the job reports completion.

### Audit and Document Retrieval

Auditors and finance ops sometimes need to pull the original invoice document for a specific posting. The export response references file IDs that GET `/organizations/{organizationId}/files/{fileId}` resolves to the archived document, letting an audit bot download supporting evidence on demand.

Example prompt: Resolve the fileId from a posting via GET `/organizations/{organizationId}/exports/{exportId}/postings`, then GET `/organizations/{organizationId}/files/{fileId}` to download the original PDF.

### AI Agent AP Workflows via Jentic

Through Jentic, an agent searches for 'export approved invoices from Candis', loads the input schema for `/organizations/{organizationId}/exports`, and executes the call without managing the bearer JWT. Jentic's vault holds the token so it never enters the agent's prompt context.

Example prompt: Use the Jentic SDK to search 'export approved invoices', load the POST `/organizations/{organizationId}/exports` operation schema, and execute it for the org ID returned by `/organizations/info.`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/organizations/info` | Get organisation information |
| POST | `/organizations/{organizationId}/exports` | Create an export of approved invoices |
| GET | `/organizations/{organizationId}/exports/{exportId}/postings` | Retrieve postings for an export |
| POST | `/organizations/{organizationId}/imports/general-ledger-accounts` | Import general ledger accounts |
| POST | `/organizations/{organizationId}/imports/contacts` | Import contacts |
| POST | `/organizations/{organizationId}/imports/tax-codes` | Import tax codes |
| GET | `/organizations/{organizationId}/files/{fileId}` | Download an invoice file by ID |

## Key resources

- **Organizations** — Read organisation metadata used to scope subsequent calls
- **Exports** — Create and retrieve invoice export batches with postings
- **General Ledger Accounts** — Import and update ledger accounts as Candis master data
- **Cost Dimensions** — Import and update cost-centre dimensions
- **Tax Codes** — Import and update tax codes
- **Contacts** — Import and update vendor and customer contacts
- **Payment Conditions** — Import and update payment terms
- **Additional Delivery Costs** — Import and update delivery-cost master data
- **Import Logs** — Track the status and errors of master-data import jobs
- **Files** — Download archived invoice documents by ID

## Why Jentic

- **Setup:** Wiring the Candis API by hand means managing its bearer token and finding the right export and master-data import routes yourself. Through Jentic you install once, import Candis from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Candis puts the organization id in the URL path (`/organizations/{organizationId}/...`), so a rule can pin your agent to one organization: it can read that organization's exports and nothing else. You choose the operations it may call, so imports of ledger accounts, contacts, or tax codes are not included unless you add them.
- **Credential handling:** Your Candis bearer token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'export approved invoice postings' or 'import general ledger accounts', and Jentic returns the matching Candis operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Xero Accounting API** — Xero is a full general-ledger accounting platform, where Candis focuses specifically on AP automation that exports into a separate ledger.
- **Spendesk API** — Spendesk covers spend management including cards, requests, and invoices, where Candis specialises in invoice capture, approval, and ERP export.
- **Bill.com API** — Bill.com handles AP payments and approvals in the U.S. market, complementing Candis's strength in European AP capture and DATEV-style export.

## FAQ

### Why is there no official OpenAPI spec for Candis API?

Candis documents its API in HTML on developer.candis.io but does not publish a redistributable OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Candis API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Candis API use?

It uses HTTP Bearer authentication with a JWT issued by Candis. Through Jentic, the JWT is stored in your Jentic One instance and injected into the Authorization header at execution time, so the raw token never enters the agent's prompt context.

### Can I export approved invoices for posting to my ERP?

Yes. POST `/organizations/{organizationId}/exports` creates an export batch from approved invoices, and GET `/organizations/{organizationId}/exports/{exportId}/postings` returns the line-item postings ready for journal entries in DATEV, NetSuite, or another ledger.

### How do I sync ledger accounts into Candis through Jentic?

Run pip install jentic, then search 'sync ledger accounts to Candis' through the Jentic SDK. Jentic returns POST `/organizations/{organizationId}/imports/general-ledger-accounts` with its input schema. Provide the organisation ID and the account list, then poll GET `/organizations/{organizationId}/imports/{processId}` for job completion.

### Are master-data imports synchronous or asynchronous?

Imports are asynchronous. Each POST or PUT to an /imports/* endpoint returns a process ID; poll GET `/organizations/{organizationId}/imports/{processId}` to retrieve the per-record processing status and any per-row errors before treating the job as complete.

### How do I download the original invoice document for a posting?

Take the file ID from the posting returned by `/exports/{exportId}/postings` and call GET `/organizations/{organizationId}/files/{fileId}` to download the archived document for audit or evidence purposes.

### Can I limit what my agent is allowed to do with the Candis API?

Yes. Because you run Jentic One yourself, your own rules decide which Candis operations and credentials the agent may use. Since Candis puts the organization ID in the URL path (`/organizations/{organizationId}/...`), you can pin the agent to a single organization so it reads only that organization's exports and postings. You also pick the operations it may call, so master-data imports such as POST `/organizations/{organizationId}/imports/general-ledger-accounts`, contacts, or tax-codes stay off limits unless you add them.