What to agree before building an API integration.

Name the source of truth

Start with one record type, such as an enquiry. Write down which application owns each field and which applications only need a copy. If two systems can update a field, agree how a conflict will be resolved before implementing two-way synchronisation.

Define the event and the expected result

Describe the trigger in ordinary language: when a qualified enquiry is approved, create a task for the account team. List required fields, optional fields and the conditions that should stop processing. Include an example input and the expected destination record.

Plan for duplicate and failed events

A useful brief answers what happens if the same event arrives twice, an API is unavailable, or a record changes while processing is underway. Agree which failures can be retried and which need review. An operator should be able to understand what failed and what to do next.

Keep access proportional

Identify which records the integration must read or change. Arrange credentials through the organisation’s approved process and keep them out of example payloads, project briefs and logs. SSO/SAML, webhooks and export formats may also affect the solution.

Agree acceptance and ownership

Use representative test records, including missing fields and conflicting updates. Define what counts as a successful run, who receives failure notifications and who maintains the integration when either platform changes. Include field mappings and recovery instructions in the handover.

Bring this to discovery

Bring the names of the systems, a redacted example record, the desired trigger and outcome, known access restrictions and the person who owns the workflow. That is enough to start discussing a bounded first implementation.