> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revdesk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an integration

> Plan a reliable RevDesk integration around ownership, permissions, write-back, and recovery.

# Build an integration

Start with the operating contract, not the endpoint list. A reliable integration makes it clear which system owns each record, what RevDesk may change, and how both systems recover when a request fails.

## Integration checklist

1. **Name the workflow.** Define the trigger, audience, expected outcome, and human escalation path.
2. **Choose the system of record.** Decide which system owns the customer, opportunity, appointment, and consent state.
3. **Limit access.** Request only the organizations, locations, objects, fields, and actions the workflow needs.
4. **Define identity.** Choose the stable external identifiers used to match and deduplicate records.
5. **Write down write-back.** List every field RevDesk may create or update, including stage, owner, activity, appointment, and next step.
6. **Design retries.** Make repeated requests safe and keep enough context to reconcile a partial failure.
7. **Test the exception path.** Verify missing records, revoked access, invalid data, rate limits, timeouts, and duplicate events.
8. **Add operational visibility.** Record request identifiers, outcome, latency, and the person or workflow responsible for recovery.

## Recommended build path

<Steps>
  <Step title="Authenticate">
    Follow [Authentication](/api-reference/authentication) and keep credentials server-side.
  </Step>

  <Step title="Read the conventions">
    Review pagination, timestamps, identifiers, and request behavior in [API
    conventions](/api-reference/conventions).
  </Step>

  <Step title="Build the smallest complete flow">
    Prove one record can enter, receive work, produce an outcome, and update the expected destination.
  </Step>

  <Step title="Subscribe to the events you need">
    Use webhooks for relevant changes instead of repeatedly polling broad collections.
  </Step>

  <Step title="Test and observe">
    Exercise failure cases before expanding the audience or adding more locations.
  </Step>
</Steps>

## Data and identity contract

Write down the contract before sending production data:

* Which organization and, when applicable, location owns each record
* Which system owns customer, opportunity, appointment, consent, and communication state
* The stable identifiers used to match and deduplicate records
* Required, optional, immutable, and sensitive fields
* The direction of each supported write and how conflicts are resolved
* The event or reconciliation process that repairs missed updates

Use organization-scoped credentials and request only the scopes required by this contract. A successful API
request does not grant permission to copy unrelated fields into another system.

## Events and webhooks

Use webhooks when another system needs to react to RevDesk activity without polling. A consumer should accept
the event durably, process it idempotently, and preserve enough evidence to diagnose or replay a failure.

1. Verify the webhook signature before parsing or acting on the payload.
2. Persist the event identifier, organization, event type, received time, and processing state.
3. Return success only after the event is accepted for durable processing.
4. Treat duplicate and out-of-order delivery as normal.
5. Fetch current resource state when the latest state matters more than the event snapshot.
6. Retry transient failures with bounded backoff and route permanent failures to a visible review queue.

Do not place credentials, full payloads, or broad customer records in logs. Use request and event identifiers
to connect sanitized application logs to the affected record.

<CardGroup cols={2}>
  <Card title="Webhook reference" icon="webhook" href="/api-reference/webhooks">
    Verify requests and review supported events.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    Handle API failures consistently.
  </Card>
</CardGroup>

## Recovery and reconciliation

Retries cover temporary failures; reconciliation covers failures you did not observe. Keep a cursor or time
window that lets an operator compare the source and destination, identify missing or conflicting records, and
replay only the affected work. Reconciliation must use the same ownership and idempotency rules as the live
path.

Define who owns each recovery queue, how long failures may remain unresolved, and which corrections require a
person. Never make a broad overwrite the default response to a partial mismatch.

## Testing and production readiness

Test the business outcome across both systems, not only the successful HTTP response.

| Area           | Verify                                                                        |
| -------------- | ----------------------------------------------------------------------------- |
| Authentication | Valid, expired, revoked, and incorrectly scoped credentials                   |
| Identity       | New record, existing record, duplicate event, and missing external identifier |
| Data           | Required fields, invalid values, unexpected nulls, and timezone handling      |
| Write-back     | Allowed fields change and protected fields remain untouched                   |
| Reliability    | Timeout, rate limit, retry, replay, and partial downstream failure            |
| Tenancy        | Data never crosses organization or location boundaries                        |
| Workflow       | Stop, opt-out, approval, and human handoff behavior                           |
| Visibility     | Operators can find the request, event, outcome, and recovery owner            |

Before production:

1. Run the complete flow with test records.
2. Compare the final state in RevDesk and the connected system.
3. Confirm replaying a request or event does not duplicate work.
4. Verify revoked or insufficient credentials fail closed.
5. Exercise the reconciliation path.
6. Start with a controlled audience or one location and monitor the first production window.

<Card title="API quickstart" icon="bolt" href="/api-reference/quickstart">
  Authenticate and make the smallest complete request before adding the full workflow.
</Card>