Help Docs Developer Resources Project API Project API Reference
The “Projects” resource in our API corresponds to UI RumbleUp Projects. You can create and manage projects via this API.
You can also send test messages and submit messages to be sent by your team or an outsourcing team. Read more about the sending flow and requirements in this doc.
Base Endpoint:
https://app.rumbleup.com/api/project
The project API also has an alias so both /api/project and /api/action can be used interchangeably.
For example both endpoints are the same below:
https://app.rumbleup.com/api/project/stats
https://app.rumbleup.com/api/action/stats
The Project object contains information about your messages, including organization ID, status, details, messaging statistics, and more.
cid - Your account IDaccount - Your account nameaction - The project idname - The project namestatus - The project status (live, archived)num - The project numbertype - Message type (SMS, MMS)sent_by - The type of team that sent out the project (self, outsourced, fullservice)message - The project messagemedia - The file attachment on the projectcampaignId - The Campaign Registry(TCR) Id (No if no ID)project - The project nameproxy - Phone numbers the project sends fromareacode - Areacode of the phone numbers the project sends fromtest_phone - Phone number that test messages are sent togroup - ID of the contact group the project will be sent togroup_name - Name of the contact group the project will be sent togroup_count - Number of contacts of the contact group the project will be sent tocontact_filter - Dynamic filter to filter groups in project before sendingcontact_count - Number of contacts the project will be sent to after the filtersubmit_time - Date and time the project was submitted for outsourcingoutsource_start_time - Start date and time for the projectoutsource_end_time - End date and time for the projectoutsource_email - Email for project updates to be sent tooutsource_notes - Notes visible in portal for the project.clicks - Total number of link clicks (when RumbleUp link shortener is used)shortids - A list of existing shortener IDs used in the textlinks - A list of links used in the text, it includes all links shortener or notredirect - A list of shortlink original urls corresponding to the same index in the shortids list abovelive_time - Date and time the project was made livetest_time - Date and time the project was first testedupdate_time - Date the time the project was last updatedsent_time - Date and time of last project message sentreply_time - Date and time of last reply message receivedestimate_cost - Estimated total cost of the project including taxestimate_tax - Estimated tax of the projectcost - Total billed cost of the projecttax - Total additional tax charged (when applicable)target - Total number of contactssent - Total number of messages sentsent_percent - Percent of messages sent compared to totalsegments_sent - Total number of SMS segments sentdelivered - Total number of messages successfully delivereddelivered_percent - Percent of messages successfully deliveredreceived - Total number of incoming texts (including opt-outs)dnd - Number of opt outs receivedbad - Number of contacts marked bad on this projectspam - Number of messages flagged as spamlandline - Number of contacts flagged as landlineerr - Number of messaged flagged with an error tag (e.g. landline or undeliverable)skipped - Number of messages where sending was skippedreplies - Notal number of replies (without of opt-outs)responses - Notal number of responses sent from textersautoresponses - Notal number of responses sent from auto-responsesreceived_percent - Percent of messages received out of sent messagesreceived_target_percent - Percent of messages received out of total contactsdnd_percent - Percent of opt-outs received out of sent messagesdnd_target_percent - Percent of opt-outs received out of total contactsbad_percent - Percent of contacts marked bad received out of sent messagesbad_target_percent - Percent of contacts marked bad out of total contactsspam_percent - Percent of messages undelivered due to spam out of sent messagesspam_target_percent - Percent of messages undelivered due to spam out of total contactslandline_percent - Percent of contacts marked as landline out of sent messageslandline_target_percent - Percent of contacts marked as landline out of total contactserr_percent - Percent of messages undelivered due to error out of sent messageserr_target_percent - Percent of messages undelivered due to error out of total contactsskipped_percent - Percent of messages skipped out of sent messagesskipped_target_percent - Percent of messages skipped out of total contactsreplies_percent - Percent of replies received out of sent messageserr_target_percent - Percent of replies received out of total contactsDeprecated fields
These fields will be removed in the future:
tcrcid, live, updated, tested, lastmsg, lastreply, submitted, percent, outsource_start, outsource_end
Example Object:
{
"cid": "12345",
"account": "Acme Corporation",
"action": "123",
"name": "Summer Campaign",
"status": "live",
"num": "123",
"type": "SMS",
"sent_by": "self",
"message": "Don't miss our summer sale! Visit our website for discounts.",
"media": null,
"campaignId": "No",
"project": "Summer Campaign",
"phone": ["11234567890", "10987654321"],
"areacode": "123",
"test_phone": "11234567890",
"group": "1",
"group_name": "Premium Customers",
"group_count": 10000,
"contact_filter": "{\"op\":\"all\",\"condition\":[{\"name\":\"state\",\"op\":\"eq\",\"value\":\"CA\"}]}"
"contact_count": 8000,
"outsource_start_time": "2024-08-20T10:00:00Z",
"outsource_end_time": "2024-08-20T18:00:00Z",
"outsource_email": "updates@acme.com",
"outsource_notes": "Priority project for VIP clients.",
"clicks": 1200,
"shortids": ["abc", "def"],
"links": ["http://short.url/abc", "http://short.url/def"],
"redirect": ["http://original.url/1", "http://original.url/2"],
"live_time": "2024-08-20T09:00:00Z",
"test_time": "2024-08-19T15:00:00Z",
"update_time": "2024-08-20T09:30:00Z",
"sent_time": "2024-08-20T09:05:00Z",
"reply_time": "2024-08-20T09:15:00Z",
"estimate_cost": 1500.00,
"estimate_tax": 120.00,
"cost": 1450.00,
"tax": 116.00,
"target": 10000,
"sent": 9500,
"sent_percent": 95.0,
"segments_sent": 9500,
"delivered": 9200,
"delivered_percent": 96.84,
"received": 800,
"dnd": 50,
"bad": 30,
"spam": 10,
"landline": 5,
"err": 15,
"skipped": 200,
"replies": 750,
"responses": 700,
"autoresponses": 50,
"received_percent": 8.42,
"received_target_percent": 7.50,
"dnd_percent": 0.53,
"dnd_target_percent": 0.50,
"bad_percent": 0.32,
"bad_target_percent": 0.30,
"spam_percent": 0.11,
"spam_target_percent": 0.10,
"landline_percent": 0.05,
"landline_target_percent": 0.05,
"err_percent": 0.16,
"err_target_percent": 0.15,
"skipped_percent": 2.11,
"skipped_target_percent": 2.00,
"replies_percent": 7.89,
"err_target_percent": 7.50
}
/api/project/get/{project_id}{project_id} (required, Number): ID of the project to retrieve (action property)Example Request:
curl -X GET https://app.rumbleup.com/api/project/get/1 -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'
Example Response:
{
"action": 1,
"name": "Project 1",
// Additional details specific to the project
}
Endpoint: /api/project/create
Method: POST
Description: Create a new project.
Request Parameters:
name (required): Name of the project.
message (required): Message associated with the project.
media (optional): Media file associated with the project (e.g., image, video)…
group (optional): Group associated with the project.
group_file (optional): CSV file containing group information (if group is “null”)
campaignId (optional): TCR campaign ID for the project. See TCR Campaign Select. This replaces depricated tcr_cid parameter.
proxy (optional): If TCR campaignId is provided then this must be a proxy number from the TCR proxy list, it will also determine areacode for the rest of the lines in the campaign. Use ‘All’ to select all proxy numbers from TCR campaign. If no campaignId is provided then this mut be a verified phone assigned to your account to be used instead of a TCR line. This works for short codes, toll free and long code numbers. This replaces deprecated tcr_phone and phone parameters.
flags (optional): List of flags associated with the project.
outsourced (required for the outsource_* information to be used)outsource_start (optional): Start date & time for outsourcing the project, it must include full date time and timezone, like MM/DD/YYYY HH:MM TZ, where TZ is EST/EDT, CET/CDT, MST/MDT, PST/PDT
outsource_end (optional): End date & time for outsourcing the project, same format as the start
outsource_email (optional): Email for outsourcing the project.
outsource_contact (optional): Contact name for outsourcing the project.
outsource_notes (optional): Additional notes or description for outsourcing
shorturl_domain (optional): Domain for short URLs associated with the project.
shorturl_tracking (optional): Enable tracking for short URLs.
Response:
Success: Returns a project object.
Error: Returns an appropriate error message when validation fails in the common format explained in General Overview
Specific Errors
If not marked as retry-able errors returned by this endpoint are final, no report has been created.
Error codes:
400phone (required)name (required if first_name is not present)first_name (required if name is not present)emailurliconsourcenotesquestioncustom1, custom2, custom3, custom4, custom5YYYY-MM-DDTHH:MM:SS±HH:MM2024-12-25T10:00:00-06:00
Example Request
curl -X POST https://app.rumbleup.com/api/project/create -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'
-d "name=New Project&message=This is my test message with a https://longerLink.com&areacode=123&flags=outsourced&outsource_start=2023-12-01T13:00:00-06:00&outsource_end=2023-12-01T17:30:00-06:00&outsource_email=outsourcer@example.com&outsource_notes=Additional notes&shorturl_domain=exmple.com&shorturl_tracking=true&campaignId=CSDF123"
-F "file=@/path/to/media_file.jpg"
-F "group_file=@/path/to/group_file.csv"
Example Response:
{
"cid": "c_abc123",
"action": 3,
"num": 3,
"media" : "https://imageUrl.com/c_abc123/3.jpg",
"status": "Draft",
"project": "New Project",
"message": "This is my test message with a https://exmple.com STOP to opt out",
"type": "MMS",
"group": "3",
"group_name": "group_file"
"campaignId": "CSDF123",
"flags": ["outsourced"],
"outsource_start_time": "2023-12-1 13:00 CST",
"outsource_end_time": "2023-12-1 17:30 CST",
"outsource_email": "outsourcer@example.com",
"outsource_notes": "Additional notes"
// Additional details specific to the created project
}
Endpoint: /api/project/update/{project_id}
Method: POST
Description: Create a new project.
Request Parameters:
{project_id} (required, Number): ID of the project to update in the path (action property)name (optional): Updated name of the project.message (optional): Updated message associated with the project.media (optional): Updated media file associated with the project (e.g., image, video)…group (optional): Updated group associated with the project.group_file (optional): Updated CSV file containing group information (if group is “null”)campaignId (optional): TCR campaign Id for the project. See TCR Campaign Select. This replaces depricated tcr_cid parameter.proxy (optional): If TCR campaignId is provided then this must be a proxy number from the TCR proxy list, it will also determine areacode for the rest of the lines in the campaign. Use ‘All’ to select all proxy numbers from TCR campaign. If no campaignId is provided then this mut be a verified phone assigned to your account to be used instead of a TCR line. This works for short codes, toll free and long code numbers. This replaces deprecated tcr_phone and phone parameters.flags (optional): Updated list of flags associated with the project.
outsourced (required for the outsource_ information to be used)outsource_start (optional): Updated start date & time for outsourcing the project, it must include full date time and timezone, like MM/DD/YYYY HH:MM TZoutsource_end (optional): Updated end date & time for outsourcing the project, same format as the startoutsource_email (optional): Updated email for outsourcing the project.outsource_notes (optional): Updated additional notes or description for outsourcingshorturl_domain (optional): Updated domain for short URLs associated with the project.shorturl_tracking (optional): Update enable tracking for short URLs.Response:
Success: Returns a project object.
Error: Returns an appropriate error message when validation fails in the common format explained in General Overview
Specific Errors
If not marked as retry-able errors returned by this endpoint are final, no report has been created.
Error codes:
400Example Request:
curl -X POST https://app.rumbleup.com/api/project/update/3 -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'
-d "name=Updated Project&message=Updated test message with a https://exmple.com STOP to opt out&phone=18001234567&flags=outsourced&outsource_start=2023-12-22T13:00:00-06:00&outsource_end=2023-12-22T17:30:00-06:00&outsource_email=updated_outsourcer@example.com&outsource_notes=Updated notes"
-F "media=@/path/to/updated_media_file.jpg"
-F "group_file=@/path/to/updated_group_file.csv"
Example Response:
{
"cid": "c_abc123",
"action": 3,
// Additional details specific to the updated project
}
/api/project/test/{project_id}{project_id} (required, Number): ID of the project to test (action property)test_phone (required): Phone number to send the test message.terms_agree (optional): Indication that you’ve read and agree to the terms at the bottom of this doc.message (optional): Message associated with the project.Example Request
curl -X POST https://app.rumbleup.com/api/project/test/3 -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>' -d "test_phone=1234567890&terms_agree=true"
Example Response:
{
"cid": "c_abc123",
"action": 3,
"status": "Testing",
"test_time": "2023-11-30 15:30:44 GMT-0600",
// Additional details specific to the updated project
}
Endpoint: /api/project/submit/{project_id}
Method: POST
Description: Submit an project to be scheduled for outsourced sending.
Request Parameters:
{project_id} (required, Number): ID of the project to submit
terms_agree (required): Indication that you’ve read and agree to the terms at the bottom of this doc.
Response:
Success: Returns a report object.
Error: Returns an appropriate error message when validation fails in the common format explained in General Overview
Specific Errors
If not marked as retry-able errors returned by this endpoint are final, no report has been created.
Error codes:
400Note: Outsourced projects require a minimum of 2500 after any contact filtering is applied. Projects below this threshold may not be accepted for outsourcing. Please contact the support about changing this limit for your account. See API Overview for all default quotas.
Example Request:
curl -X POST https://app.rumbleup.com/api/project/submit/3 -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'
Example Response:
{
"cid": "c_abc123",
"action": 3,
"submit_time": "2023-11-30 16:04:32 GMT-0600",
// Additional details specific to the updated project
}
Endpoint: /api/project/send/{project_id}
Method: POST
Description: Make an project live.
Request Parameters:
{project_id} (required, Number): ID of the project to sendReturns:
A single Project object.
Note
Once an project is Live texters can start sending messages via our portal or via Message API.
Example Request:
curl -X POST https://app.rumbleup.com/api/project/send/1 -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'
Example Response:
{
"cid": "c_abc123",
"action": 1,
"status": "Live",
"live_time": "2023-11-30 16:10:09 GMT-0600"
// Additional details specific to the sending response
}
/api/project/stop/{project_id}{project_id} (required, Number): ID of the project to stopExample Request:
curl -X POST https://app.rumbleup.com/api/project/stop/1 -H "Authorization: Bearer YOUR_API_KEY"
Example Response:
{
"cid": "c_abc123",
"action": 1,
"status": "Testing",
// Additional details specific to the sending response
}
/api/project/statsformat (optional): Response format, supported values are json, xml, csv, JSON is default if not provided.interval (optional): Time in milliseconds.days (optional): Time in days.since (optional): Start date in milliseconds or as a string.before (optional): End date in milliseconds or as a string.project (optional): Specific project ID.name (optional): Filter pattern for the name field.NOTE: The json format is JSONL, i.e. one JSON object per line.
Example Request:
Stats in default format:
curl -X POST https://app.rumbleup.com/api/project/stats -u 'CID:APIKEY' -d
Example Response:
[
"cid": "c_123456",
"account": "Test",
"action": "54",
"name": "Untitled",
"status": "Draft",
"num": "54",
"type": "SMS",
"sent_by": "self",
"areacode": "203",
"campaignId": "CVJI10P",
"live_time": "",
"test_time": "",
"update_time": "2025-08-27 17:30:14 GMT-0400",
"sent_time": "",
"reply_time": "",
"proxy": [
"12031558771"
],
"phone": [
"12031558771"
],
"tcr_cid": "CVJI10P",
"live": "",
"tested": "",
"updated": "2025-08-27 17:30:14 GMT-0400",
"lastmsg": "",
"lastreply": "",
"percent": 100,
"estimate_cost": "$0.00",
"estimate_tax": "$0.00",
"cost": "$0.00",
"tax": "$0.00",
"target": 0,
"sent": 0,
"sent_percent": 0,
"segments_sent": 0,
"delivered": 0,
"delivered_percent": 100,
"received": 0,
"dnd": 0,
"bad": 0,
"spam": 0,
"landline": 0,
"err": 0,
"skipped": 0,
"replies": 0,
"responses": 0,
"autoresponses": 0,
"received_percent": 0,
"received_target_percent": 0,
"dnd_percent": 0,
"dnd_target_percent": 0,
"bad_percent": 0,
"bad_target_percent": 0,
"spam_percent": 0,
"spam_target_percent": 0,
"landline_percent": 0,
"landline_target_percent": 0,
"err_percent": 0,
"err_target_percent": 0,
"skipped_percent": 0,
"skipped_target_percent": 0,
"replies_percent": 0,
"replies_target_percent": 0,
"clicks": 0,
"shortids": [
"lnY"
],
"links": [
"http://localhost/lnY.~##!"
],
"redirect": [
"http://google.com"
]
}
]
Stats in JSONL format:
curl -X POST https://app.rumbleup.com/api/project/stats?format=json -u 'CID:APIKEY' -d
Example Response:
{"cid":"c_1234567","account":"Test","action":"6","name":"testing message STOP","status":"Live","num":"6","type":"EVT","sent_by":"self","areacode":"555","campaignId":"C1TEZT","live_time":"2025-08-25 14:29:23 GMT-0400","test_time":"2025-08-25 14:29:20 GMT-0400","update_time":"2025-08-25 14:29:23 GMT-0400","sent_time":"2025-08-25 14:29:31 GMT-0400","reply_time":"2025-08-26 17:26:17 GMT-0400","proxy":["15551112233"],"phone":["15551112233"],"tcr_cid":"C1TEZT","live":"2025-08-25 14:29:23 GMT-0400","tested":"2025-08-25 14:29:20 GMT-0400","updated":"2025-08-25 14:29:23 GMT-0400","lastmsg":"2025-08-25 14:29:31 GMT-0400","lastreply":"2025-08-26 17:26:17 GMT-0400","percent":100,"estimate_cost":"$3.68","estimate_tax":"$0.00","cost":"$2.13","tax":"$0.00","target":19,"sent":19,"sent_percent":0,"segments_sent":21,"delivered":19,"delivered_percent":100,"received":11,"dnd":0,"bad":0,"spam":0,"landline":0,"err":0,"skipped":0,"replies":11,"responses":0,"autoresponses":3,"received_percent":58,"received_target_percent":0,"dnd_percent":0,"dnd_target_percent":0,"bad_percent":0,"bad_target_percent":0,"spam_percent":0,"spam_target_percent":0,"landline_percent":0,"landline_target_percent":0,"err_percent":0,"err_target_percent":0,"skipped_percent":0,"skipped_target_percent":0,"replies_percent":58,"replies_target_percent":0,"clicks":0,"shortids":[],"links":[],"redirect":[]}
...more lines with JSON object per line
More Examples:
All stats for the last 24 hours:
curl -u CID:APIKEY https://app.rumbleup.com/api/project/stats
All stats for the last week:
curl -u CID:APIKEY https://app.rumbleup.com/api/project/stats?interval=604800000
All stats for the last week 7 days:
curl -u CID:APIKEY https://app.rumbleup.com/api/project/stats?days=7
All stats since some date in the past (2022-02-1), time is milliseconds:
curl -u CID:APIKEY https://app.rumbleup.com/api/project/stats?since=1643673600000`
or as a date
curl -u CID:APIKEY https://app.rumbleup.com/api/project/stats?since=2022-02-01
Stats for a specific project:
curl -u CID:APIKEY https://app.rumbleup.com/api/project/stats?project=25
Stats for all projects that begin with the pattern:
curl -u CID:APIKEY https://app.rumbleup.com/api/project/stats?name=POLL
Return as CSV:
curl -u CID:APIKEY https://app.rumbleup.com/api/project/stats?format=csv
Response in CSV
cid,account,action,name,status,num,type,sent_by,areacode,campaignId,live_time,test_time,update_time,sent_time,reply_time,proxy,phone,tcr_cid,live,tested,updated,lastmsg,lastreply,percent,estimate_cost,estimate_tax,cost,tax,target,sent,sent_percent,segments_sent,delivered,delivered_percent,received,dnd,bad,spam,landline,err,skipped,replies,responses,autoresponses,received_percent,received_target_percent,dnd_percent,dnd_target_percent,bad_percent,bad_target_percent,spam_percent,spam_target_percent,landline_percent,landline_target_percent,err_percent,err_target_percent,skipped_percent,skipped_target_percent,replies_percent,replies_target_percent,clicks,shortids,links,redirect
c_123456,Test,54,Untitled,Draft,54,SMS,self,203,CVJI10P,,,2025-08-27 17:30:14 GMT-0400,,,"12031558771","12031558771",CVJI10P,,,2025-08-27 17:30:14 GMT-0400,,,100,$0.00,$0.00,$0.00,$0.00,0,0,0,0,0,100,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,lnY,http://local.com/lnY.~##!,http://google.com
403 Please include opt-out instructions in your messageIf you encounter a 403 Forbidden error with the message “Please include opt-out instructions in your message,” it indicates the need to include “STOP” in the message field to comply with regulations. Ensure your messages adhere to this requirement for successful processing.
400 The group must be Active in order to be usedIf you receive a 400 Bad Request error stating “The group must be Active in order to be used,” you need to visit the portal and update the group status to “Active” for proper functionality. Ensure the group is active to resolve this issue.
These terms are represented by the terms_agree fields in the API.