Connect Holded
Create a Holded API token with the right permissions, connect it, and see which documents Gurusup reads, how changes arrive and how Gurusup paces its calls.
Admins only. Gurusup answers about your invoices, purchases, contacts and products, so you can ask "Which customers with overdue invoices did sales talk to this month?" and get Holded joined with your calls and deals. Gurusup only reads Holded: the one thing it creates there is its own webhook, so Holded can tell it when something changes.
At a glance
| Topic | Details |
|---|---|
| Who can connect | Admins |
| What you need | A Holded API token (starts with pat_) with the permissions below |
| What Gurusup reads | Sales and purchase documents, contacts, products and services |
| How changes arrive | Within minutes through a webhook, or every 6 hours for some types |
| Past content | Import history, from last week to last year |
| Knowledge access | Default access, Restricted or Private. See Who can read it. |
Before you start
- You are an admin in Gurusup.
- In Holded, you can create an API token under Settings > Developers > Credentials.
- Gurusup uses at most 40% of your monthly Holded API calls, so your other tools keep working. See How Gurusup paces its Holded API calls.
- Holded takes one connection per Gurusup organization.
The permissions the token needs
In Holded, choose By area when you create the token and set each permission below. Leave everything else on None.
| Area | Resources | Level |
|---|---|---|
| Sales | Invoices, Credit notes, Estimates, Proformas, Sales receipts, Receipt notes, Services | Read |
| Inventory | Products, Sales orders, Purchase orders, Waybills | Read |
| Accounting | Purchases, Purchase refunds | Read |
| Contacts | Contacts | Read |
| Developers | API usage | Read |
| Developers | Webhooks | Read and write |
- Document types are your choice. Leave one out and Gurusup does not read it. The token needs Read on at least one.
- Both Developers permissions are required. Webhooks lets Gurusup hear about changes, and API usage lets it pace itself. Give nothing else in Developers.
Connect Holded
Open the Holded connector
In the sidebar, open Sources, then Catalog, find Holded (use Search sources if you need to) and click Connect on its row. Its page opens. Next to Organization accounts, click Connect for the organization. The dialog Connect Holded for the organization opens.
Create the token in Holded
Under the fields, click Show steps, then Open Holded next to "Open Holded's API credentials". Holded's API credentials open. The steps suggest naming the token "Gurusup" so you recognise it later. Give it the permissions in the table above and copy it.
Paste the token
Paste it in API key (the hint reads "Starts with pat_"). Gurusup says "Checking this token’s permissions in Holded…" and marks each permission as granted or missing.
Check the result
With every required permission there, the form shows "This month in Holded: X of Y API calls used. Gurusup uses at most 40% of your monthly limit." If something is missing, Gurusup says what and Connect stays off. See If it does not work.
Choose who can read it (optional)
Under Who can read it, Access mode starts as Default access. Choose Restricted to limit Holded to the people you pick, for example your finance team.
Connect
Click Connect. A message says "Holded connected." The connection appears under Organization accounts as "Holded account" with a Connected badge.
Gurusup starts from the moment you connect. To bring in documents you already have, see Import past work.
What Gurusup reads
Gurusup makes one document per Holded record.
| Record | What Gurusup reads |
|---|---|
| Invoices, credit notes, estimates, proformas, sales receipts, receipt notes, sales orders, purchase orders, waybills, purchases and purchase refunds | Number, date, due date, contact, status, subtotal, tax, total, amount paid and pending, tags, description, notes, every line (name, units, price, discount, taxes and description), contact persons, custom fields, payments and comments |
| Contacts | Name, contact type, trade name, email, phone, mobile, website, tags, notes, contact persons and custom fields |
| Products and services | Name, SKU, code, price, whether it is active, description and notes |
What Gurusup does not read
- Document types the token has no Read permission on.
- Anything outside the record types above.
- Notes, custom fields, comments and individual payments on documents Gurusup reads in its own checks rather than through the webhook: past documents brought in with Import history, and types marked Every 6 hours.
How changes arrive
Each document type is read in one of two ways:
| Mark | What it means |
|---|---|
| Live | Holded tells Gurusup about every create, update and delete within minutes. |
| Every 6 hours | Another tool in your Holded already listens to this type's changes, and Holded allows one listener per change, so Gurusup checks it on a schedule. The row says "Another tool in your Holded already listens to its changes". |
Gurusup listens to these events in your Holded. If another tool needs one, disconnect Gurusup or write to us. The Holded page no longer lists the document types or these marks on screen.
Gurusup also checks on its own: recent documents every 6 hours, contacts, products and services every week, and older documents throughout the month. These checks bring in only what changed after you connected. The first full check of each record type only notes what exists, and from then on a record that differs from it counts as a change. A type Gurusup could not read before, for example after you reconnect with more permissions, starts the same way from that moment. Import history is how you bring in older records.
When a record is deleted in Holded, or a check no longer finds it, Gurusup withdraws it: what it learned only from that record leaves, and anything other sources also back stays.
How Gurusup paces its Holded API calls
Gurusup keeps to at most 40% of your monthly Holded API calls, and recent changes go before history imports.
Import past work
Open Import history
On Sources, open the Holded page. Under History, click Import history.
Pick how far back
Pick Last week, Last month, Last 3 months, Last 6 months or Last year. The dialog says "Import documents dated in this window, plus your contacts, products and services. Past documents come without notes, custom fields, comments or individual payments."
Check the estimate
Gurusup shows what the import would use out of what you have left this month, and how many API calls counting cost: "This count used N Holded API calls." Past 500 of a type, the count shows a +.
Import
Click Import. Gurusup says "Importing history. It keeps going in the background." What does not fit in your remaining usage waits until it renews.
A window you already imported shows "Already imported"; pick a longer one to go further back. If the import stops, the button reads Try again.
Who can read it
Holded is one source.
| Knowledge access | Who reads it in Brain |
|---|---|
| Default access | Everyone, according to what they are already allowed to see: admins every category, members and agent accounts the categories an admin granted them. |
| Restricted | Only the people you pick. Administrators are not included unless you pick them. |
| Private | Only you. Administrators are not included. |
Set it when you connect, under Who can read it, and it applies before Gurusup reads anything. To change it later, open the Holded page and change Access mode under Knowledge access; it saves as soon as you change it, and what Gurusup already learned keeps the access it had. See Restrict a source to specific people.
Check that it worked
- On Sources, a Holded row is there.
- Create or change an invoice in Holded.
- Open Ingest and pick the Holded source in the source filter. The invoice moves from Queued to Learning to Learned. A type marked Every 6 hours can take up to that long. See Follow ingestion.
Reconnect
To change the token, for example to add document types, click Reconnect on the account's row under Organization accounts, paste the new token and click Reconnect again. Gurusup updates its webhook in Holded to cover the new types.
If Holded stops accepting the token, the connection shows Needs reconnect. Click Reconnect on the account's row and paste a new token. Until you reconnect, Gurusup reads nothing new from Holded.
Disconnect
On Sources, open the Holded page. Under Danger zone, open the menu on Disconnect, choose Disconnect and confirm. Gurusup deletes its webhook in Holded and forgets the token, which stays in Holded until you delete it there; see Remove, disconnect and what stays.
If it does not work
When you click Connect, these messages come after "Could not connect Holded."
| Message | What to do |
|---|---|
| "Missing Developers → API usage and Developers → Webhooks. Update the token in Holded and paste it again." (it names only what is missing) | Add the permission to the token in Holded and paste it again. |
| "This token can’t read any document type. Give it Read on at least one, like Sales → Invoices." | Give the token Read on at least one document type. |
| "Holded didn't accept this API token. Create a new one in Holded and paste it here." | Create a new token and paste it. |
| "This token can't create webhooks in Holded. In the token's permissions, set Developers → Webhooks to Read and write." | Set Webhooks to Read and write in Holded. |
| "Holded's API allowance is currently unavailable. Gurusup will resume reading when the allowance renews." | Your Holded API calls for the month are used up. Gurusup carries on when Holded renews them. |
| "This Holded account is already connected. Open its connection to manage it." | Open the existing Holded connection on Sources. |
| "This Holded connection was removed. Add a new connection." | Connect Holded again from its page in Catalog. |
| "We couldn't read Holded because of a problem on our side. Your saved content is safe. Contact support for help." | Nothing was connected. Contact support. |
| "Holded needs a new API token. Reconnect Holded." (in Import history) | Reconnect with a new token, then import again. |
| "The import didn't finish. Try again, and contact support if it keeps failing." | Click Try again. If it keeps failing, contact support. |
| "Holded couldn't disconnect Gurusup yet. Your connection is unchanged. Contact support for help." | Holded could not remove the webhook. Contact support. |
| "Ingestion is paused for this organization. Ask your organization admin to resume ingestion before adding content." or "Demo Mode prevents changing external sources. Ask your organization admin to turn off Demo Mode to continue." | Connecting, reconnecting and changing what a source brings in are off. Disconnect still works while ingestion is paused, but not in Demo Mode. See Connectors overview. |
Nothing coming in and no message? See Connector troubleshooting.