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:

   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)

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)

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:

{ "error": "Error description" }