An API Integration Brief Template for Non-Technical Business Owners

Explain the business change you need

A useful API integration brief explains the business process that needs to change, which systems are involved, what information should move between them and when. It also says what should happen when the process cannot complete as expected, and how you will judge whether the change has worked. Start with those needs rather than telling the supplier which technical method to use.

Describe the current task in plain language. Say who carries it out, what they do in each system, and where they have to re-enter information, wait for an update or check that two records match. Then state the improvement you want: for example, less manual handling, fewer delays or a clearer view of a process. Be specific about the task, not about a technical solution.

Give the supplier enough context to understand the workflow. Name the systems and the people or teams who use them. Explain what information needs to pass between systems, what event should prompt the transfer, and what the relevant person should see or do if information is missing, rejected or out of date. You do not need to know how the systems connect; identifying what you do not know is more useful than guessing.

Illustrative wording: “When a customer’s order status changes in our order system, the relevant status should be reflected in our customer-service system so staff can give a consistent update. If the status cannot be matched or transferred, the responsible team needs a way to identify and resolve it. We will assess the result by checking whether staff can find the current status without re-entering it.”

This describes the desired business change without prescribing how it is built. A supplier can use the brief to ask about the systems, workflow and exceptions, then assess possible approaches with you. Treat it as the start of a scoping conversation: record open questions instead of filling gaps with assumptions. Keep pricing and detailed implementation choices for the conversations where the supplier has enough information to assess them.

Copy and complete this integration brief

Copy this brief into a document and complete what you can in plain English. Mark anything you cannot confirm as “Unknown” or “To discuss” rather than guessing; the supplier can help identify what needs checking during scoping.

• Business problem and outcome
  • What happens today? Describe the task, delay, duplicated entry or gap between systems.
  • Who is affected, such as a member of staff, customer or supplier, and what do they need to do?
  • What would you like to change? Describe the better process in terms of the work people do and the information they need.
  • What should improve if the change works? Name an observable business outcome, such as staff no longer re-entering a particular update.

  Your notes: ______

• Current workflow
  • List the steps in order, from the event that starts the process to the point where the work is complete.
  • For each step, say who does it, which system or record they use, and what information they enter, check or pass on.
  • Where does work pause, get repeated or require someone to compare records manually?
  • What happens when a usual step cannot be completed?

  Your notes: ______

• Systems involved
  • For each system, give its product or system name, its purpose in this process, and the supplier’s name if known.
  • Who in your organisation can answer questions about how the system is used? Who can arrange access or speak to the supplier?
  • Who owns or administers the account? Note any access restrictions, account ownership issues or approval steps that may affect assessment.
  • Is relevant system documentation available, and where can it be found? If you do not know, say so.

  System one: ______
  Purpose: ______
  Supplier, if known: ______
  Internal contact: ______
  Access or documentation notes: ______

  Repeat for each other system: ______

• Information to exchange
  • Name the business information in familiar terms, such as an order status, customer detail or stock update. Avoid guessing technical field names.
  • Which system currently holds or provides that information? Which system needs to receive or use it?
  • If the two systems show different values, which record should staff treat as authoritative for this information? If the answer varies by situation, explain how.
  • Are there related details that must move with the update for staff to use it correctly?

  Information: ______
  Provided by: ______
  Needed by: ______
  Source of truth if records differ: ______

• Trigger and timing
  • What business event should start the exchange? For example, a member of staff marking an order ready.
  • When should the receiving system show the change: as it happens, in a batch, or within another agreed business timeframe?
  • Does a person need to review or approve the information before it is sent or acted on?

  Trigger: ______
  Expected timing: ______
  Approval or review needed: ______

• Volume and variation
  • Describe activity in ordinary terms: when is the process quiet or busy, and are there seasonal peaks?
  • What common variations affect the workflow, such as different order types or teams using different procedures?
  • If you can estimate volumes, note the basis and period. If not, write “Unknown” for the supplier to discuss.

  Expected activity and variations: ______

