Adopt an External Integration

Change The System In Small Steps

Use this guide when a route, request, response, permission model, integration, or deployment behavior needs to be understood before people rely on it. In this guide, Adopt an External Integration narrows that work to adopter workflow for rolling out an external integration. Because this is a adoption page, read it as part of the Platform adoption learning path rather than as an isolated checklist.

An API is a contract between systems. Even technical changes can affect attendee records, dashboard behavior, notifications, payments, files, or staff tools. Read the page for the decision it helps a person make, then use the steps and checks as a steady path from context to action to proof.

What This Change Touches

This page is for adding or changing behavior. Use it to keep the requirement, service behavior, checks, adoption notes, and reviewer handoff connected. The intended readers are partner administrators, event leads, adoption leads, and integration owners. If the guide names a dashboard screen, service area, export, or record type, treat that name as a pointer to real operational responsibility.

• Primary surface or service: partners-api.
• Records or contracts involved: API service expectations, Auth state, and Platform records.
• Main care point: Watch for using a service route with the wrong actor, changing a response another app depends on, leaking a secret, or triggering the same side effect twice.
• Proof worth keeping: route inventory, method and path, auth model, request and response shape, platform owner confirmation, test result, consumer note, and deployment evidence.

Move From Requirement To Verified Change

1. Name the user need and owner: Begin by naming the Platform adoption situation, the owner, and the exact item involved in Adopt an External Integration.
2. Find the route, component, record, or integration that changes: Use partners-api to connect the words on the page to the screen, file, route, or service trail that people actually use.
3. Request the smallest coherent change: Keep API service expectations, Auth state, and Platform records in view so the work stays tied to the records or contracts it can affect.
4. Verify behavior, side effects, and documentation together: Before handing off, save proof such as route inventory, method and path, auth model, request and response shape, platform owner confirmation, test result, consumer note, and deployment evidence so an adoption lead and a non-specialist reviewer can understand what the route does and how it was verified.

The Change Is Ready When

You are ready to use the rest of this page when the purpose, owner, affected information, and proof are all clear enough for a second person to review.

1. Scope is named: The work is tied to the correct page, event, report, route, file, person, or record.
2. Impact is understood: The operator can explain the effect on callers, records, permissions, secrets, side effects, and downstream apps.
3. Proof is findable: The handoff points to evidence that an adoption lead and a non-specialist reviewer can understand what the route does and how it was verified.

End-to-end adoption runbook

1. Step 1 - Name the API workflow and owner: Identify the product area, organization owner, service path, and relying team before adopting a workflow or integration.
2. Step 2 - Read the contract in human terms: Check who can use it, what information is exchanged, what can fail, what records change, and what proof the adopting team must keep.
3. Step 3 - Prepare auth and input deliberately: Confirm the right role, account, partner, event, and approved data before depending on the workflow.
4. Step 4 - Use or request the route in the right environment: Use the approved dashboard, rego, LAN, or integration environment and keep credentials out of notes, screenshots, and exports.
5. Step 5 - Check returned data and real side effects: Confirm the visible result, affected records, external action, and review evidence in plain language.
6. Step 6 - Record tests, docs, and handoff notes: Record the owner, expected behavior, adoption evidence, and escalation path before relying on it in production.

Workflow

1. Step 1 - Confirm the external integration requirement: Write down caller, capability family, records touched, side effects, and consumer.
2. Step 2 - Pick the service owner: Reuse an existing service area only when ownership matches; otherwise add a focused module and mount it from src/index.ts.
3. Step 3 - Define auth first: Choose dashboard auth, rego auth, public validation, webhook secret, or internal test control before requesting implementation work.
4. Step 4 - Validate inputs: Document path, query, body, file, and header options before consumers call the route.
5. Step 5 - Confirm response and error shapes: Return stable JSON or documented binary/redirect behavior.
6. Step 6 - Test side effects: Verify database records and external systems in a safe environment.
7. Step 7 - Refresh the capability inventory: Ask the platform owner to refresh the capability inventory and update affected reference pages.
8. Step 8 - Add handoff notes: Mention compatibility, migration, deprecation, and monitoring expectations.

Verification checklist

1. Checkpoint 1 - Route appears in generated inventory: Method, path, internal trace, and line number are present.
2. Checkpoint 2 - Auth and role checks are proven: The route has explicit enforcement.
3. Checkpoint 3 - Consumer behavior is tested: Dashboard, rego, LAN, webhook, or integration caller works against the route.
4. Checkpoint 4 - Docs explain operation: An adopter can understand, test, and confirm the capability with a clear platform-owner escalation path.