Help Docs Developer Resources Sending API Requests
Welcome to the RumbleUp API documentation!
The RumbleUp API allows developers to programmatically interact with our platform, enabling messaging workflows and account management through a set of structured JSON endpoints.
This documentation provides an overview of available functionality, integration guidelines, and example requests to help you get started quickly and build efficiently.
Base URL:
https://app.rumbleup.com/api
The RumbleUp API uses API keys to authenticate requests. You can view and manage your API keys in the Integrations -> API Keys.
An API key consists from 2 parts: key and secret separated by colon: KEY:SECRET
Your API keys inherit your admin privileges on creation, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value and the secret as a password.
If you need to authenticate via bearer auth (e.g., for a cross-origin request), in curl use -H “Authorization: Bearer KEY:SECRET”
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
When using Postman enter the KEY part in the Username field and the SECRET in the Password for Basic authorization. For Bearer type paste the whole KEY:SECRET pair in the Token field.
In the rest of the documentation examples may contain YOUR_ACCOUNT_CID referring to legacy keys, if using new keys just use the KEY part instead.
Example using curl:
curl -X POST https://app.rumbleup.com/api/account/get -u "<KEY>:<SECRET>"
curl -X POST https://app.rumbleup.com/api/account/get -H "Authorization: Bearer KEY:SECRET"
The legacy API keys only support Basic Authentication.
Use your RumbleUp Account ID as the username and legacy API key as the password. Find both in Integrations -> API Keys, legacy keys are marked explicitly.
Example using curl:
curl -X POST https://app.rumbleup.com/api/account/get -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'
All API calls return list of items only one page at a time. You can control the number of results per page and where each page starts using the following query or body parameters:
_count - a number of items per page, by default it is 32._start - a token returned by previous call in the next_token, see example.Example of paginated output:
curl https://app.rumbleup.com/api/contact/select -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'
{
"total": 100,
"count": 32,
"data": [ ... ],
"next_token": "XXX1"
}
curl https://app.rumbleup.com/api/contact/select?_start=XXX1 -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'
Error messages are returned as JSON in the following format:
{
"status": STATUS,
"message": "error message",
}
status - in most cases it is a HTTP status but sometimes it can be some other specific error code.message - detailed or more human readable explanationMany times but not always an additional property code might be provided, it is opaque and specific to the situation, in most cases it gives additional context why this error occurred, especially if the status is one of the generic HTTP codes like 400.
{
"status": "401",
"message": "Access denied",
"code": 99
}
401 Unauthorized
This error indicates invalid authentication. Validate your information in Integrations -> API Keys. The request can be retried.
404 Not found
This error indicates that a resource does not exist. This is not the case when searching results in empty result set.
441 Activity limit reached
This error indicates API endpoint limits, this is based on many factors but in most cases restricted by CID, i.e. it is account wide limit. The request can be retried.
429 Too Many Requests
This error occurs due to exceeding the request limit. The server allows new requests after a short period. This is usually IP based rate limiting. The request can be retried.
Common naming conventions and internal property names that are still used in the API:
cid refers to your account ID, accounts are used to be called campaignsrupid refers to contact unique ID, mostly it is a phone numberaction refers to an action or texting project, actions may represent functionality not limited to textinggid refers to a contact group IDproxy refers to a virtual proxy number to send fromctime refers to creation time in milliseconds since Epochmtime refers to last update time in milliseconds since Epoch⚠️ Note: Only documented properties are guaranteed to be present in API responses, some properties may be marked as deprecated but any undocumented property that appear in responses can be removed without any notice.
To keep the API available to all users, the system enforces request rate limiting. Requests that hit any of our rate limits will receive a 429 Too Many Requests response, which contains the standard Retry-After header indicating how many seconds the client should wait before retrying the request.
Here is an example of such error response:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 0.825
{"status":429,"message":"Too many requests","retryAfter":825}
Limits are allocated per API key. Different endpoints may have different rates.
Rates for common endpoints:
/api/ - 3 reqs/sec, default rate for all/api/message/next - 100 reqs/sec/api/message/send - 100 reqs/sec/api/proxy/send - 100 reqs/sec/api/project/create - 10 reqs/hour/api/contact/import - 10 reqs/hourMany resources in the system limited by quotas, system wide or account specific. Quotas marked with * can be changed by support on request for each account individually.