Holded
App · 25 actions
Manage contacts, contact groups and services, and read invoices, products, payments, ledger entries, taxes, projects, tasks and treasury accounts.
Actions
| Action | What it does |
|---|---|
| Create a contact | Create a contact. |
| Create a contact group | Create a contact group. |
| Create a service | Create a service. |
| Delete a contact | Delete a contact. |
| Delete a contact group | Delete a contact group. |
| Delete a service | Delete a service. |
| Get a contact by ID | Get a contact by ID. |
| Get a contact group | Get a contact group. |
| Get a product by ID | Get a product by ID. |
| Get a service | Get a service. |
| Get an invoice | Get an invoice. |
| List all products | List all products. |
| List all tasks | List all tasks. |
| List all taxes | List all taxes. |
| List contact groups | List contact groups. |
| List contacts | List contacts. |
| List invoices | List invoices. |
| List ledger entries | List ledger entries. |
| List payments | List payments. |
| List projects | List projects. |
| List services | List services. |
| List treasury accounts | List treasury accounts. |
| Update a contact | Update a contact. |
| Update a contact group | Update a contact group. |
| Update a service | Update a service. |
Create a contact
Create a contact.
Inputs
- Name
nametextRequired - Contact full name or company name
- Code
codetext - Tax identification number (NIF, CIF, etc.)
- VAT number
vat_numbertext - EU VAT number
- Trade name
trade_nametext - Commercial or trade name, if different from legal name
- Is person
is_persontrue/false - True if the contact is an individual, false if a company
- Email
emailtext - 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).
- Phone
phonetext - Landline phone number
- Mobile
mobiletext - Mobile phone number
- Website
websitetext - Website URL
- Type
typetext - Contact classificationOne of:
client,debtor,supplier,creditor,lead. - Client record
client_recordnumber - Number of the accounting account (chart of accounts) used when this contact acts as a client
- Supplier record
supplier_recordnumber - Number of the accounting account (chart of accounts) used when this contact acts as a supplier
- IBAN
ibantext - IBAN bank account number
- Swift
swifttext - SWIFT/BIC code of the bank
- Sepa ref
sepa_reftext - SEPA mandate reference for direct debit collections
- Sepa date
sepa_datedate - Date the SEPA direct debit mandate was signed
- Tax operation
tax_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 address
bill_addressobject - Billing address
- Tags
tagslist - Tags attached to the contact
- Custom fields
custom_fieldslist - User-defined custom fields
- Defaults
defaultsobject - 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
- Name
nametextRequired - Group name
- Description
descriptiontext - Group description
- Color
colortext - 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
- Name
nametextRequired - Service name
- Description
descriptiontext - Service description
- Price
pricenumber - Unit sale price
- Cost
costnumber - Unit cost price
- Tax
taxnumber - Tax percentage
- Taxes
taxeslist - List of tax identifiers to apply
- Tags
tagslist - List of tag names
- Sales channel ID
sales_channel_idtext - Sales channel identifier
- Code
codetext - Internal reference code
- Color
colortext - Display color
- Duration
durationnumber - 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
- ContactId
contactIdtextRequired - 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
- ContactGroupId
contactGroupIdtextRequired - 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
- ServiceId
serviceIdtextRequired - 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
- ContactId
contactIdtextRequired - 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
- ContactGroupId
contactGroupIdtextRequired - 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
- ProductId
productIdtextRequired - 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
- ServiceId
serviceIdtextRequired - 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
- InvoiceId
invoiceIdtextRequired - 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
- Name
nametext - Search products by name across your whole catalog. Optional.
- Cursor
cursortext - Opaque cursor for pagination
- Limit
limitnumber - 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
- Cursor
cursortext - Pagination cursor returned by the previous response. Omit to start from the first page.
- Limit
limitnumber - Maximum number of items to returnAt most 200.
- Status
statustext - `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
- Cursor
cursortext - Pagination cursor returned by the previous response. Omit to start from the first page.
- Limit
limitnumber - 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
- Phone
phonetext - Filter contacts by exact phone number match
- Mobile
mobiletext - Filter contacts by exact mobile number match
- Email
emailtext - Filter contacts by exact email address match
- Custom ID
custom_idtext - Filter contacts by your external reference identifier
- Code
codetext - Filter contacts by exact tax identification number (NIF/CIF)
- Cursor
cursortext - Opaque cursor for pagination. Use the value returned in the previous response to fetch the next page.
- Limit
limitnumber - 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
- Limit
limitnumber - Maximum number of invoices to return per page. Defaults to 50, maximum 200.At most 200.
- Cursor
cursortext - Pagination cursor returned by the previous response. Omit to start from the first page.
- Contact ID
contact_idtext - Filter invoices by contact identifier
- Status
statustext - 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 date
start_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 date
end_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 start
due_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 end
due_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.
- Sort
sorttext - Sort order for results. Prefix with - for descending.One of:
date,-date,dueDate,-dueDate,total,-total. - Approval status
approval_statustext - Filter by approval status. Use "draft" for unapproved invoices, "approved" for approved ones.One of:
draft,approved. - Accounting account num
accounting_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 date
start_datedateRequired - Filter entries from this date onward
- End date
end_datedateRequired - Filter entries up to this date
- Cursor
cursortext - Opaque cursor for pagination
- Limit
limitnumber - Maximum number of ledger entries to return per page. Defaults to 50, maximum 200.At most 200.
- Account
accountnumber - 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 date
start_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 date
end_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 ID
document_idtext - Filter payments linked to this document. Combine with document_type to match a specific document
- Document type
document_typetext - Filter payments by document type. Can be used alone, or combined with document_id to match a specific document
- Banking account ID
banking_account_idtext - Filter payments linked to this banking account
- Cursor
cursortext - Opaque cursor for pagination
- Limit
limitnumber - 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
- Cursor
cursortext - Pagination cursor returned by the previous response. Omit to start from the first page.
- Limit
limitnumber - Maximum number of items to returnAt most 200.
- Status
statustext - 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
- Limit
limitnumber - Maximum number of services to return per page. Defaults to 25, maximum 100.
- Cursor
cursortext - Pagination cursor returned by the previous response. Omit to start from the first page.
- Include archived
include_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
- Cursor
cursortext - Opaque cursor for pagination
- Limit
limitnumber - Maximum number of banking accounts to return per pageAt most 200.
- Type
typetext - 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. - Archived
archivedtrue/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
- ContactId
contactIdtextRequired - Contact ID (24-char hex ObjectId)
- Name
nametextRequired - Contact full name or company name
- Code
codetext - Tax identification number (NIF, CIF, etc.)
- VAT number
vat_numbertext - EU VAT number
- Trade name
trade_nametext - Commercial or trade name, if different from legal name
- Is person
is_persontrue/false - True if the contact is an individual, false if a company
- Email
emailtext - 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).
- Phone
phonetext - Landline phone number
- Mobile
mobiletext - Mobile phone number
- Website
websitetext - Website URL
- Type
typetext - Contact classificationOne of:
client,debtor,supplier,creditor,lead. - Client record
client_recordnumber - Number of the accounting account (chart of accounts) used when this contact acts as a client
- Supplier record
supplier_recordnumber - Number of the accounting account (chart of accounts) used when this contact acts as a supplier
- IBAN
ibantext - IBAN bank account number
- Swift
swifttext - SWIFT/BIC code of the bank
- Sepa ref
sepa_reftext - SEPA mandate reference for direct debit collections
- Sepa date
sepa_datedate - Date the SEPA direct debit mandate was signed
- Tax operation
tax_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 address
bill_addressobject - Billing address
- Tags
tagslist - Tags attached to the contact
- Contact persons
contact_personslist - Linked contact persons (by their contact ID)
- Custom fields
custom_fieldslist - User-defined custom fields
- Defaults
defaultsobject - 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
- ContactGroupId
contactGroupIdtextRequired - Contact Group ID (24-char hex ObjectId)
- Name
nametext - Group name
- Description
descriptiontext - Group description
- Color
colortext - 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
- ServiceId
serviceIdtextRequired - Service ID (24-char hex ObjectId)
- Name
nametext - Name
- Description
descriptiontext - Description
- Price
pricenumber - Price
- Cost
costnumber - Cost
- Tax
taxnumber - Tax
- Taxes
taxeslist - Array of tax keys to apply. Retrieve valid keys from GET /api/v2/taxes before setting this field.
- Tags
tagslist - Tags
- Sales channel ID
sales_channel_idtext - Sales channel id
- Code
codetext - Code
- Color
colortext - Color
- Duration
durationnumber - 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"
}