Treat an integration as an operating agreement between systems, not simply an API connection. Decide which workflow it supports, which system owns each record, what data is exchanged, who is allowed to act, how repeated or failed requests are handled, what evidence proves the connection works and who owns it after launch.
Put this guidance into practice
Explore our custom CRM and ERP development, software development, application launch, premium website development and business automation services. We scope the work around your existing tools, team and goals.
Start with the business event, not the connector
Describe the real event that should move between systems. For example: a qualified enquiry becomes an opportunity, an approved order reserves stock, a successful payment releases fulfilment, or a completed installation creates a service record. This gives the integration a clear purpose and a point where the business can verify the outcome.
Name the people affected before discussing endpoints. Who creates the information, who relies on it next, who can correct it and who must know when it does not arrive? A connection can be technically successful while the operational handover remains unclear.
GOV.UK guidance recommends treating APIs as services that meet user needs. For a commercial business, that means the integration should be judged by whether the intended workflow remains understandable and usable, including when a third-party service is unavailable.
- Business event that starts the exchange
- Required outcome in the receiving system
- People who create, review and correct the information
- Timing expectation: immediate, scheduled or manual
- Fallback when the automated route is unavailable
Choose one source of truth for every important field
List the records and fields that cross the boundary: customer identity, product code, price, tax, stock, order status, payment reference, owner, consent, timestamps and attachments. For each one, identify the authoritative system and whether the receiving system may change it or only display it.
Write the mapping in business language before translating it into an API schema. A status called ‘closed’ may mean a completed sale in one tool and an inactive account in another. Codes, units, currencies, time zones and optional values need the same care because apparently matching labels can carry different rules.
Decide how existing records are matched and what creates a new record. Email address alone may not be a stable customer key; a product name may not be a reliable inventory identifier. Use controlled identifiers where available and record the rule for merges, duplicates and corrections.
- Authoritative owner for each record and field
- Stable identifiers used for matching
- Field formats, units, currency and time-zone rules
- Treatment of missing, invalid and duplicate values
- Who can correct a mapping or master-data problem
Define access by action and data scope
An integration should receive only the access needed for its task. Separate read, create, update, approve, export and delete actions, and restrict them to the relevant records or fields. A connection that only checks payment status should not automatically gain permission to edit customer profiles.
OWASP highlights broken object-level and function-level authorisation among common API risks. Test permission at the requested object and action rather than assuming that possession of a token makes every request appropriate. Treat data returned by a third-party service as untrusted input and validate it before it changes a business record.
Use organisational service accounts, documented owners and a controlled route for rotating credentials. Keep secrets outside source code and screenshots. Record where access is granted, how it is monitored and what must be revoked when a supplier or employee leaves.
- Named service account and business owner
- Minimum actions and data fields required
- Object, role and tenant boundaries
- Credential storage, rotation and revocation route
- Audit evidence for sensitive changes
Design repeated requests and failures before launch
Networks time out and services retry. Decide whether the same request can safely arrive more than once. For orders, payments, stock movements and notifications, use a stable business reference or idempotency key so a retry does not create a duplicate action.
Classify failures by the next safe step. Some requests can be retried automatically after a short delay; some need corrected data; some must wait for a human approval; and some should stop immediately. Set a limit so a failed request does not loop indefinitely or hide in a queue without an owner.
GOV.UK warns that depending on a third-party API can tie your availability to that provider. Plan an alternative, delayed queue or clear user message where appropriate. A customer should not receive a false confirmation simply because the downstream system could not be reached.
- Duplicate-prevention rule for retried requests
- Retry limit and delay policy
- Queue or holding state for temporary failures
- Human correction and replay route
- Customer or staff message when the workflow is delayed
Test the whole workflow with realistic evidence
A successful API response is not proof that the business workflow is correct. Test from the original action through to the final record, notification and ownership state. Include realistic but fictional examples of the variations that matter: tax treatment, product types, partial payments, cancelled work, duplicate submissions and permission boundaries.
Use a controlled test environment where both systems behave closely enough to production for the result to be meaningful. Record the exact versions, configuration and sample identifiers used. Confirm that production credentials and real personal data are not copied into informal test files.
The Home Office engineering standard recommends an API specification, appropriate status codes, validation, integration testing, observability and versioning. The specific tools can vary, but acceptance evidence should show the request, the receiving outcome, any audit event and the recovery path for at least one failure.
- End-to-end happy path across both systems
- Important validation, permission and duplicate cases
- Failure, retry and manual-recovery demonstration
- Expected audit records and notifications
- Signed acceptance by the workflow owner
Make monitoring and change ownership explicit
Monitor the outcome the business cares about, not only server availability. Track failed or delayed exchanges, queue age, repeated requests, unexpected volume and records that do not reach a final state. Alerts need a recipient who can investigate and a short first-response guide.
Keep an inventory of active endpoints, versions, credentials, dependencies and owners. OWASP identifies improper inventory management as an API risk because old versions and forgotten debug endpoints can remain exposed. Decide how a provider change, field change or version retirement will be tested and released without silently breaking the workflow.
Finish with an operating boundary: which team supports the connector, which provider supports each platform, who communicates with users, what data can be replayed and when a manual process takes over. DigiStartup India plans integrations around these workflow and ownership decisions for custom CRM, ERP, portals, premium websites and business automation.
- Dashboard for outcomes, failures and queue age
- Alert recipient and first-response steps
- Endpoint, version, credential and dependency inventory
- Change notice and compatibility-testing process
- Support, escalation and manual-continuity owner
Further reading
Frequently asked questions
Do we need an API to integrate two systems?+
Not always. A supported API is often the most maintainable option, but a secure file exchange, webhook, managed connector or carefully controlled manual import may fit the timing and volume better. Choose the simplest supported method that preserves validation, ownership, security and recoverability.
Which system should be the source of truth?+
Choose the system closest to the business authority for that information. A CRM may own sales ownership, an ERP may own invoiced prices and stock, and an identity system may own staff access. Document the owner field by field; do not assume one platform owns everything.
How should an integration handle duplicate requests?+
Use a stable business reference or idempotency key, store the outcome of accepted requests and make repeated delivery safe. The exact design depends on the workflow, but a retry should not create a second order, payment, stock movement or customer message.
What should be monitored after launch?+
Monitor failed and delayed exchanges, queue age, repeated requests, unexpected volume, authentication or permission failures and records that never reach the expected final state. Give every alert an owner and a documented recovery or escalation route.