At a glance
What you need to know.
A useful API integration moves a business task across a system boundary and makes the result traceable. Start with the record that must change, define what success means on both sides, and design how an operator recovers when one side is unavailable.
Describe one complete business handoff
Choose one transaction before drawing a network diagram: save an enquiry in a CRM, reserve stock for an order, or attach an approved invoice to an account. Identify the system that owns the authoritative record. Define the trigger, required fields, permitted destination changes and the person responsible for a failed handoff. An integration is incomplete if the request works but nobody can determine which system now owns the next action. Record what remains manual in the first release.
Write the contract before the connector
Document field meaning, required values, identifier format, time zones, error responses and data that must never cross the boundary. Distinguish missing values from empty values and a deletion from an update. OpenAPI provides a standard way to describe HTTP interfaces, but the description still needs to match the deployed service. Check the actual account plan, API version and test environment. A provider offering an API does not prove that your required object, field or operation is available.
Give the integration a narrow identity
Use an identity dedicated to the agreed integration and limit it to the records and operations required. Keep credentials on the server and record who rotates them. Evaluate permissions with the intended production role, rather than relying on an administrator credential during development. Validate incoming identifiers before accessing records, including ownership and organization boundaries. If a webhook is involved, follow the provider's documented verification procedure and establish a replay policy; a familiar sender name is not evidence of authenticity.
Make duplicate and partial completion explicit
A timeout can mean that the remote write failed or that it succeeded and its response was lost. Give each business operation a stable reference and agree how duplicates are recognized. Confirm the destination's idempotency scope and retention before retrying a create operation. For asynchronous delivery, keep durable pending work and distinguish received, processed and failed states. Where changes span two systems, define reconciliation or a compensating action. Do not assume a network call makes both databases commit together.
Verify the result in both systems
Test a valid transfer, repeated delivery, invalid mapping, missing permission, expired credential and a remote outage. Compare the source reference with the destination record, including fields that influence routing or money. Test out-of-order updates if the provider can deliver events that way. A successful response proves only the endpoint's documented acknowledgement, not every downstream consequence. Operators need enough context to locate the failed operation without exposing customer messages or credentials in shared logs.
Release one path and assign ongoing ownership
Start with a bounded flow and a reversible rollout. Decide whether old records will be backfilled, which direction wins a conflict and what happens during a schema change. Monitor pending age, rejection categories and reconciliation differences, rather than only counting requests. Maintain an operator procedure for retrying, correcting or closing failed work. Delivery cost depends on mapping, permissions, duplicate rules, provider constraints and maintenance. Adding a second destination often introduces a new business contract, not just another URL.
Before you start.
- Name the authoritative record and destination operation.
- Confirm the deployed API version and required account access.
- Agree field mappings, duplicate rules and credential ownership.
- Test lost responses, repeat delivery and unavailable dependencies.
- Prove destination state using a stable business reference.
- Assign failed-work review, reconciliation and change maintenance.
Common questions.
Should we use a native connector or write an integration?
Use a native connector when its supported objects, permissions and failure handling fit the workflow. Custom code becomes useful when the required mapping, authorization, deduplication or reconciliation cannot be expressed reliably. Verify the connector with the actual account and plan first.
Does a successful API response mean the workflow is complete?
Only if the endpoint contract promises that exact outcome and the stored result confirms it. Many APIs acknowledge receipt before processing. Track acceptance, durable processing and downstream completion separately when the workflow contains those stages.