Holded

App · 25 actions

Manage contacts, contact groups and services, and read invoices, products, payments, ledger entries, taxes, projects, tasks and treasury accounts.

Actions

ActionWhat it does
Create a contactCreate a contact.
Create a contact groupCreate a contact group.
Create a serviceCreate a service.
Delete a contactDelete a contact.
Delete a contact groupDelete a contact group.
Delete a serviceDelete a service.
Get a contact by IDGet a contact by ID.
Get a contact groupGet a contact group.
Get a product by IDGet a product by ID.
Get a serviceGet a service.
Get an invoiceGet an invoice.
List all productsList all products.
List all tasksList all tasks.
List all taxesList all taxes.
List contact groupsList contact groups.
List contactsList contacts.
List invoicesList invoices.
List ledger entriesList ledger entries.
List paymentsList payments.
List projectsList projects.
List servicesList services.
List treasury accountsList treasury accounts.
Update a contactUpdate a contact.
Update a contact groupUpdate a contact group.
Update a serviceUpdate a service.

Create a contact

Create a contact.

Inputs

NamenametextRequired
Contact full name or company name
Codecodetext
Tax identification number (NIF, CIF, etc.)
VAT numbervat_numbertext
EU VAT number
Trade nametrade_nametext
Commercial or trade name, if different from legal name
Is personis_persontrue/false
True if the contact is an individual, false if a company
Emailemailtext
Email address. Several can be sent separated by commas or semicolons: the first is the primary, the rest are returned in `extra_emails`. Invalid ones are ignored (400 if none is valid).
Phonephonetext
Landline phone number
Mobilemobiletext
Mobile phone number
Websitewebsitetext
Website URL
Typetypetext
Contact classificationOne of: client, debtor, supplier, creditor, lead.
Client recordclient_recordnumber
Number of the accounting account (chart of accounts) used when this contact acts as a client
Supplier recordsupplier_recordnumber
Number of the accounting account (chart of accounts) used when this contact acts as a supplier
IBANibantext
IBAN bank account number
Swiftswifttext
SWIFT/BIC code of the bank
Sepa refsepa_reftext
SEPA mandate reference for direct debit collections
Sepa datesepa_datedate
Date the SEPA direct debit mandate was signed
Tax operationtax_operationtext
Fiscal operation type of the contact (e.g. general, intra, receq, exento). Must be one of the operations defined by the account tax scheme
Bill addressbill_addressobject
Billing address
Tagstagslist
Tags attached to the contact
Custom fieldscustom_fieldslist
User-defined custom fields
Defaultsdefaultsobject
Default settings applied to documents created for this contact

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": "example"
}

Create a contact group

Create a contact group.

Inputs

NamenametextRequired
Group name
Descriptiondescriptiontext
Group description
Colorcolortext
Group color (hex code)

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": "example"
}

Create a service

Create a service.

Inputs

NamenametextRequired
Service name
Descriptiondescriptiontext
Service description
Pricepricenumber
Unit sale price
Costcostnumber
Unit cost price
Taxtaxnumber
Tax percentage
Taxestaxeslist
List of tax identifiers to apply
Tagstagslist
List of tag names
Sales channel IDsales_channel_idtext
Sales channel identifier
Codecodetext
Internal reference code
Colorcolortext
Display color
Durationdurationnumber
Duration in minutes

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": "example"
}

Delete a contact

Delete a contact.

Inputs

ContactIdcontactIdtextRequired
Contact ID (24-char hex ObjectId)

Outputs

datanull
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": null,
  "has_more": false,
  "next_cursor": "example"
}

Delete a contact group

Delete a contact group.

Inputs

ContactGroupIdcontactGroupIdtextRequired
Contact Group ID (24-char hex ObjectId)

Outputs

datanull
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": null,
  "has_more": false,
  "next_cursor": "example"
}

Delete a service

Delete a service.

Inputs

ServiceIdserviceIdtextRequired
Service ID (24-char hex ObjectId)

Outputs

datanull
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": null,
  "has_more": false,
  "next_cursor": "example"
}

Get a contact by ID

Get a contact by ID.

Inputs

ContactIdcontactIdtextRequired
Contact ID (24-char hex ObjectId)

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "bill_address": null,
    "client_record": null,
    "code": null,
    "contact_persons": [],
    "created_at": null,
    "custom_fields": [],
    "custom_id": null,
    "defaults": null,
    "email": null,
    "extra_emails": [],
    "group_id": null,
    "iban": null,
    "id": "example",
    "is_person": false,
    "mobile": null,
    "name": "example",
    "notes": [],
    "phone": null,
    "rate": null,
    "sepa_date": null,
    "sepa_ref": null,
    "shipping_addresses": [],
    "social_networks": null,
    "supplier_record": null,
    "swift": null,
    "tags": [],
    "tax_operation": null,
    "trade_name": null,
    "type": "client",
    "updated_at": null,
    "vat_number": null,
    "website": null
  },
  "has_more": false,
  "next_cursor": "example"
}

