Agicap Integration Investigation Summary

Date: 2026-02-22 Author: Max (with Claude Code) For: Co-founder review

TL;DR

Agicap has undocumented write API endpoints for invoices, POs, and credit notes. We confirmed them by creating a test account, authenticating via OAuth 2.0, and reverse-engineering the full DTO schema through validation errors. The API works, but needs a "connection" to be provisioned by Agicap before we can actually push data. Next step: contact Agicap to get a connection set up.

What We Investigated

Channel	Result
Agicap Public API	Write endpoints exist (undocumented). Confirmed via direct testing.
Celigo (iPaaS)	Native Agicap connector with confirmed Import (write) support. ~$6k/yr minimum.
Chift (unified API)	Dead end. Agicap is a customer of Chift, not a connector.
SFTP	Custom-quoted professional services engagement. No self-service. No documented formats.
Agicap UI	"Banks and Integrations" page only handles bank connections, not API integration sources.

What We Actually Tested (hands-on)

1. Created accounts

Agicap test account (entity ID: 211584)
Celigo free tier account with Agicap native connector
Generated OAuth 2.0 API credentials in Agicap

2. Authenticated successfully

POST https://api.agicap.com/public/auth/v1/token with client credentials
Scope: agicap:public-api, token lifetime: 3600s

3. Confirmed read endpoints work

Treasury Bank Journal: GET /public/treasury-bank-journal/v1/entities/211584/exports?size=5&after=2020-01-01T00:00:00Z → HTTP 200, {items:[], cursor:{...}}
Card Expenses Bank Journal endpoint also responds
List connections: GET /public/business-documents/v1/entities/211584/connections → HTTP 200, []

4. Discovered write endpoints exist (v1 + v2)

By sending intentionally incomplete requests, we got HTTP 400 validation errors that revealed:

5 writable document types:

POST .../connections/{connectionId}/supplier-invoices
POST .../connections/{connectionId}/client-invoices
POST .../connections/{connectionId}/purchase-orders
POST .../connections/{connectionId}/supplier-credit-notes
POST .../connections/{connectionId}/client-credit-notes

Both v1 and v2 of the API exist. URL pattern:

https://api.agicap.com/public/business-documents/{v1|v2}/entities/{entityId}/connections/{connectionId}/{resource}

5. Reverse-engineered the full V2 DTO schema

By sending wrong field types and checking for 400 vs 500 responses, we mapped which fields the backend actually parses:

Required fields (V2 supplier/client invoices):

Field	Type
`externalId`	string
`invoiceNumber`	string
`currency`	string
`amounts.totalAmount`	number
`amounts.taxesAmount`	number
`amounts.dueAmount`	number
`status`	enum: none, draft, due, paid, cancelled, deleted, paymentExecuted
`issueDate`	DateTimeOffset
`dueDate`	DateTimeOffset
`counterParty.id`	string

Optional fields (confirmed parsed by DTO):

Field	Type
`counterParty.name`	string
`paymentDate`	Nullable<DateTimeOffset>
`metadata`	IDictionary<string, string>

Variations by document type:

Purchase orders use purchaseOrderNumber instead of invoiceNumber
Credit notes use creditNoteNumber and don't require dueDate

Fields confirmed NOT on the DTO (silently ignored by .NET backend): description, costCenter (top-level), category, account, tags, lineItems, notes, paymentTerms, reference, supplier, contact, bankAccount, paymentMethod, and ~15 others tested

Valid statuses:

Supplier invoices: none, draft, due, paid, cancelled, deleted, paymentExecuted
Client invoices: none, draft, due, paid, cancelled, deleted

Example V2 request body:

[{
  "externalId": "orcha-001",
  "invoiceNumber": "INV-2024-001",
  "currency": "EUR",
  "amounts": {"totalAmount": 119.00, "taxesAmount": 19.00, "dueAmount": 119.00},
  "status": "draft",
  "issueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "counterParty": {"id": "supplier-001", "name": "Test Supplier GmbH"},
  "metadata": {"costCenter": "CC-001", "glAccount": "4200"}
}]

6. Confirmed what does NOT exist

All return 404: categories, cost-centers, accounts, contacts, suppliers, expected-transactions, payment-orders, settings, integrations, sources

7. Hit the blocker: connection provisioning

