Define an API integration contract before either team starts building
Prepared with AI assistance by Alactic Editorial. Examples identified as hypothetical are illustrative, not customer results.
Send qualified enquiries to the CRM sounds complete until one team expects a contact update, another expects a sales opportunity, and a third assumes the customer receives a confirmation. Those are different operations, with different permissions and failure cases.
An integration contract settles the business boundary before estimates become commitments. It defines inputs, permitted changes, completion evidence and what happens when a request repeats or a response disappears. It is an operating agreement, not an endpoint specification.
The filled contract below is a fictional worked example. All names, identifiers and operating arrangements are hypothetical requirements, not Alactic customer results or existing product controls. Replace the decisions with yours, then secure agreement from the business owner and participating system owners.
1. Define one operation and its authority
Start with a trigger, an authorised action and an observable result:
Proposed operation: When an authorised reviewer submits a qualified enquiry, record it once in the designated CRM workspace, linked to an appropriate contact, and return the saved record references.
This does not authorise opportunity creation, salesperson assignment or customer messaging. Add those only through an explicit scope decision.
Identify who may submit, which source enquiries they may access and which destination workspace may receive them. Possessing a record identifier is not permission. OWASP recommends least privilege, deny-by-default decisions and authorisation checks for each requested object. These are design recommendations, not evidence about a particular product.
Verify required records, fields, permissions and integration access in the intended workspace and current plan. Alactic offers CRM and WhatsApp business communications products; ACID supports business-assistant workflows. Do not assume their capabilities are interchangeable, or that web capabilities are available in the Android app. This article defines operating requirements, not exact UI instructions.
2. Separate contract approval from operational acceptance
Use two approval gates. Otherwise, a demand to prove recovery before approving scope can sound like a demand to build the integration before anyone may start.
- Pre-build contract approval: Owners agree the operation, feasibility assumptions, unresolved blockers, evidence required and who will supply it. Confirm that the participating systems appear able to support the requirements; do not label untested behaviour as demonstrated.
- Post-build operational acceptance: Run the agreed checks in a suitable test setting. Accept the implementation for operation only when the required evidence is present and blockers are resolved.
If feasibility is uncertain, commission limited discovery before committing to implementation scope. For example, investigate whether a contact created during a lost-response event can be identified reliably. Record the finding and its limitations. Discovery is not completed integration acceptance.
A requirement may remain conditional during planning, but it must have an owner and a decision point. If safe recovery proves infeasible, revise the contract to an explicit manual-review boundary or stop that part of the scope. Do not silently replace a recovery requirement with blind retries.
3. Filled contract: ownership, inputs and exclusions
The following hypothetical artifact can be copied into a planning document. Sections that follow supply its repeat, matching and recovery rules.
- Operation: Submit qualified enquiry to Sales Workspace A.
- Business owner: Sales Operations Lead; approves qualification, matching and review decisions.
- Source owner: Enquiry Desk application team; owns source data and outcome display.
- Destination owner: CRM Administration Lead; verifies destination fields, permissions and inspection methods.
- Integration owner: Integration Operations Lead; owns reconciliation and unresolved-outcome escalation.
- Review location: Enquiry Transfer Review, a proposed access-controlled operations register, not an assumed product screen.
- Trigger: An authorised reviewer explicitly selects Submit to CRM. Qualification alone does not authorise execution.
- Submission identity: Destination workspace plus external enquiry reference.
- Example reference:
Sales Workspace A + ENQ-HYP-0142. - Required contact inputs:
Jordan Exampleandjordan@example.com. - Optional organisation:
Example Workshop; leave empty when unknown. - Required summary:
Requests a discussion about managing incoming service enquiries. - Qualification evidence: Reviewer
REVIEWER-HYP-A, qualification timestamp and confirmation of a relevant request with sufficient context for sales review. - Source reference: An enquiry reference that authorised staff can inspect.
For a new submission, the enquiry must be qualified, not withdrawn and not previously admitted under this identity. Check required values before submission and validate again at receipt. Missing required data causes rejection before destination changes.
Excluded: Opportunity or task creation, owner assignment, stage changes, contact merging, overwriting existing contact details, outbound communication, historical backfill and synchronisation of later edits. Withdrawal after submission does not delete destination records. Corrections require a separately approved workflow.
4. Freeze inputs and define every repeat outcome
Once a valid submission is admitted, preserve an immutable snapshot before destination writes. Recovery uses that snapshot, not whatever the source record says later.
- Check authority first. Verify access to the source enquiry, submission and destination. An unauthorised caller must not receive saved record details.
- Find the submission identity. If it exists, compare supplied business inputs against the snapshot using agreed normalisation rules.
- Reject changed inputs. Return Input conflict without replacement writes. Changing the email or summary under the same reference is not a correction mechanism.
- Handle unchanged repeats by state. Completed returns the saved result without writes. Pending confirmation or Partial completion enters the existing reconciliation process, not a new submission. Needs review stays blocked and returns its review status; repetition does not select a contact.
- Admit a new submission only when no identity exists. Apply current eligibility checks and establish its snapshot before destination work.
A completed repeat therefore does not fail merely because the source now says Submitted. Retrieving an authorised existing result is different from admitting a new operation.
Overlapping requests for the same identity must not independently create contacts or enquiries. The technical design must explain how it will meet that requirement, and implementation testing must demonstrate it.
5. Set matching, review and completion rules
For this hypothetical contract, match email after trimming surrounding spaces and lowercasing. This is a chosen business rule, not proof of a person's identity.
- No match: Create a contact from the snapshot, then create its linked enquiry.
- One match: Link the enquiry without changing existing contact details.
- Multiple matches: Set Needs review. Do not choose, merge or create a contact, and do not create the enquiry.
The Sales Operations Lead owns ambiguous-match resolution. A designated authorised reviewer may select one of the recorded candidate contacts or decide that no safe selection is available. Selecting a contact requires a decision record containing the submission identity, candidate references, chosen reference, reviewer identity, time and rationale.
The selection is a separate authorised decision, not an edit to the immutable inputs. Before resuming, verify the decision's authority and that the selected contact remains available in the intended workspace. Resume the original submission using its snapshot and recorded selection. If the choice is no longer valid, return to review rather than selecting a substitute.
If no safe selection is available, the submission stays blocked. Creating a different contact, merging candidates or changing the email requires a separately approved process outside this contract.
Completed means the contact, enquiry and link are confirmed, and the source has saved the workspace, external enquiry reference, contact reference and destination enquiry reference. An authorised inspector must find exactly one enquiry for that identity with the agreed values and link. The source displays Submitted, matching references and completion time. Queuing or contact creation alone is not completion.
6. Make uncertain writes an owned recovery process
A timeout does not establish that nothing was saved. Distinguish Rejected, Input conflict, Needs review, Pending confirmation and Partial completion. Pending confirmation means a write may have occurred; Partial completion means some work is confirmed but the operation is incomplete.
Integration Operations owns pending and partial entries. Each review entry records the identity, snapshot reference, known destination references, last confirmed step, uncertainty, assigned owner, next action and resolution evidence. Restrict access to authorised staff.
Agree recovery requirements for each write boundary:
- Contact confirmed, enquiry absent: Reuse that contact and perform only the missing authorised work.
- Enquiry response lost: Establish whether the enquiry exists using the agreed external reference and other evidence. Verify its values and link before returning its references.
- Contact-creation response lost: Establish whether this submission created a contact before permitting further destination writes. The enquiry reference alone cannot solve this if no enquiry exists, and a fresh email match alone does not establish which operation created a contact.
Before building, both system owners must agree a feasible way to determine the contact-creation outcome and associate any created contact with this submission. Keep the mechanism in the technical design; do not assume a particular endpoint or product feature exists.
If the systems cannot establish that outcome safely, retain an unresolved manual-review state. Do not automatically create another contact or enquiry. Manual recovery also requires recorded evidence and authorised action; a reviewer pressing Retry is not evidence that a write failed.
7. Worked example: the first response disappears
Hypothetical sequence: Jordan's submission passes validation and its snapshot is saved under Sales Workspace A + ENQ-HYP-0142. No contact matches. The destination creates CONTACT-HYP-081, but the contact-creation response disappears before an enquiry exists.
The source shows Pending confirmation. It does not claim Submitted or Nothing saved. An unchanged repeat finds the existing submission and starts reconciliation rather than fresh contact creation.
Using the previously agreed recovery method, authorised staff establish that this submission created CONTACT-HYP-081. They record the evidence. Recovery reuses that contact, creates linked enquiry CRM-ENQ-HYP-309, verifies the saved values and stores the result in the source.
The observable result is one contact created by this operation, one linked enquiry, consistent references and a resolved review entry. If the recovery method cannot establish the contact outcome, the correct result is an unresolved item with an owner and next action, not an automatic retry. If the submitted summary changes meanwhile, return Input conflict; the original snapshot remains the basis for recovery.
8. Test the contract before operational acceptance
After implementation, record the submission identity, inputs, responses, destination observations and reviewer decision for each check. A source success message alone is insufficient evidence.
- New and existing contacts: Confirm the correct link and one enquiry; existing contact details remain unchanged.
- Completed repeat: Return the saved references without new writes.
- Changed inputs: During recovery and after completion, require Input conflict, no replacement writes and an unchanged snapshot.
- Overlapping requests: Require one enquiry, no duplicate contact created by this operation and consistent final references.
- Ambiguous matching: Require Needs review with no destination writes. An unchanged repeat stays blocked. An authorised recorded selection resumes the original snapshot; no safe selection leaves it blocked.
- Lost contact-creation response: Interrupt after the contact is saved but before its response arrives. Require evidence-based identification and reuse, or unresolved manual review without further writes.
- Confirmed contact, missing enquiry: Recovery reuses the contact and creates only the missing work.
- Lost enquiry response: Reconcile to the existing enquiry without creating another, then resolve the source and review states.
- Invalid or unauthorised requests: Require understandable rejection without unintended writes or disclosure, including attempts to retrieve completed results.
The business owner, both system owners and integration owner approve the evidence before operational acceptance. Failed checks remain blockers or require an explicitly revised contract. Later requests become approved scope changes, not informal additions to a workflow whose recovery assumptions no longer hold.
Put the next conversation to work.
Explore Alactic Communications for WhatsApp conversations, campaigns and AI-assisted workflows. Choose the product and plan that fit your team.
Explore Communications