Building an API integration: data, errors and ongoing management

An integration like this lets systems exchange data through an agreed interface. But two products having an API doesn't mean your whole process is taken care of. You still need to decide what gets sent, when it happens and how you'll know it worked.

Those are useful questions to ask before having an API integration built. They determine much of the development work and the ongoing management it will need. Not sure where to start? Read our guide to which business processes to automate first.

Describe the handover first

Start with one specific workflow. For example: a checked enquiry should create a contact and a task in the CRM. What data does that require? And at what point should it happen?

Write down what's outside that workflow, too. A change in the CRM may not need to go back to the form or website. A one-way transfer can be a very different project from two systems that need to keep updating each other.

Make the desired outcome something you can check. 'The systems are connected' tells you very little. 'An approved enquiry appears in the CRM with the right owner and no duplicate contact' gives you a much clearer starting point for building and testing.

Choose one source of truth for each piece of data

When the same information exists in several places, it needs to be clear where changes start. Suppose a customer's address is updated in one system while someone in another system is still working with the old address. Which version should the integration use?

Agree on this for each type of data. The CRM might be the source of truth for customer details, while another system manages order status. You don't need to use the same product as the main source for every type of information.

Check how fields match up as well. A full name in one text field is different from separate first-name and last-name fields. A required country code may be missing from the source. You need to agree on how to handle those differences before sending data automatically.

An existing integration may be enough

First check whether an integration already exists that supports the workflow you need. It might be available within the platform itself or through an additional tool. Look at the data, actions and exceptions you need, rather than just the two systems' names in an integration directory.

An existing solution might create new contacts but be unable to update custom fields. Or it might retrieve an order without being able to send its status back. Check this using a real situation from your process.

A custom integration becomes useful when the standard workflow doesn't fit. It lets you adapt the processing to the way you work. That also means agreeing on maintenance, because the systems on both sides can change.

What happens when a request fails?

The receiving system might be temporarily unavailable. A record might be rejected because a required field is missing. And sometimes no clear confirmation comes back, even though an action has been completed.

Simply sending it again could create a duplicate task or order. The integration therefore needs to recognise what has already been processed and which actions can safely be retried. Stripe describes idempotent requests as one way to do this: repeating a request without unintentionally performing the same action again. How you arrange this depends on the systems involved.

Make errors visible, too. A message in a technical log isn't much use if nobody looks at it. Agree on who gets notified, what information is needed to investigate the problem and how an employee can recover a transfer that has got stuck.

Agree on management before the integration goes live

The integration needs access to the systems. Decide who manages that access and how to avoid making everything depend on one employee's personal account. Grant only the access required for the agreed actions.

Consider changes as well. What happens when a field is renamed, a subscription changes or a vendor updates its API? Who assesses the impact and who makes the necessary fixes?

At handover, ask for an overview of the data flows, error handling and management responsibilities. That helps your team understand what happens without having to read the code.

Test more than the successful example

A good test shows that a normal enquiry arrives. A useful handover also shows how the integration handles an existing contact, missing data and a failed transfer.

Include those situations in the scope and check the outcome in both systems. That lets you see whether the integration supports your process as well as moving information.

Want to plan an integration with us? Start with the two systems and one recurring handover. From that workflow, we can investigate what already exists, where custom development is needed and who will manage the integration afterwards.