How to Integrate Holded API

Holded API Integration Uses API Key Authentication

Most modern accounting APIs use OAuth 2.0, which provides per-user authorization, token expiry, and revocation flows. The Holded API integration takes a simpler approach: a static API key that is generated in the Holded account settings and passed in the key header on every request.

GET https://api.holded.com/api/invoicing/v1/contacts
Headers:  
      key: your_api_key  
      Content-Type: application/json

For the integration, this is straightforward, but it creates some challenges:

• Each customer must generate an API key in their Holded account and provide it to your system — there is no OAuth flow that automates this
• There is no token expiry or automatic rotation, a compromised key requires manual replacement
• The API key provides full access to the account, there is no scope-based access control to limit what your Holded API integration can read or write
• Only account Owners or Administrators can generate API keys; users with custom roles cannot

Maesn's Unified Auth Abstracts Holded API Key Management: No Raw Key Handling Required

Maesn handles API key management for the Holded API integration as part of its unified authentication layer. Your customers connect their Holded account once through Maesn's onboarding flow — which guides them through key generation and securely stores it per tenant. You never handle raw API keys or build custom key collection UIs yourself.

The Holded API Integration Document Model - docType Controls What You Create or Retrieve

In most accounting APIs, invoices, credit notes, purchase orders, and sales receipts have separate endpoints. In the Holded API integration, all of these document types share a single endpoint, with the document type controlled by a docType path parameter:

GET  https://api.holded.com/api/invoicing/v1/documents/{docType}
POST https://api.holded.com/api/invoicing/v1/documents/{docType}

The valid docType values are:

Using the wrong docType when creating a document produces the wrong document type without an error.

Maesn Maps Document Types to Holded's docType Model - Correct Routing Without Configuration

Maesn's Holded API integration normalizes the document type model into its common data model. You work with unified document concepts - invoices, credit notes, purchases - and Maesn maps these to the correct docType for each operation. You never manage docType routing directly.

The Holded API Integration Is Split Across Five Separate Modules With Different Base Paths

The Holded API integration is not a single API, it is a collection of module-specific APIs, each with its own base path and its own set of endpoints:
‍

For a product that needs to sync financial data across invoicing and accounting, or integrate projects with invoicing, you must build and maintain requests across multiple module paths. There is no single root endpoint in the Holded API integration that gives you a unified view of all data. Each module also has its own endpoint structure and response format conventions.

Maesn Unifies All Holded API Modules Behind One Surface - No Module Path Management

All Holded API module paths are handled in the Maesn backend. Your integration makes standard calls to Maesn's unified endpoints — Maesn resolves the correct module and path for each operation automatically.

Spanish IVA in the Holded API Integration: Tax IDs Are Tenant-Configured and Must Be Resolved Before Every Write

Holded is built primarily for the Spanish market, where VAT is called IVA (Impuesto sobre el Valor Añadido). Spain operates a four-tier IVA system:
‍

In the Holded API integration, taxes are not passed as plain percentage values when creating documents. Instead, you reference a tax object ID — fetched via GET /api/invoicing/v1/taxes — that represents the configured tax in the tenant's account. Each tax object contains the rate, the tax name, and any additional configuration the company has set up.

This means: before creating any invoice or document with tax, your Holded API integration must first fetch the available taxes for that tenant and resolve the correct tax ID. The tax objects available differ per tenant — a company that only operates domestically may have different tax configurations than one that handles intra-EU or export transactions.

Additionally, the numSerieId — the numbering series identifier — must also be resolved per tenant before creating invoices. Spanish businesses typically have separate numbering series for different document types, and these are tenant-configured in Holded.

Maesn Resolves IVA Tax IDs and Numbering Series Per Tenant

Via Maesn, tax configurations and numbering series are mapped during onboarding and applied automatically in all subsequent Holded API operations. Your integration expresses tax intent once in Maesn's common data model — Maesn handles tenant-specific IVA resolution automatically.

The Holded API Integration Requires a Paid Plan and Administrator Access

This is a practical constraint that affects how you design your Holded API integration onboarding flow: the Holded API is not available on the free plan. Only customers on active paid Holded plans can generate API keys and connect to the API.

Additionally, within paid plans, only users with Owner or Administrator roles can generate or view API keys. Users with custom roles cannot access the API key management interface — even if they are on a paid plan.

For SaaS products onboarding Holded customers, this means your connection flow must account for these constraints. A customer on a free plan who attempts to connect will be unable to generate an API key. A customer on a paid plan with a custom role faces the same limitation.

Maesn Guides Your Customers Through Holded's Plan and Role Requirements - No Onboarding Surprises

Maesn's onboarding flow accounts for Holded's paid plan and admin role requirements, so your customers are guided correctly from the start of the Holded API integration setup.

Why Teams Use Maesn for Their Holded API Integration

Building a direct Holded API integration means managing per-tenant API keys, routing every document request through the correct docType, navigating five separate module paths, resolving tenant-specific IVA tax IDs and numbering series before every write operation, and handling plan and role constraints during onboarding — all before you ship your first feature.

Maesn abstracts this entire surface into a single unified API. You integrate once to Maesn and your product automatically works with Holded and every other accounting and ERP system in the Maesn portfolio, without system-specific branches in your code.

Check the Maesn documentation for Holded or talk to the Maesn team to get started.