Get a contact group

Get a contact group.

Inputs

ContactGroupIdcontactGroupIdtextRequired
Contact Group ID (24-char hex ObjectId)

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "color": "example",
    "description": "example",
    "id": "example",
    "name": "example"
  },
  "has_more": false,
  "next_cursor": "example"
}

Get a product by ID

Get a product by ID.

Inputs

ProductIdproductIdtextRequired
Product ID (24-char hex ObjectId)

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "archived": false,
    "attributes": [],
    "barcode": null,
    "category_id": null,
    "cost": null,
    "description": null,
    "exp_account_id": null,
    "factory_code": null,
    "for_purchase": false,
    "for_sale": false,
    "has_stock": false,
    "id": "example",
    "image": null,
    "in_pos": false,
    "kind": "simple",
    "min_stock": null,
    "min_stock_alarm": false,
    "name": "example",
    "pack_items": null,
    "price": null,
    "purchase_price": null,
    "purchase_taxes": [],
    "rates": [],
    "sales_channel_id": null,
    "sku": null,
    "stock": "example",
    "stocks": [],
    "supplier_id": null,
    "tags": [],
    "taxes": [],
    "total": null,
    "translations": [],
    "type_id": null,
    "variants": [],
    "warehouse_id": null,
    "weight": null
  },
  "has_more": false,
  "next_cursor": "example"
}

Get a service

Get a service.

Inputs

ServiceIdserviceIdtextRequired
Service ID (24-char hex ObjectId)

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "archived": false,
    "code": "example",
    "color": null,
    "cost": "example",
    "description": "example",
    "duration": null,
    "id": "example",
    "name": "example",
    "price": "example",
    "sales_channel_id": null,
    "tags": [],
    "taxes": []
  },
  "has_more": false,
  "next_cursor": "example"
}

Get an invoice

Get an invoice.

Inputs

InvoiceIdinvoiceIdtextRequired
Invoice ID (24-char hex ObjectId)

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "accounting_date": null,
    "approved_at": null,
    "body": null,
    "contact_id": null,
    "contact_name": null,
    "currency": "example",
    "currency_change": "example",
    "custom_fields": [],
    "date": null,
    "description": null,
    "discount": "example",
    "document_number": null,
    "draft": null,
    "due_date": null,
    "forecast_date": null,
    "from": null,
    "id": "example",
    "language": null,
    "lines": [],
    "multiple_due_dates": null,
    "notes": null,
    "payment_method_id": null,
    "payments_detail": [],
    "payments_pending": "example",
    "payments_refunds": "example",
    "payments_total": "example",
    "pipeline_id": null,
    "projects_summary": [],
    "shipping": null,
    "shipping_data": null,
    "status": "failed",
    "subtotal": "example",
    "tags": [],
    "tax": "example",
    "total": "example",
    "warehouse_id": null
  },
  "has_more": false,
  "next_cursor": "example"
}

List all products

List all products.

Inputs

Namenametext
Search products by name across your whole catalog. Optional.
Cursorcursortext
Opaque cursor for pagination
Limitlimitnumber
Number of products per page. Defaults to 50, maximum 200.At most 200.

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "cursor": null,
    "has_more": false,
    "items": []
  },
  "has_more": false,
  "next_cursor": "example"
}

List all tasks

List all tasks.

Inputs

Cursorcursortext
Pagination cursor returned by the previous response. Omit to start from the first page.
Limitlimitnumber
Maximum number of items to returnAt most 200.
Statusstatustext
`open`: tasks not in a done status and not archived. `done`: tasks in a done status, archived ones included. Omit to list every task, archived ones included.One of: open, done.

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "cursor": null,
    "has_more": false,
    "items": []
  },
  "has_more": false,
  "next_cursor": "example"
}

List all taxes

List all taxes.

Inputs

None.

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "items": []
  },
  "has_more": false,
  "next_cursor": "example"
}

List contact groups

List contact groups.

Inputs

Cursorcursortext
Pagination cursor returned by the previous response. Omit to start from the first page.
Limitlimitnumber
Maximum number of items to returnAt most 200.

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "cursor": null,
    "has_more": false,
    "items": []
  },
  "has_more": false,
  "next_cursor": "example"
}

