Tools and security

API for beginners: what is it? and what to ask your software vendor

You do not need to write code to make a good decision about an API. You need to know what to ask before you buy a system, what a key is, where rate limits come from and what a webhook does. All of it below in plain language, with a table of questions for your vendor and what to do when there is no API at all.

8 minutes read

4 partswhat every request to an API is made of: the address, the method, headers carrying the key and optional data
100 to 150requests per 10 seconds HubSpot allows private apps, depending on the plan; every API has its own limit
6 questionsenough to ask a software vendor to know whether the system can be wired into the rest of your company
EUR 3,500 netone week of the process workshop, where we read your systems' documentation and write down what they actually expose

Short answer

What is an API, and why ask about it before you buy a system?

An API is how one program asks another for data or tells it to perform an operation, with nobody clicking through a screen. That is all. The rest is technical detail you do not need in order to make a buying decision.

For you it means one thing. A system with a working API can be connected to the rest of your company; a system without one stays an island that somebody retypes data out of by hand. That work does not disappear on its own. It grows with the number of customers and invoices.

Ask the vendor four things before you sign: whether the API is included in your pricing tier, where the public documentation lives, what the rate limits are, and whether the specific fields you care about can be read through it. Get the answers in writing.

What is an API, and what is one request made of?

The one-sentence definition: an API is a set of rules by which one program asks another for data or tells it to perform an operation, and gets an answer back in a format a machine can read. No magic and no waiter analogy.

The most common type is called a REST API. It runs over the same protocol as web pages and returns its answer as JSON, plain text that both a program and a person can read. Every request has the same four parts.

The address, or endpoint: the exact place you knock on, for example the contact list in a CRM
The method: GET reads data, POST creates a new record, PUT or PATCH updates an existing one, DELETE removes it
Headers: among them the key or token the system uses to recognise who is asking and what they are allowed to do
The body: when you create or update you attach the content of the record; on a plain read there is none

What does „we have an API” actually mean, and why is it the first question when you buy?

„We have an API” in a sales deck means only that the vendor built such an interface. It does not mean you have access to it on your plan, that it is documented, or that it covers the module you care about. Those are three separate things and you check them separately.

You can check it yourself in five minutes. Type the name of the system and the word „developers” or „API docs” into a search engine. Public documentation with a list of addresses and example requests is a good sign. If the only thing you find is a „contact sales” form, treat that as the answer.

Ask before you buy, not a year in. A year in you have data, history and a cost of leaving inside that system, so you negotiate from the position of someone who cannot walk away. How to compare tools on this specific point is in our guide on how to choose an automation platform.

Why do you treat an API key like a password, not like a setting?

An API key is a string that travels with the request and tells the system who is asking. Whoever holds the key is you, as far as the system is concerned, with your permissions. There is no second factor here, no code by text message, no „is this really you”.

So a key pasted into a spreadsheet, sent over Slack or saved in the description of a task is the same thing as an admin password left on a sticky note by the monitor. When personal data of your customers passes through that API, a leaked key is an incident under GDPR, not a fault in a tool.

A separate key for every integration, so one access can be revoked without switching off the rest
The narrowest permissions that still work: if an integration only reads invoices, do not give it write access
Keys in a password manager or in the platform's secret store, never in a spreadsheet and never in email
A written expiry date and a reminder 7 days ahead, because keys tend to expire over a weekend
A list of who has access and why; when someone leaves, keys go the same route as office cards

How many requests fit inside the limit, and what happens when you go over?

Every vendor caps the number of requests in a time window, so that one customer cannot take the system down for everybody else. HubSpot allows private apps 100 to 150 requests per 10 seconds depending on the plan, and states it in its developer documentation. Other vendors keep their own numbers in the same place.

Past the limit the API stops returning data and answers with a rejection instead, usually for a few minutes or an hour. A well-written integration expects that: it slows down, retries and comes back for the records it did not get. A badly written one drops that slice quietly, and the gap surfaces only when a report does not add up.

