The API said yes. Did the customer handoff work?

Picture a fictional service company. A customer requests an equipment visit on the website. The request appears in its customer system, and an integration reports success, but no technician sees it on the dispatch board. One system called the request 'urgent' because the customer wanted a prompt reply; another interpreted 'urgent' as an after-hours emergency. The connection moved data. It did not deliver a usable job to the person who could act.

HTTP defines a 200 response as success for the request that received it. That is useful technical evidence, but it does not, by itself, prove a later system assigned work, a person responded, or a customer received what was promised. Treat the API response as the start of an end-to-end acceptance check, not its finish line. [1]

Write the customer outcome before the interface spec

Choose one real journey, then write what a successful handoff should leave behind. For the fictional visit request, an example is: 'A valid request appears once in the dispatch workspace with the correct service, source request ID, named owner and next action; an invalid request appears in a staffed exception queue; no customer message is sent without the agreed permission.' Your team should set its own response window based on actual capacity. Do not let the API's response time stand in for that window.

Give the business owner, operations owner and technical owner a chance to agree on that sheet. A developer can confirm a field transferred; the operations owner can say whether it is the field that makes the work actionable. The acceptance sheet is a shared decision record, not a promise that software alone can resolve every ambiguous request.

Define field meaning, authority and permission

A data contract needs more than column names. For each transferred field, specify its meaning, allowed values, whether it may be blank, its time zone or units, and which system may change it. Microsoft’s integration guidance explicitly calls out direction of data flow, access scope, schema, dates and nullability as design considerations. Use those questions even when both systems belong to the same company. [2]

• Distinguish a service address from a billing address. Neither should be copied into a field merely because it is named 'address.'
• Define 'booked,' 'requested' and 'assigned' as separate states. Record which system has authority to advance each state.
• Carry a stable source request ID into the destination and keep a mapping to its destination ID. Avoid using a customer's name or email as the duplicate key.
• Carry only the customer details and contact permissions needed for the agreed action. A service question does not automatically authorize promotional follow-up.

If a required field is missing or a value has no agreed meaning, hold the request for a named reviewer. Silently choosing a default can make the record look complete while sending the team to the wrong place. Preserve the original request and record the correction so a later replay is understandable.

Make a retry safe without repeating the work

A connector should expect uncertain outcomes. The sending system might time out after the destination saved a record, or a queue might deliver a message again. Cloudflare documents at-least-once delivery for its queue product and recommends stable IDs or idempotency keys for duplicate-sensitive work. Stripe documents one specific API's idempotency-key behavior for safe request retries. Those are examples of mechanisms, not a guarantee that every destination supports the same feature. [3][4]

Use one stable identifier for one intended business action, check the destination for that action after an ambiguous response, and make the destination reject or harmlessly absorb a replay. Do not generate a fresh business ID on every retry. Set a retry limit and route unresolved work to a visible owner. In a queue-based design, a dead-letter path can retain failures after the retry limit; Cloudflare's documentation also warns that, without a configured dead-letter queue, exhausted messages can be deleted. The exact mechanism depends on the systems you connect. [3][5]

Exercise: four transmissions, three customer requests

Use synthetic records in a test account with customer-facing sends disabled. Make three fictional requests: R-201 is complete, R-202 is complete, and R-203 is missing a required service address. Deliver R-202 twice to simulate a retry. There are now four transmissions for three intended requests. The expected initial result is two owned destination items, one visible exception for R-203 and one duplicate R-202 ignored. The counts reconcile: 2 + 1 + 1 = 4 transmissions. Nothing should disappear. No test message should reach a real customer; inspect would-send events to confirm each valid request prepares at most one confirmation and the invalid request prepares none.

After correcting R-203, the final state should be three destination items for three intended requests, zero unresolved exceptions and no duplicate customer action. If a test produces four destination items, the replay rule failed. If it produces only two without an open exception, the recovery path failed. Record both the technical result and the person who can resolve a mismatch.

Trace the journey and reconcile the counts

A shared request or trace identifier helps a team follow one action across services without searching by personal customer details. OpenTelemetry explains how trace context connects spans across process boundaries. A trace can explain where a request went; it still needs the business record and destination-state check to prove the operator received usable work. [6]

1. Before release, agree on the acceptance sheet, sample records, permission boundary, response window and named exception owner.
2. In a test account, run the valid, invalid, duplicate and destination-unavailable cases. Inspect destination records, alerts and the recovery queue; do not use real customer contacts to test sends.
3. After each test, reconcile intended source requests to owned destination records plus visible exceptions. Investigate every unexplained difference before enabling live traffic.
4. After a limited release, repeat the reconciliation with permitted production evidence. Review whether the real team can work the items, not just whether the connector returns success.

Bring the handoff to the design conversation

If your customer journey crosses a website, customer system and operating workspace, bring one troublesome handoff to Open Gate AI. We can map the records and owners, design a focused integration or custom application, and define acceptance around what the team needs to do next. Start with the acceptance sheet above: the source event, field meanings, destination action and failure owner. That gives us a better first conversation than a list of APIs to connect.