List contacts

List contacts.

Inputs

Phonephonetext
Filter contacts by exact phone number match
Mobilemobiletext
Filter contacts by exact mobile number match
Emailemailtext
Filter contacts by exact email address match
Custom IDcustom_idtext
Filter contacts by your external reference identifier
Codecodetext
Filter contacts by exact tax identification number (NIF/CIF)
Cursorcursortext
Opaque cursor for pagination. Use the value returned in the previous response to fetch the next page.
Limitlimitnumber
Maximum number of contacts to return per page. Defaults to 25, maximum 100.At most 200.

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "cursor": null,
    "has_more": false,
    "items": []
  },
  "has_more": false,
  "next_cursor": "example"
}

List invoices

List invoices.

Inputs

Limitlimitnumber
Maximum number of invoices to return per page. Defaults to 50, maximum 200.At most 200.
Cursorcursortext
Pagination cursor returned by the previous response. Omit to start from the first page.
Contact IDcontact_idtext
Filter invoices by contact identifier
Statusstatustext
Filter invoices by payment status. "pending" matches invoices with no payment recorded and "partial" those collected in part; both still owe a balance. "outstanding" returns the two together, "overdue" narrows that set to a due date already past, and "completed" returns the settled ones.One of: pending, completed, partial, cancelled, failed, overdue, outstanding.
Start datestart_datedate and time
Filter invoices from this date. Accepts ISO 8601 datetime (e.g. 2026-01-01T00:00:00+00:00) or date only (e.g. 2026-01-01)
End dateend_datedate and time
Filter invoices up to this date. Accepts ISO 8601 datetime (e.g. 2026-12-31T23:59:59+00:00) or date only (e.g. 2026-12-31). A date without a time (YYYY-MM-DD) includes that whole day; a value with a time is applied exactly as sent.
Due date startdue_date_startdate and time
Filter invoices whose DUE date is on or after this date. Accepts ISO 8601 datetime or date only (e.g. 2026-01-01).
Due date enddue_date_enddate and time
Filter invoices whose DUE date is on or before this date. Accepts ISO 8601 datetime or date only (e.g. 2026-03-12). A date without a time (YYYY-MM-DD) includes that whole day; a value with a time is applied exactly as sent.
Sortsorttext
Sort order for results. Prefix with - for descending.One of: date, -date, dueDate, -dueDate, total, -total.
Approval statusapproval_statustext
Filter by approval status. Use "draft" for unapproved invoices, "approved" for approved ones.One of: draft, approved.
Accounting account numaccounting_account_numnumber
Filter invoices that have at least one line booked to this accounting account, identified by its numeric PGC code (e.g. 70000000 for "Ventas de mercaderias"). Only the numeric code is accepted; a non-numeric value returns 400. Returns 404 if no accounting account with that number exists in the tenant. When called through the AI assistant, an account name is resolved to its code automatically before the request reaches this endpoint.

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "cursor": null,
    "has_more": false,
    "items": []
  },
  "has_more": false,
  "next_cursor": "example"
}

List ledger entries

List ledger entries.

Inputs

Start datestart_datedateRequired
Filter entries from this date onward
End dateend_datedateRequired
Filter entries up to this date
Cursorcursortext
Opaque cursor for pagination
Limitlimitnumber
Maximum number of ledger entries to return per page. Defaults to 50, maximum 200.At most 200.
Accountaccountnumber
Filter entries by accounting account number (e.g. 70500001). Returns only entries posted to this exact account.

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "cursor": null,
    "has_more": false,
    "items": []
  },
  "has_more": false,
  "next_cursor": "example"
}

List payments

List payments.

Inputs

Start datestart_datedate and time
Filter payments from this date onward. Accepts ISO 8601 datetime (e.g. 2024-01-01T00:00:00+00:00) or date only (e.g. 2024-01-01)
End dateend_datedate and time
Filter payments up to this date. Accepts ISO 8601 datetime (e.g. 2024-12-31T23:59:59+00:00) or date only (e.g. 2024-12-31)
Document IDdocument_idtext
Filter payments linked to this document. Combine with document_type to match a specific document
Document typedocument_typetext
Filter payments by document type. Can be used alone, or combined with document_id to match a specific document
Banking account IDbanking_account_idtext
Filter payments linked to this banking account
Cursorcursortext
Opaque cursor for pagination
Limitlimitnumber
Maximum number of payments to return per pageAt most 200.

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "cursor": null,
    "has_more": false,
    "items": []
  },
  "has_more": false,
  "next_cursor": "example"
}