• Exceptions and recovery
  • What should happen if a matching record cannot be found, information is missing or invalid, or a duplicate is created?
  • How should staff know that a transfer has failed or needs attention? Who should review it, and what should they do next?
  • Could an update be corrected later? If so, explain which system or person makes the correction and what the other system should then show.
  • Are retries or manual recovery part of the desired process? Describe the business outcome, not how the supplier should implement it.

  Exceptions and expected handling: ______

• People and responsibilities
  • Who is the business decision-maker for the integration?
  • Who can explain each system and the current process, arrange access, and answer supplier questions?
  • Which staff should take part in testing realistic examples?
  • Who will own the process after launch, including reviewing exceptions and reporting problems?

  Names or roles and responsibilities: ______

• Acceptance criteria
  • Write checks that someone can observe in the business workflow. State what should happen, where it should appear and how staff will recognise the result.
  • Include a normal case and, where relevant, a case that needs review or cannot be completed automatically.
  • Keep the checks focused on the outcome. Leave code, architecture and the choice of connection method for the supplier to assess.

  We will consider the work ready for acceptance when: ______

• Open questions and constraints
  • List anything still unknown, relevant business rules, and existing procedures that must continue during or after the change.
  • Note any operational constraints, such as who may approve changes or when staff can take part in testing.
  • Record data-handling questions for the appropriate adviser, rather than assuming the supplier can decide your business responsibilities.
  • Ask the supplier to assess whether the systems have the capabilities needed. Do not assume a product supports a particular connection or feature.

  Questions and constraints to discuss: ______

See how the template works for an order-status update

Illustrative example. Assume a fictional small retailer uses one system to manage orders and a separate system to coordinate fulfilment. This is not a real business or a report of an achieved outcome; it shows how to describe the need without specifying how the systems should be connected.

Business problem: When an order changes status, staff currently check the order system and then enter the relevant update in the fulfilment system by hand. This takes repeated effort and creates a risk that the two systems show different information.

Desired outcome: Make the agreed order status available against the corresponding order in the fulfilment system, so staff do not have to re-enter that update manually.

Systems involved: The order system is where staff manage orders. The fulfilment system is where staff coordinate fulfilment. The supplier should confirm what each actual system can support before proposing an approach.

Information to exchange: The order reference and the agreed status. The business needs to agree which status values are relevant and what each one means to staff. Do not assume that similarly named statuses in the two systems mean the same thing.

Trigger and timing: The assumed business rule is that a change to an order status should prompt an update. The precise timing, and how the update would be made, are for the supplier to assess and agree during scoping.

Exceptions and review: The brief should ask what happens if an order cannot be matched, a status is missing, or an update fails. An appropriate person should be able to identify and review unresolved cases, rather than having them disappear without notice. The business should say who is responsible for that review and what information they need to investigate.

Acceptance checks: Agree observable checks before work begins. For example, for an agreed order, the agreed status should appear against the corresponding order in the fulfilment system. A person responsible for review should also have a clear way to identify cases that need attention. These are proposed checks, not claims that an integration has been built or tested.

This example gives a supplier the business context, the information involved, the assumed trigger and the cases that need human attention. It does not assume that either system has a particular feature or that the connection is technically possible as described. The supplier must assess the actual systems and confirm what they can support before recommending a solution.

Gather what you can before sending the brief

You do not need to know how the connection will be built before speaking to a supplier. Gather the business information you can, mark gaps clearly and identify who can help resolve them; do not fill gaps by guessing or delay the conversation while looking for technical answers.

