API Overview
The Rally CRM REST API lets you programmatically manage contacts, companies, deals, activities, and more. Use it to build custom integrations, sync data with external systems, or automate your workflows.
Base URL
All API requests are made to your tenant-specific subdomain:
Replace your-tenant with your organization's subdomain.
Authentication
Rally supports two authentication methods. Use the one that fits your integration:
API Key (Recommended)
Best for server-to-server integrations, ETL pipelines, and third-party tools. Generate keys from Settings → API Keys.
JWT Bearer Token
Best for browser-based apps and user-context operations. Obtain a token via the login endpoint.
API Key Example
curl https://your-tenant.rallycrm.io/api/v1/contacts \
-H "X-Api-Key: rk_live_your_api_key_here" \
-H "Content-Type: application/json"Security Note
API keys carry full access to your tenant data. Never expose them in client-side code or public repositories. Rotate keys periodically and use the minimum required scope.
API Key Scopes
| Scope | Permissions |
|---|---|
read | View contacts, companies, deals, activities, pipelines |
write | All read permissions + create, update, delete records |
admin | All write permissions + manage API keys, webhooks, settings |
API Versioning
The API supports versioning through URL segments. The current version is v1. Unversioned paths are also supported for backward compatibility.
Rate Limiting
API requests are limited to 1,000 requests per minute per tenant. Rate limit information is included in every response via headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per window (e.g., 1000) |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
When you exceed the limit, the API returns 429 Too Many Requests. Back off and retry after the reset time.
Pagination
All list endpoints support offset-based pagination with two query parameters:
| Parameter | Default | Description |
|---|---|---|
limit | 100 | Maximum records to return (max 100) |
offset | 0 | Number of records to skip |
# Get the second page of 50 contacts
curl "https://your-tenant.rallycrm.io/api/v1/contacts?limit=50&offset=50" \
-H "X-Api-Key: rk_live_your_api_key_here"Field Filtering
Reduce payload size by requesting only the fields you need. Add a fields query parameter with a comma-separated list of property names:
# Only return id, email, and firstName
curl "https://your-tenant.rallycrm.io/api/v1/contacts?fields=id,email,firstName" \
-H "X-Api-Key: rk_live_your_api_key_here"Works on all GET endpoints — both list and single-record responses.
Incremental Sync
For ETL and integration workflows, use the updatedSince parameter on any list endpoint to fetch only records modified after a given timestamp:
# Get contacts updated since Jan 15, 2025
curl "https://your-tenant.rallycrm.io/api/v1/contacts?updatedSince=2025-01-15T00:00:00Z" \
-H "X-Api-Key: rk_live_your_api_key_here"For a complete change log including deletes, see the Sync & Changes API.
Error Handling
The API uses standard HTTP status codes. Error responses include a JSON body with details:
| Code | Meaning |
|---|---|
200 | Success |
201 | Created |
400 | Bad Request — invalid input or missing required fields |
401 | Unauthorized — missing or invalid API key / JWT |
403 | Forbidden — insufficient scope for this operation |
404 | Not Found — resource does not exist |
429 | Too Many Requests — rate limit exceeded |
500 | Internal Server Error — something went wrong on our end |