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:

https://your-tenant.rallycrm.io/api/v1

Replace your-tenant with your organization's subdomain.

Authentication

Rally supports two authentication methods. Use the one that fits your integration:

1

API Key (Recommended)

Best for server-to-server integrations, ETL pipelines, and third-party tools. Generate keys from Settings → API Keys.

X-Api-Key: rk_live_xxxxxxxxxxxxxxxx
2

JWT Bearer Token

Best for browser-based apps and user-context operations. Obtain a token via the login endpoint.

Authorization: Bearer eyJhbGci...

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

ScopePermissions
readView contacts, companies, deals, activities, pipelines
writeAll read permissions + create, update, delete records
adminAll 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.

/api/v1/contacts(versioned — recommended)
/api/contacts(unversioned — defaults to v1)

Rate Limiting

API requests are limited to 1,000 requests per minute per tenant. Rate limit information is included in every response via headers:

HeaderDescription
X-RateLimit-LimitMaximum requests per window (e.g., 1000)
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix 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:

ParameterDefaultDescription
limit100Maximum records to return (max 100)
offset0Number 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:

CodeMeaning
200Success
201Created
400Bad Request — invalid input or missing required fields
401Unauthorized — missing or invalid API key / JWT
403Forbidden — insufficient scope for this operation
404Not Found — resource does not exist
429Too Many Requests — rate limit exceeded
500Internal Server Error — something went wrong on our end

Next Steps

Rally Support

We typically reply in a few hours

Hi! 👋 How can we help you today?