Entity 211584 has zero connections
POST /connections endpoint exists but returns HTTP 500 for every field combination
Agicap UI "Banks and Integrations" page only offers bank connections (PSD2, EBICS), not API integration sources
Celigo connector went "Online" but didn't auto-provision a connection
Could not send test data through Celigo (format issues with their mock data system)

The `metadata` Field (Cost Centers + GL Accounts)

Cost centers and GL accounts are not available as standalone endpoints (404). However, both v1 and v2 DTOs have a metadata field typed as IDictionary<string, string>. This is almost certainly how custom data like cost centers and GL accounts get attached to invoices.

We can't test which metadata keys Agicap recognizes until we have a live connection. This is a key question for Agicap.

Capability Matrix

Capability	Can we do it?	How?	Confidence
Write invoices (supplier/client)	YES	Business Documents API v2	95%+ (validated via API)
Write purchase orders	YES	Business Documents API v2	95%+ (validated via API)
Write credit notes (supplier/client)	YES	Business Documents API v2	95%+ (validated via API)
Push cost centers	Likely	Via `metadata` field on invoices	80% (field exists, keys untested)
Push GL accounts	Likely	Via `metadata` field on invoices	80% (field exists, keys untested)
Trigger approval workflows	NO	Not possible via any channel	95%+
Read bank journal entries	YES	Treasury Bank Journal API	Confirmed
Read transactions	YES	Treasury Bank Journal exports	Confirmed
Read card expenses	Likely	Card Expenses Bank Journal API	High

Architecture Options

Approach	Cost	Complexity	Best When
Direct Agicap API (recommended)	$0	Low	Agicap provisions a connection for us
Celigo middleware	~$6k/yr	Medium	If connection can only be created via Celigo
SFTP	Custom quote	High	If API approach fails entirely

Recommended: Direct API integration via Business Documents v2. Auth is standard OAuth 2.0, schema is straightforward, backend is .NET/C#. Build a native Clojure module following Orcha's DATEV/Maesn pattern.

Next Steps to Get Full Certainty

1. Contact Agicap (critical, unblocks everything)

Send them this:

We're building an integration from our invoice processing platform (Orcha) to Agicap via your Business Documents API v2. We've confirmed the write endpoints work and reverse-engineered the DTO schema.

We need:

A connection provisioned for entity 211584 (GET /connections currently returns [])

Full API documentation for Business Documents v2 write endpoints

What metadata keys are recognized for cost centers and GL accounts?

Is there a partner API program for direct integration?

Contact via: https://agicap.com/en/partners/become-partner/

2. Once connection exists, test these (we can do this ourselves)

POST a supplier invoice via v2 and verify it appears in Agicap UI
POST with metadata: {"costCenter": "CC-001"} and check if it's persisted
POST with metadata: {"glAccount": "4200"} and check if it's persisted
Test PUT (update) on an existing invoice
Test batch creation (multiple invoices in one array)
Test status transitions (draft → due → paid)
Verify counterParty creates/links a supplier in Agicap
Check if Treasury Bank Journal returns data for accounts with transactions

3. Ask Agicap about SFTP (if API doesn't cover everything)

What file formats are supported?
What fields can be imported via SFTP that can't be done via API?
What's the pricing for SFTP setup?

4. Rotate test credentials

The current API credentials (Client ID MWKY9K5mrD) were used during this exploration and should be rotated.

Key Links

Resource	URL
Developer Portal	https://api.agicap.com/
Business Documents Guide	https://api.agicap.com/guides/business_documents
Business Documents v2	https://api.agicap.com/api-details/business-documents-v2
Auth Guide	https://api.agicap.com/guides/authentication
Partner Program	https://agicap.com/en/partners/become-partner/
Celigo Agicap Connector	https://docs.celigo.com/hc/en-us/articles/30494709375515
Legacy API Docs	https://openapi.agicap.com/docs/index.html
Postman Collection	https://www.postman.com/agicap-data-int/workspace/agicap-public/

Dead Ends (don't revisit)

Chift: Agicap is a customer, not a connector. Can't bridge to them.
SFTP self-service: Doesn't exist. Custom-quoted per Agicap T&Cs.
Agicap UI for API connections: "Banks and Integrations" only handles bank/EBICS connections.
Public API docs for write endpoints: Don't exist. Developer portal is a JS SPA that can't be scraped.
Connection creation via API: POST /connections returns 500 for all payloads. Needs Agicap involvement.