Making API Requests

​

Authentication

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

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
   

​

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.errorMessage || data.error || 'Failed to fetch people');
}

​

Read another data type

​

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.errorMessage || 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).

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

​

Error Handling

• 400: Bad request. For example, the requested entity is not enabled or the connector does not support the operation. Read errorMessage for the cause.
• 401: Unauthorized (invalid token)
• 403: Forbidden (invalid credentials)
• 404: Not found
• 409: Conflict. This can indicate that data is not ready yet. Allow the sync to progress and retry; timing varies by connector and data volume. Inspect the message for other conflict causes.
• 500: Server error

{ "errorMessage": "This credential is configured to not sync Notes." }