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

# Making API Requests

This guide explains how to make API requests to the Rollout Universal CRM API. We'll cover authentication, request headers, and basic CRUD operations using the `/people` endpoint as an example.

To see all the other endpoints, navigate to the API Reference page

## Authentication

All API requests require two authentication components:

1. A Bearer token in the `Authorization` header. This is the `authToken` we previously generated in the “Getting your API Key” section of this guide.

2. A credential ID in the `x-rollout-credential-id` header, this is the Rollout generated credential ID for the user

## Where to get the credential ID

There are 2 ways to get the credential ID for your user:

1. Provide a callback function to the `onCredentialAdded` hook when rendering the Rollout Link authentication UI, in that callback function you can save the credential ID to your database and use it going forward.

2. Query the Rollout API to get a given users credential:

   ```javascript theme={null}
   const response = await fetch('https://universal.rollout.com/api/credentials', {
     headers: {
       'Authorization': `Bearer ${authToken}`,
     },
   });

   const credentials = await response.json();
   const credentialId = credentials[0]?.id; // Get the first credential 
   ```

For the above query, the user that you would be fetching credentials for is identified as the `sub` claim when you generate the `authToken`, for more info see the Getting your API Key page

## Making Requests

### Fetch People (GET)

```typescript theme={null}
const response = await fetch("https://crm.universal.rollout.com/api/people", {
  headers: {
    Authorization: `Bearer ${authToken}`,
    "x-rollout-credential-id": credentialId,
    "Content-Type": "application/json"
  }
});

const data = await response.json();
if (!response.ok) {
  throw new Error(data.error || 'Failed to fetch people');
}
```

### Create Person (POST)

```typescript theme={null}
const response = await fetch("https://crm.universal.rollout.com/api/people", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${authToken}`,
    "x-rollout-credential-id": credentialId,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(personData)
});

const data = await response.json();
if (!response.ok) {
  throw new Error(data.error || 'Failed to create person');
}
```

## Rate Limiting and Upstream Limits

* Rollout currently applies a **coarse tenant-level rate limit** (roughly `50 requests/second` per tenant; exact values may evolve).
* We do not currently enforce a per-credential limit.
* Most **read** traffic is served from Rollout's internal data view, which reduces direct pressure on upstream APIs.
* If an upstream system rate-limits requests, Rollout applies backoff/retry behavior where possible. If a request still cannot be completed in time, you may receive a transient error (for example `429`/`5xx`).

Recommended client behavior:

* Retry transient failures with exponential backoff + jitter.
* Make write operations idempotent when possible.

### Error Handling

The API uses standard HTTP status codes:

* 401: Unauthorized (invalid token)

* 403: Forbidden (invalid credentials)

* 404: Not found

* 409: Conflict — This is commonly returned when the data for a given CRM is not yet ready, please allow 30-60 seconds for the data sync to start once you have authenticated

* 500: Server error

Errors return JSON with an error message:

```javascript theme={null}
{ "error": "Error description" }
```