What is API integration?
API integration uses an application's interface to exchange information or request an action from another application. A CRM might send account details to a support tool, or a reporting app might request a customer's permitted data. The API defines the available operations and the format of requests and responses.
IBM describes APIs as contracts that let software access data or functionality exposed by other software. An integration combines those contracts into a workflow. A connector or automation platform can perform some of the implementation, while your team still owns the meaning and consequences of the exchange.
This guide works through an original fictional CRM-to-support integration. A CRM named AccountBook owns company names and plans; a support app named HelpBench needs an up-to-date company record for each linked customer. The routes and payloads below are invented teaching examples, not endpoints for a real provider.
Define the business contract and source of truth
Write the event that should trigger work and the destination state you want. In this example, a company created or updated in AccountBook should eventually have a corresponding company in HelpBench. The support tool continues to own ticket status and agent notes.
Choose an immutable source identifier. The key crm:acct_041 identifies a company even if its name changes. A display name alone would merge unrelated companies that happen to share a name. In a multi-tenant product, include the authorized tenant boundary when looking up that key.
Record which system can change each field. A bidirectional sync needs explicit conflict rules. For this first workflow, HelpBench must not write its version of the plan back into AccountBook; doing so would create a loop and an unclear source of truth.
| Source field | Destination field | Rule |
|---|---|---|
| account_id | external_id | Prefix a stable CRM ID with crm: |
| company_name | name | Trim surrounding whitespace; reject an empty result |
| subscription_tier | plan | Map only supported values: starter, team, enterprise |
| record_version | source_version | Store an increasing source version for ordering |
| ticket notes | No mapping | Keep support notes in the support system |
Choose authentication and the smallest useful operation
Use the provider's documented server authentication method and request only the scopes required for this workflow. Store credentials in a server-side secret mechanism, keep them out of browser bundles, and define how expired or revoked access is handled. Connecting an account requires the customer's appropriate authorization.
The fictional destination supports an upsert at a stable resource path. An upsert creates a missing company or updates its mapped fields. Its contract says a lower source_version cannot overwrite a higher one. These are design choices for this example; a real provider may offer different methods and guarantees.
Inspect the response body and destination state, not just the HTTP status. A request can be accepted for asynchronous work before the state is fully applied. Write down whether success means queued, stored, or visible to the support agent.
PUT /v1/companies/crm-acct-041
Content-Type: application/json
Authorization: Bearer SERVER_SIDE_TOKEN_PLACEHOLDER
Request:
{
"external_id": "crm:acct_041",
"name": "North Studio",
"plan": "team",
"source_version": 7
}
Example response, after storage:
{
"id": "company_193",
"external_id": "crm:acct_041",
"source_version": 7,
"sync_status": "applied"
}
This is a fictional contract. Do not send it to a real service.Choose polling, webhooks, or a combination
Polling requests changes on a schedule. It can be a reasonable starting point when the provider supports a reliable update cursor and immediate synchronization is unnecessary. Define pagination, cursor storage, overlap handling, and the time at which a cursor can advance safely.
Webhooks notify your system when an event occurs. GitHub's documentation explains the event-driven model and how it differs from repeatedly checking an API. A receiving system still needs to authenticate the delivery, validate the event, and recover missed work.
A combination can use webhooks for timely updates and a reconciliation job to find gaps. The correct cadence depends on the business tolerance for stale data and the provider's documented limits. Our workflow automation guide helps decide which steps belong in the broader process.
| Approach | Useful when | Operational question |
|---|---|---|
| Polling | A modest delay is acceptable and changes can be listed reliably | Can the cursor resume after a partial failure? |
| Webhooks | Events should trigger work promptly | How are deliveries verified, deduplicated, and recovered? |
| Webhooks plus reconciliation | Timely updates and gap detection both matter | Which authoritative state resolves a disagreement? |
Make repetition and failure explicit
A connection can fail after the destination stores a request but before your worker sees the response. Retrying blindly can duplicate a creation or another side effect. Use the provider's idempotency behavior where available, or design an application-level operation ledger and lookup process appropriate to the action.
Stripe's idempotency documentation illustrates one provider's mechanism for retrying a request with a stable key. Its retention and response rules are specific to Stripe. Confirm the behavior of the actual endpoint you use rather than assuming that an Idempotency-Key header is universally supported.
For a validation failure, preserve a clear reason and correct the input before retrying. For expired authorization, route the account to reauthorization. For throttling and transient failures, use the provider's documented timing with bounded retries and a review path after exhaustion. Never retry an unknown side effect indefinitely.
Our background task guide explains the relationship between retries and idempotency. For billing-specific state changes, use the narrower Stripe subscription webhook guide.
Test the contract and maintain a recovery path
The downloadable contract defines seven synthetic cases: create a valid record, repeat the same version, apply a newer version, ignore an older version, reject an empty name, reject an unknown plan, and handle a temporary failure without marking the item complete. Each case has an expected destination state.
In a real sandbox, also test pagination, revoked access, removed source records, large values, Unicode names, and unexpected response fields. Confirm that one tenant cannot update another tenant's company. Keep the local mapping and source version durable before advancing a change cursor.
Log operation identifiers, status, timing, and safe error categories. Avoid storing full credentials or unnecessary customer payloads. Provide an operator with a way to inspect a failure, correct its cause, and replay only the intended operation. A successful first demo is the beginning of this operating process.
Download the integration contract
The original JSON contract includes field ownership, the invented upsert interface, seven expected cases, and operational questions to resolve with a real provider. The TXT checklist provides space for access scopes, cursor behavior, retries, monitoring, and recovery ownership. Neither file calls an external API. Sources checked October 27, 2026.