The limit is usually counted per account, so all your integrations share it at the same time
Run bulk operations in batches: one request per 100 records instead of 100 separate calls
The first pull of history is the heaviest, so it gets scheduled overnight and fetched page by page

How is a webhook different from polling every minute?

Polling means your automation asks the system every so often whether there is anything new. A webhook turns the direction around, because the system sends the notification itself the moment something happens. Instead of knocking on the door every minute, you leave your number and wait for the call.

The difference shows up in latency and in your request budget. Polling every 15 minutes means 15 minutes of delay in the worst case and several hundred empty requests a day. A webhook reacts in seconds and does not eat the limit, but it needs an address the vendor can send to, and a plan for the notification that never arrives.

Criterion	Polling every X minutes	Webhook
Reaction time	as long as the gap between checks, usually 5 to 60 minutes	seconds from the event
Request budget	requests go out even when nothing has changed	traffic only when something happened
What you need on your side	a key and a schedule	a public receiving address and signature verification
Failure on the other side	the next poll catches up on the backlog by itself	the notification can vanish, so you need a daily reconciliation
When we pick it	reports, overnight sync, systems with no webhooks	new order, new lead, payment status change

In practice you use both: a webhook to react to events, and a poll once a day to check that nothing was lost. You can set either up without writing code in Make, n8n or Zapier, by filling in a form with the address and the parameters.

What do you do when „we have an API” does not mean „you can read that field”?

An interface exposes only what the vendor decided to expose. Sometimes you see a contract number or a salesperson's note in the panel and the field simply is not in the API. Sometimes it is there but read-only, so writing back from the other side is out. That is a normal situation and you check it before the quote, not after it.

The order of checking is always the same, and it fits inside one working day.

Name the fields, not the system
Write down exactly what has to move: order number, VAT number, net amount, payment status, dispatch date. „Integration with the ERP” is not a requirement, it is the name of a folder.
Find those fields in the documentation
Open the API documentation and check that each one appears there and which direction it works in. Write down any field that is missing, together with the question you will send the vendor.
Ask about the fallback route
When a field is not in the API, ask about a batch export to a file, a read-only view on the database, or a webhook the vendor adds on their side. Usually one of those routes exists.
Settle the export as your floor
If no route exists, the floor is a scheduled export of all the data to CSV or XML that you do not have to ask anyone for. That is also your way out of the system when you change vendor.

What do you ask a software vendor before you buy?

Six questions that fit into one email to a salesperson. Ask for the answers in writing and attach them to the contract, because in a year nobody will remember what was said on a call. We ask the same six on the workshop, before anyone writes the first line of an integration.

An answer from the right-hand column does not rule the system out. It means the integration will cost more, and that you know it before you sign. What that kind of integration looks like when it is built from scratch is on our API integration page, and an example of a well-documented interface is on the HubSpot integration page.

Question for the vendor	An answer that is enough	An answer that means trouble
Is the API in my plan, and is there a surcharge?	yes, on this plan, with no surcharge	„from the higher tier”, or an add-on billed per request
Where is the documentation?	a public address, a list of endpoints, examples	„we send a PDF once the contract is signed”
What are the rate limits?	a number and a time window stated in the documentation	„there are no limits”, or „it depends on load”
Are there webhooks, and for which events?	a list of events and how the signature is verified	„you can always just poll every minute”
Is there a test environment?	a separate test account with its own key	„you test on production, just be careful”
How do I export all my data when I leave?	a full export to a file, on your own from the panel	„we run exports on request and they are chargeable”

Ask the last question even when the API looks perfect. It is the one item on this list whose answer you will otherwise learn at the worst possible moment.

Common mistakes

Six mistakes that cost the most on a first contact with an API

