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

# API Reference

> Integration patterns, auth flow, and API implementation guidance for Sozo CRM.

## API Overview

Sozo CRM integrations are built around authenticated requests and role-safe access to sales, pipeline, and payout data.

<Tip>
  This page is intentionally implementation-focused for technical users integrating with Sozo CRM.
</Tip>

<CardGroup cols={2}>
  <Card title="Authentication" icon="shield-check">
    Every request is tied to an authenticated user context.
  </Card>

  <Card title="Role-Safe Access" icon="users">
    Permissions are enforced based on admin, manager, and rep roles.
  </Card>

  <Card title="Event-Driven Automations" icon="bolt">
    Trigger downstream actions from stage and deal lifecycle changes.
  </Card>

  <Card title="Reliable Payloads" icon="database">
    Use stable identifiers and avoid brittle name-based matching.
  </Card>
</CardGroup>

## Authentication pattern

Use a signed user token when calling protected endpoints.

```javascript theme={null}
import { getAuth } from 'firebase/auth';

const auth = getAuth();
const idToken = await auth.currentUser.getIdToken();

await fetch('/your-endpoint', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${idToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
});
```

### cURL example

```bash theme={null}
curl -X POST "https://your-api-endpoint" \
  -H "Authorization: Bearer <firebase-id-token>" \
  -H "Content-Type: application/json" \
  -d '{"dealId":"abc123","event":"stage_updated"}'
```

## Core data domains

<AccordionGroup>
  <Accordion title="Deals" icon="handshake">
    Pipeline lifecycle, customer records, and operational status for each opportunity.
  </Accordion>

  <Accordion title="Reps and Teams" icon="user">
    Identity, team mapping, role, and visibility scope for sales users.
  </Accordion>

  <Accordion title="Commissions" icon="dollar-sign">
    Split logic, payout state, and dispute-safe earnings records.
  </Accordion>

  <Accordion title="Notifications and Events" icon="bell">
    System events used for alerts, automation triggers, and manager oversight.
  </Accordion>
</AccordionGroup>

## Integration best practices

<AccordionGroup>
  <Accordion title="Use immutable identifiers" icon="hash">
    Store and pass record IDs rather than matching by names or free-form text.
  </Accordion>

  <Accordion title="Design for retries" icon="refresh-cw">
    Network calls and webhooks can repeat. Make create/update operations idempotent.
  </Accordion>

  <Accordion title="Validate at boundaries" icon="check-circle">
    Validate inbound payloads before write operations to prevent partial failures.
  </Accordion>

  <Accordion title="Batch where possible" icon="layers">
    Group related writes to keep state consistent and reduce edge-case drift.
  </Accordion>
</AccordionGroup>

## Typical error categories

<ResponseField name="permission-denied" type="error">
  The authenticated user does not have access for the requested action.
</ResponseField>

<ResponseField name="not-found" type="error">
  The record or collection path could not be resolved.
</ResponseField>

<ResponseField name="invalid-argument" type="error">
  A required field is missing or a payload type is incorrect.
</ResponseField>

<ResponseField name="deadline-exceeded" type="error">
  The operation timed out; retry with backoff and observability.
</ResponseField>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Set up production-ready workflows before connecting external systems.
  </Card>

  <Card title="Integrations" icon="plug" href="/integrations">
    Review integration patterns and rollout guidance.
  </Card>

  <Card title="Hosted MCP" icon="terminal" href="/mcp">
    Connect AI clients to your docs and implementation context.
  </Card>
</CardGroup>