Integrations & APIs
If a person moves information between two systems, an integration is probably missing.
Custom systems integration: we design integrations and APIs so that applications, platforms and services exchange data and actions automatically, without relying on copying, exporting, checking and re-entering information.
First we understand which information has to move, when, in which direction and what should happen when something does not fit. Then we design the right connection.
Many integrations already exist.A person is just doing them by hand.
Every time someone exports, copies, checks or retypes information between two tools, they are running an integration manually. It works until it stops working: the information exists twice, the states drift apart and someone has to decide which one is right.
- 01Open A
- 02Copy the fields
- 03Paste into B
Same customer, two states. Someone will have to notice.
Conceptual scenario · fictional data
What a person does today
Copying field by field
Every field copied by hand is a field that can arrive wrong, late or not at all. And nobody knows which ones were already copied.
- 01Information exists twice
- 02States drift apart
- 03A person reconciles them
Our job is to make that integration stop living in someone's head and hands.
This is how a piece of data travelswhen the integration exists.
A single fictional record travels the whole way between two systems. Every stop exists for a reason, and something different can go wrong at each one. Select a stage to see what happens.
CRM · customer record
Billing · account
Direction
Direction matters as much as the data.
Before writing a line of code you have to decide which way the information travels and what each system expects in return.
A → B
Information is born in A and reflected in B. B sends nothing back. The simplest form and, often, the right one.
Fits when one system clearly owns the data.
Mechanisms
Not everything connects the same way.
An API is the cleanest route, but not the only one, and not always available. The mechanism depends on what each system allows.
- APIThe system exposes functions to read, create and update. Allows complete, real-time integrations.
- WebhookThe system notifies when something happens. Avoids asking every minute whether there is news.
- File / importPeriodic exports and scheduled imports. Less immediate, but reliable when there is no API.
- DatabaseControlled reading or writing in the system's database. Only with control and guarantees.
- Scheduled syncA process checks for changes at intervals and propagates them. Simple to operate, with a known delay.
- Custom adapterWhen the system offers something unlike all of the above, we build the piece that translates between both.
The first step is to verify what each system exposes.Only then is it decided which integration can be built.
- Official APIAllows a complete integration: reads, writes and notifications.
- Partial accessWe integrate what the system allows and document what stays out.
- Import and exportSometimes the safest option, with a known rhythm.
- No accessThe system does not expose what is needed. We design the viable alternative; we do not promise the impossible.
An integration is not finishedwhen it works once.
The clean path is the easy part. What sets a production integration apart is what it does when the destination does not answer, the data does not fit or the same event arrives twice. Trigger a failure and watch what it decides.
Trigger a failure
- Receive
- Validate
- Translate
- Rules
- Deliver · breaks here
- Confirm
How it is handled
- 01Retry with increasing waits
- 02Log every attempt
- 03Queue if it persists
Retrying makes sense: the failure is transient and the operation can be repeated without double effects. If it persists, the data waits in a queue with its trace.
No strategy fits everything. Each failure has its answer, and deciding it is part of the design.
Before synchronising information,you have to decide who is in charge.
An integration must not create competing truths. For every piece of data, one system is the source and the others hold copies.
- Customer profile CRMSource of truth BillingCopy
- Payment state BillingSource of truth CRMCopy
- Availability CalendarSource of truth CRMCopy
Connecting data also meansknowing when two records are the same thing.
Customer 1827 in one system and contact a91f… in another are the same person. The integration stores that relationship and always uses it: that is how it updates instead of duplicating.
customer_id = 1827
contact_id = a91f…
External reference stored on both sides
- External identifiers: each system stores the other one's id.
- Stable references: records are linked by identifier, not by name or email.
- Explicit mapping: the relationship is created once and reused every time.
An API defines how other systemscan work with yours.
Sometimes the job is not to connect to an API but to build one: your system holds information and functions that others need to use. An API is the contract that says what can be done, by whom and with which guarantees.
An API also draws boundaries
- Who may connect
- Credentials per integrator, revocable without touching the others.
- What it may see
- Only the resources and fields its role needs.
- What it may change
- Bounded writes; everything else is read and left alone.
- How it authenticates
- API keys per environment, or signatures when a message has to be verifiable.
- What stays restricted
- Refunds, deletions, permission changes: separate operations with separate controls.
- GETreadWhat may another system know?
- POSTcreateWhat may it create?
- PATCHupdateWhat may it change?
- EVENTcustomer.updatedWhat is it told when something happens?
- Email with a valid, unique format
- Reference required
- States only change through allowed transitions
- One credential per integrator
- Read or write scope
- Sensitive operations restricted
FivoThis is how Fivo's API is built: keys per environment (live and test), webhooks signed with HMAC-SHA256 and a timestamp, and a log of every delivery.
It is not technical documentation. It is the decision of what each system may do with yours.
You do not need to replace everythingto get a better system.
The tools you already use usually work. What fails is the space between them. Instead of replacing them with a new platform, a thin layer is added that makes them behave like one system.
- Stays
- Every tool, with its team, its data and its habits.
- Is added
- A layer that listens, translates and delivers between them.
- Changes
- Nobody moves information by hand again.
When the integration needs a service of its own in the middle, we build it. The intent stays the same: make these systems work together.
- CRM
- ERP
- Web
- Payments
- Calendar
- Documents
Different systems.The same responsibility: data that arrives right.
Two real systems we built that live off their integrations. One moves payments and events; the other, operations and external platforms.
Trace A
A merchant creates a charge, a customer pays from another network and the merchant receives the signed result.
Fivo is a stablecoin payments infrastructure. Its value to the merchant is exactly an integration: an API to create charges and a webhook that tells it what happened.
- API keys per environment, stored hashed and shown only once
- A payment is never recorded twice: the transaction hash is unique
- A scanner checks the chain every few minutes and recovers payments even if the customer's browser closed
- MerchantCreates a checkout session from its serverPOST /checkout/sessions · X-API-Key · cs_live_…
- CustomerPays from the network where they hold fundsUSDC on 9 networks · EURC on 3
- CircleThe amount crosses networks and lands in the merchant's walletBridge Kit · CCTP v2 · no custody in between
- FivoVerifies the transaction on-chain before recording anythingcontract · sender · recipient · amount → completed
- WebhookSigned notification to the merchant's system, with retriespayment.completed · HMAC-SHA256 · 1 s / 5 s / 25 s
- MerchantIts system receives the event and its dashboard shows it in real timeX-Fivo-Signature verified · ack
Facts verified in each system's repositories. No invented performance figures.
What happens todaybetween the two systems?
Pick the situation closest to yours. It is not a closed diagnosis: it is the first thing we would look at.
Situation
States drift apart
Likely pattern
Define the source of truth, map the states and design the sync direction with conflict handling.
What we would inspect first
- 01Which system is in charge of each state
- 02Which transitions exist on each side
- 03What happens today when they do not match
We do not promise the solution before looking at the systems. The likely pattern is a starting point.
To get started,this is enough.
You do not need to bring API documentation. Tell us which tool you use, which one needs to receive the information and what you do by hand between them today.
- 01System Awhere the information is born
- 02System Bwhere it should end up
- 03What has to moverecords, states, documents
- 04Wheninstantly, hourly, every night
- 05Which system is rightwhen the two differ
- 06What happens todaywho does it by hand and how long it takes
Your systems
Tell us which tools have to talk to each other.
Tell us where the information is born, where it should end up and what a person does today to move it. We will review which access the systems offer and which kind of integration makes sense to build.