List projects

List projects.

Inputs

Cursorcursortext
Pagination cursor returned by the previous response. Omit to start from the first page.
Limitlimitnumber
Maximum number of items to returnAt most 200.
Statusstatustext
Filter projects by status. Use "active" or "in_progress" to retrieve only active/in-progress projects.One of: active, in_progress, completed, cancelled, waiting, budgeted.

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "cursor": null,
    "has_more": false,
    "items": []
  },
  "has_more": false,
  "next_cursor": "example"
}

List services

List services.

Inputs

Limitlimitnumber
Maximum number of services to return per page. Defaults to 25, maximum 100.
Cursorcursortext
Pagination cursor returned by the previous response. Omit to start from the first page.
Include archivedinclude_archivedtrue/false
Whether to include archived services in the results

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "cursor": null,
    "has_more": false,
    "items": []
  },
  "has_more": false,
  "next_cursor": "example"
}

List treasury accounts

List treasury accounts.

Inputs

Cursorcursortext
Opaque cursor for pagination
Limitlimitnumber
Maximum number of banking accounts to return per pageAt most 200.
Typetypetext
Filter banking accounts by account type. Allowed values: `bank` (bank account), `card` (credit or debit card), `gateway` (payment gateway such as Stripe or PayPal), `cash` (cash register / petty cash).One of: bank, card, gateway, cash.
Archivedarchivedtrue/false
Filter by archived state. `true` returns only archived accounts, `false` returns only active accounts. Omit to return both (default).

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "cursor": null,
    "has_more": false,
    "items": []
  },
  "has_more": false,
  "next_cursor": "example"
}

Update a contact

Update a contact.

Inputs

ContactIdcontactIdtextRequired
Contact ID (24-char hex ObjectId)
NamenametextRequired
Contact full name or company name
Codecodetext
Tax identification number (NIF, CIF, etc.)
VAT numbervat_numbertext
EU VAT number
Trade nametrade_nametext
Commercial or trade name, if different from legal name
Is personis_persontrue/false
True if the contact is an individual, false if a company
Emailemailtext
Email address. Several can be sent separated by commas or semicolons: the first is the primary, the rest are returned in `extra_emails`. Invalid ones are ignored (400 if none is valid).
Phonephonetext
Landline phone number
Mobilemobiletext
Mobile phone number
Websitewebsitetext
Website URL
Typetypetext
Contact classificationOne of: client, debtor, supplier, creditor, lead.
Client recordclient_recordnumber
Number of the accounting account (chart of accounts) used when this contact acts as a client
Supplier recordsupplier_recordnumber
Number of the accounting account (chart of accounts) used when this contact acts as a supplier
IBANibantext
IBAN bank account number
Swiftswifttext
SWIFT/BIC code of the bank
Sepa refsepa_reftext
SEPA mandate reference for direct debit collections
Sepa datesepa_datedate
Date the SEPA direct debit mandate was signed
Tax operationtax_operationtext
Fiscal operation type of the contact (e.g. general, intra, receq, exento). Must be one of the operations defined by the account tax scheme. On update, omitting it (or sending null) keeps the current value
Bill addressbill_addressobject
Billing address
Tagstagslist
Tags attached to the contact
Contact personscontact_personslist
Linked contact persons (by their contact ID)
Custom fieldscustom_fieldslist
User-defined custom fields
Defaultsdefaultsobject
Default settings applied to documents created for this contact

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "status": 0
  },
  "has_more": false,
  "next_cursor": "example"
}

Update a contact group

Update a contact group.

Inputs

ContactGroupIdcontactGroupIdtextRequired
Contact Group ID (24-char hex ObjectId)
Namenametext
Group name
Descriptiondescriptiontext
Group description
Colorcolortext
Group color (hex code)

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": "example"
}

Update a service

Update a service.

Inputs

ServiceIdserviceIdtextRequired
Service ID (24-char hex ObjectId)
Namenametext
Name
Descriptiondescriptiontext
Description
Pricepricenumber
Price
Costcostnumber
Cost
Taxtaxnumber
Tax
Taxestaxeslist
Array of tax keys to apply. Retrieve valid keys from GET /api/v2/taxes before setting this field.
Tagstagslist
Tags
Sales channel IDsales_channel_idtext
Sales channel id
Codecodetext
Code
Colorcolortext
Color
Durationdurationnumber
Duration

Outputs

dataobject
The response returned by the service.
has_moretrue/false
Whether another page is available.
next_cursortext
Continuation token for the next page.
Example output
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": "example"
}

On this page