• Trace the work as staff do it now. Write down who starts the process, what they do in each system, what information they copy or check, and how they know the task is complete. Ask colleagues who handle unusual cases to check the steps too. A process that seems simple in the routine case may involve extra checks when information is missing or an order needs attention.
• List the systems and relevant contacts. Record the names of the products involved, the supplier for each, and the business contact who can answer questions about your account or current setup. Add any process notes, user guides or other system documentation already available. Do not assume a product name tells you what it can connect to or what access is available.
• Name the people who need to be involved. Identify who understands the business rules, who can approve a change to the process, and who can arrange access or take part in testing. These may be different people. For example, the person who handles daily exceptions may explain what should happen, while a manager approves the new workflow.
• Flag information that may be personal. Note whether the information exchanged could identify a person, such as a customer or member of staff. You do not need to decide what rules apply in the brief. Record the question and ask the appropriate adviser in your business to help assess data handling before the work proceeds.
• Describe scale and timing as best you can. Say whether work happens occasionally, throughout the day or in batches, and whether staff need updates promptly or can review them later. If you do not have exact volumes or timings, write that they are unknown and name the colleague, system contact or record that may help confirm them.
• Make constraints visible. Note any steps that must remain manual, cases that staff must review before information is acted on, or points where a person needs to make a decision. Include what staff currently do if a system is unavailable or the information does not match, if you know. These details help avoid designing a process that removes a check your business still needs.
• Keep technical questions open. Do not try to write an API specification, select an architecture or infer system capabilities from a product name. Put uncertain technical details in a list of questions for the supplier to assess. Your job is to explain the workflow and the outcome the business needs; the supplier can investigate the systems and propose how to achieve it.

Before sending the brief, check that the people responsible for the process recognise the description and that unknowns are labelled rather than presented as facts. A clear account of what happens today, what must change and who can answer follow-up questions is a useful starting point for scoping.

Use the brief to guide the scoping conversation

Use the completed brief to check that you and the supplier agree on the business need before discussing how to connect the systems. The supplier can then assess what is technically possible, identify unanswered questions and explain the options without you having to specify the design.

• Confirm the outcome and current workflow. Ask the supplier to describe, in their own words, what should change for the people doing the work. Check that they understand where information is entered now, who handles it next and where duplication, delay or errors occur. Correct any misunderstanding before moving on; a different view of the workflow can lead to a different solution.
• Check what needs assessing in each system. Discuss what information is available about the systems, such as supplier documentation, relevant functions and any access arrangements. Ask what the supplier needs to investigate, who can provide access or answer questions, and whether there are known restrictions on changing or sharing information. Treat capabilities and constraints as things to verify, not assumptions. If a system owner or existing supplier must be involved, agree who will contact them.
• Work through exceptions as business decisions. For duplicate, missing or invalid information, agree what should happen in the real workflow. Should a person review it, should processing pause, or should the issue be corrected elsewhere? Decide who monitors unresolved cases, how they are notified and who is authorised to make a correction. Ask how a correction should be reflected in the other system, so staff do not have to guess which record is current.
• Agree responsibilities. Name the people who can make decisions about the process, arrange system access, explain existing procedures and test the result. Also agree who will handle questions during testing and who will own day-to-day oversight once the integration is in use. If another department or external system supplier is involved, establish how requests and decisions will be passed between them.
• Make acceptance checks observable. Turn each acceptance criterion into a scenario that business participants can follow: what event starts the workflow, what information should appear, where it should appear and what should happen if something is wrong. Use representative examples from the process, including an exception that matters to staff. Agree who will carry out each check, who can confirm the result is acceptable and how any issue will be recorded for follow-up.
• Ask the supplier to surface assumptions and options. Invite them to list what they have understood, what remains unknown and what they need to check before proposing an approach. Ask which decisions affect the scope or the way staff will work, and what alternatives are worth considering. Keep the brief focused on the outcome; do not feel obliged to choose a technical method before the systems have been assessed.
• Leave room for discovery. Some technical details may only become clear when the supplier reviews the systems and access available. Record those as open questions, agree who will help resolve them and ask how the findings will affect the proposed scope. When you are ready to discuss your integration with DevAgency, you can Request a project quote.