Buying a system without checking whether the API is in the plan you are buying
The interface exists, but it starts a tier higher or sits behind a paid add-on. You find out once the data is already inside and leaving costs money.
One API key used by every integration at once
Revoking access for one of them switches off the rest. And when the key leaks, nobody knows which route it took or what went through it.
A key kept in a spreadsheet, in email or in the body of a task
The key works like a password with full permissions. With customer personal data behind it, a leak is an incident under GDPR, not a fault in a tool.
An integration with no rate-limit handling and no error queue
After a rejection the missing records do not come back on their own. Nobody sees it until the day a report or an invoice does not add up.
A requirement written as „integration with the ERP”, with no fields named
The quote falls apart halfway through the build, when one field turns out not to be exposed. The deadline moves by weeks and there is nobody to blame.
No question about data export on the way out
When you change vendor it turns out that pulling your own data is a paid service that takes weeks. You negotiate from a very weak position.

Checklist

Checklist before you sign for a new system

If any line is a no, go back to the vendor with the question before you sign.

You know whether the API is in your pricing tier, and you have it in writing
You have the address of the public documentation and you have seen an example request in it
The fields that have to move between systems are written down by name, not as the name of a system
The rate limit is written down together with whether it counts per account, per user or per key
Every integration has its own key, the narrowest permissions and a written expiry date
Keys sit in a password manager or a secret store, not in a spreadsheet and not in a mailbox
You know how you will export all your data yourself when you change vendor
It is settled who gets the alert on the day the integration stops working

Sources

Let us check your systems

Before you buy a system, check whether it can be wired into the rest of your company

On a free consultation (30 minutes) it is enough to name the systems you already have and the ones you are considering. We will tell you whether they have an API, whether it sits in your plan, and whether the thing you care about can be read through it. The process workshop costs EUR 3,500 net per week and ends with a list of fields, limits and entry routes that your own developer can build against. Implementation is quoted after the workshop.

Book a free consultation

Frequently asked questions

What is an API in plain words?

It is how one program asks another for data or tells it to perform an operation, with nobody clicking through a screen. A request has four parts: the address, the method (read, create, update, delete), headers carrying the key, and optional data. The answer comes back in a format a program can read.

How do I know whether my system has an API?

Type the name of the system and the word „developers” or „API docs” into a search engine. Public documentation with a list of addresses and example requests means the interface exists and is described. Separately, check the price list for whether your plan includes access, because it is often a feature of a higher tier.

Is an API key the same thing as a password?

In practice yes, and a password with no second factor. Whoever holds the key is you as far as the system is concerned, with your permissions. That is why every integration gets its own key with the narrowest permissions, keys live in a password manager, and the expiry date is written down with a reminder 7 days ahead.

What happens when I go over the rate limit?

The API stops returning data and answers with a rejection, usually for a few minutes or an hour. A correctly written integration slows down, retries and comes back for the missing records. Without that handling, the data from the rejected window never arrives, and nobody notices until a report fails to reconcile.

What is a webhook, and when do you use it instead of polling?

A webhook is a notification the system sends by itself at the moment of an event, instead of waiting to be asked. You pick it where reaction time matters: a new order, a new lead, a payment status change. Polling stays for reports, for systems that have no webhooks, and as a once-a-day reconciliation.

Can you use an API without a developer?

Yes, for simple scenarios Make, n8n or Zapier are enough: you fill in a form with the address, the method and the parameters instead of writing code. Before you build the automation, test the bare request in a free tool such as Postman. An integration with rate limits, pagination and an error queue is already work for someone experienced.

What do you do when a system has no API?

You check the fallback routes in this order: batch export to a file, import from a file, a read-only view on the database, a webhook added by the vendor. The floor worth holding on to is a scheduled export of all the data to CSV or XML. If even that is missing, price the manual retyping and put that number into the buying decision.

How much does an API integration cost?

The process workshop costs EUR 3,500 net per week and ends with a list of fields, limits and entry routes. Implementation is quoted after the workshop, because only then do you know how many systems are involved and whether they are documented. Automation platform licences and AI model usage, EUR 0.005 to 0.07 per query, you pay the providers directly.