How to Connect Business Apps With APIs
Picture a Tuesday afternoon. Your billing tool says a customer paid. Your CRM still says the deal is open. Someone on your team has already emailed the customer to ask about payment, and now you are both a little embarrassed. Nothing is broken in either tool. They simply do not talk to each other, and a person has been playing messenger between them.
An API, short for application programming interface, is the front desk each of those tools keeps open for other software. You send a request in a defined format, and you get an answer in a defined format. Connecting two business apps means writing a small, careful program that walks between two front desks, carries information across, and does not lose or duplicate anything on the way.
That last part is where most first attempts fail. Making a request work once is easy. Making it keep working through slow responses, expired credentials, partial pages of data and the same message arriving twice is the real job. This guide covers the pieces in the order you will meet them.
Start with the question before the code
Before you open any documentation, write one sentence that says which record moves, in which direction, and what should happen when it arrives. For example, "When an invoice is marked paid in the billing tool, update the matching deal in the CRM to Closed Won and stamp the payment date."
That sentence gives you four decisions you will need later.
- The trigger, meaning what event starts the movement.
- The key, meaning the value that identifies the same customer or invoice in both systems.
- The direction, meaning whether data flows one way or both.
- The failure plan, meaning who finds out when it does not work.
If you cannot answer the key question, stop. Two systems that cannot agree on which customer is which will produce duplicates no matter how good your code is. A shared customer number, an email address you trust, or a stored ID from the other system all work. A company name typed by hand does not.
Authentication is the first wall you hit
Every serious API wants to know who is calling. You will meet three common arrangements.
| Method | What it looks like | Good for | Watch out for |
|---|---|---|---|
| API key | A long secret string sent in a header | Simple server to server jobs | Keys often grant full access and rarely expire |
| OAuth 2.0 | A login and consent step that produces short-lived tokens | Acting on behalf of a user or company account | Tokens expire and must be refreshed |
| Signed requests | Each request carries a signature built from a shared secret | Payment and messaging platforms | Clock drift and exact formatting rules |
OAuth deserves a plain explanation because it confuses people. Instead of handing your password to another app, you approve a specific request for access. The provider gives the app an access token that lasts a short time, often under an hour, and a refresh token that can fetch a new access token. The approval is limited by scopes. A scope is a named permission such as "read contacts" or "create invoices". Ask only for the scopes you need. If your integration only reads, never request write access, because a leaked read-only token does far less damage.
Three habits will save you grief.
- Store secrets in an environment variable or a secrets manager, never in the code and never in a spreadsheet.
- Create a dedicated service account or integration user in each app, so the connection does not break when an employee leaves.
- Write down where every credential lives and when it expires. An expired token is the most common reason a working integration suddenly stops.
Reading data without missing any of it
Most list endpoints do not return everything at once. They return a page, perhaps 50 or 100 records, and tell you how to ask for the next page. There are two styles worth knowing.
Offset pagination says "give me records 100 to 199". It is easy to understand but it drifts. If a record is added or deleted while you are paging, you may skip one or see one twice.
Cursor pagination says "give me the page after this bookmark". The provider hands you an opaque token with each page, and you pass it back to continue. It is more reliable on data that changes while you read it, and it is the better choice when the provider offers it.
Here is the loop in plain pseudo-code.
set cursor to nothing
repeat
fetch a page of records using cursor
save each record, keyed by its ID
set cursor to the next-page token from the response
until the response has no next-page token
Two details matter. Save by ID so a repeated record replaces itself rather than creating a copy. And when you sync regularly, ask only for records changed since your last successful run, usually through an "updated since" filter. Pulling the entire customer list every five minutes is how small integrations hit rate limits and annoy the vendor.
Rate limits and the discipline of retrying
Providers limit how many requests you can send in a window of time. When you exceed the limit, you typically receive a response with status 429, often with a header that says how many seconds to wait. Other failures are temporary too. Status codes in the 500 range usually mean the provider had a hiccup. A timeout means you do not know whether the request worked.
The rule of thumb is simple. Retry on 429, on 500-range errors and on timeouts. Do not retry on 400-range errors such as 400, 401, 403 or 404, because repeating a bad request only repeats the failure. A 401 means your credentials need attention, so refresh the token once and try again, and if it still fails, raise an alert.
How you wait matters. Exponential backoff means each wait is longer than the last, for example 1 second, then 2, then 4, then 8. Add jitter, a small random amount, so that a hundred stalled jobs do not all wake at the same instant and hammer the provider together.
set attempt to 0
repeat
send the request
if it succeeded, stop
if the error is not retryable, record it and stop
add 1 to attempt
if attempt is above the maximum, send to the failure queue and stop
wait (2 to the power of attempt) seconds plus a random fraction
Cap the maximum at five or six attempts. A job that retries forever hides a real problem.
Idempotency, the idea that saves you from double charges
Here is the uncomfortable truth about retries. If a request times out, you do not know whether the provider processed it. If you retry a "create invoice" call and the first one had actually succeeded, you now have two invoices.
An idempotent operation is one that produces the same result whether you run it once or five times. Reading data is naturally idempotent. Creating data is not, unless you make it so.
You have three tools.
- An idempotency key. Many providers, especially payment platforms, let you send a unique key with a create request. If they see the same key twice, they return the original result instead of creating a second record. Generate the key from the business event, such as the order number plus the action, so a retry reuses it.
- Upsert logic. Look the record up by your matching key first. Update it if it exists, create it if it does not.
- A local ledger. Keep a small table of event IDs you have already handled and skip any you have seen.
Whenever a vendor offers idempotency keys, ask how long they remember a key. Some keep it for 24 hours, and a retry that arrives later would count as new.
Webhooks, and why polling is not always the answer
Polling means asking the other system "anything new?" on a schedule. A webhook reverses that. The provider sends an HTTP request to a web address you control the moment something happens. It is faster and far gentler on rate limits.
Webhooks come with their own obligations.
Verify the signature. Anyone who discovers your webhook address can send fake events. Reputable providers sign each message using a shared secret, and you recompute the signature and compare it before trusting the content. Reject anything that does not match. Also check the timestamp so an old captured message cannot be replayed.
Answer fast and work later. Return a success response within a few seconds, then put the event on a queue and process it separately. Providers treat slow responses as failures and resend.
Expect duplicates and disorder. Delivery is usually "at least once", so the same event can arrive twice, and two events can arrive out of order. Use the event ID for deduplication, and compare timestamps or version numbers before overwriting newer data with older data.
Keep a safety net. Webhooks can be dropped during outages. Run a low-frequency polling job, perhaps nightly, that compares recent records and repairs gaps. Webhooks for speed, polling for certainty.
A worked example with illustrative numbers
This is a hypothetical scenario, with made-up figures, to show how the pieces fit together.
A 10-person design studio wants paid invoices in its billing tool to update deals in its CRM. Assume the billing tool sends a webhook whenever an invoice is paid, and the CRM has a rate limit of 100 requests per minute.
- The webhook arrives. The handler verifies the signature, saves the event ID, and returns success in under a second.
- A worker takes the event off the queue. It checks the ledger. The event ID is new, so it continues.
- It looks up the deal using the invoice number stored in a CRM custom field. One match, so it will update rather than create.
- It sends the update. The CRM answers 429 with a wait of 12 seconds. The worker waits, adds a little jitter, and tries again. The second attempt succeeds.
- It marks the event handled in the ledger.
Suppose the studio pays 40 invoices on the first of the month and they all arrive within a minute. The queue absorbs the burst, and the worker processes at a pace under the CRM limit. Nothing is lost, and nothing is entered twice. That is the entire value of the design. The code itself is not exotic. The care around it is.
Monitoring, because silence is not success
An integration that fails quietly is worse than one that fails loudly. Decide in advance what you will watch.
- Counts. How many events came in, how many succeeded, how many failed, how many are waiting. A sudden drop to zero is as suspicious as a spike.
- Age of the oldest unprocessed item. If something has sat in the queue for an hour, someone should know.
- A failure queue, sometimes called a dead letter queue, holding events that exhausted their retries, along with the error. A human reviews it on a schedule.
- Credential expiry dates on a calendar.
- Reconciliation. Once a week, compare a count or a total across both systems. If the CRM shows 212 closed deals and billing shows 214 paid invoices, find the two that went missing.
Log enough to debug, which means event IDs, record IDs and error messages. Leave out personal details such as full names, email addresses and payment data. Logs travel to more places than databases do.
What breaks in real life
Experience says the same handful of things cause most of the pain.
- The provider changes a field or retires an old API version. Read the changelog, subscribe to deprecation notices, and pin the version you tested against when the API allows it.
- Someone renames a custom field or deletes a dropdown value in the source app, and your mapping silently stops matching.
- A token expires over a long weekend.
- Time zones. One system stores UTC and another stores local time, and records land on the wrong day. Store and compare in UTC and convert only for display.
- Rate limits that differ by plan, so the integration works in testing and stalls in production.
Questions to ask a vendor before you build
- Is there an API on my plan, or is it a paid add-on?
- What are the rate limits, and how are they reported?
- Do you support webhooks, and are they signed?
- Do create endpoints accept idempotency keys?
- How much notice do you give before retiring an API version?
- Is there a sandbox where I can test with fake data?
- Can I authenticate with a service account instead of a person's login?
What to do on Monday morning
- Pick one painful handoff and write the one-sentence description from the start of this guide.
- Confirm the matching key exists in both systems.
- Check the API documentation for authentication, rate limits and webhooks, and note anything that depends on your plan.
- Create a service account and a sandbox login.
- Build the smallest version that moves one record type in one direction, then run it against test data.
- Add the retry, ledger and alert behavior before you call it finished.
If you would rather talk it through with someone who has made these mistakes already, Ozcorp InfraOps builds and looks after connections like this for small teams, and InfraOps Base starts at $500 per month with vendor and license charges billed separately. Whether you work with us or not, I hope this saves you one bad Tuesday.
Discuss your infrastructure requirements
Review the current service offer or schedule a conversation about the scope you need.
Stay in touch
Follow Ozcorp
Leave your details for occasional notes about new articles and Ozcorp updates.