Help Docs Developer Resources Project API Project API Reference

Project API

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

Project Object
Get an Project
Create an Project
Update an Project
Send a Test Message
Submit an Project for Sending (Outsource Only - Most Common)
Make an Project Live for Sending (Send Yourself Only - Least Common)
Stop an Project
Get Projects Statistics
Common Errors
Other
Relevant Links

Project Object

The Project object contains information about your messages, including organization ID, status, details, messaging statistics, and more.

Account
- cid - Your account ID
- account - Your account name
Project
- action - The project id
- name - The project name
- status - The project status (live, archived)
- num - The project number
- type - Message type (SMS, MMS)
- sent_by - The type of team that sent out the project (self, outsourced, fullservice)
- message - The project message
- media - The file attachment on the project
- campaignId - The Campaign Registry(TCR) Id (No if no ID)
- project - The project name
- proxy - Phone numbers the project sends from
- areacode - Areacode of the phone numbers the project sends from
- test_phone - Phone number that test messages are sent to
Contact Group
- group - ID of the contact group the project will be sent to
- group_name - Name of the contact group the project will be sent to
- group_count - Number of contacts of the contact group the project will be sent to
- contact_filter - Dynamic filter to filter groups in project before sending
- contact_count - Number of contacts the project will be sent to after the filter
Outsource
- submit_time - Date and time the project was submitted for outsourcing
- outsource_start_time - Start date and time for the project
- outsource_end_time - End date and time for the project
- outsource_email - Email for project updates to be sent to
- outsource_notes - Notes visible in portal for the project.
Short Link
- clicks - Total number of link clicks (when RumbleUp link shortener is used)
- shortids - A list of existing shortener IDs used in the text
- links - A list of links used in the text, it includes all links shortener or not
- redirect - A list of shortlink original urls corresponding to the same index in the shortids list above
Timefields
- live_time - Date and time the project was made live
- test_time - Date and time the project was first tested
- update_time - Date the time the project was last updated
- sent_time - Date and time of last project message sent
- reply_time - Date and time of last reply message received
Billing
- estimate_cost - Estimated total cost of the project including tax
- estimate_tax - Estimated tax of the project
- cost - Total billed cost of the project
- tax - Total additional tax charged (when applicable)
Statistics
- target - Total number of contacts
- sent - Total number of messages sent
- sent_percent - Percent of messages sent compared to total
- segments_sent - Total number of SMS segments sent
- delivered - Total number of messages successfully delivered
- delivered_percent - Percent of messages successfully delivered
- received - Total number of incoming texts (including opt-outs)
- dnd - Number of opt outs received
- bad - Number of contacts marked bad on this project
- spam - Number of messages flagged as spam
- landline - Number of contacts flagged as landline
- err - Number of messaged flagged with an error tag (e.g. landline or undeliverable)
- skipped - Number of messages where sending was skipped
- replies - Notal number of replies (without of opt-outs)
- responses - Notal number of responses sent from texters
- autoresponses - Notal number of responses sent from auto-responses
- received_percent - Percent of messages received out of sent messages
- received_target_percent - Percent of messages received out of total contacts
- dnd_percent - Percent of opt-outs received out of sent messages
- dnd_target_percent - Percent of opt-outs received out of total contacts
- bad_percent - Percent of contacts marked bad received out of sent messages
- bad_target_percent - Percent of contacts marked bad out of total contacts
- spam_percent - Percent of messages undelivered due to spam out of sent messages
- spam_target_percent - Percent of messages undelivered due to spam out of total contacts
- landline_percent - Percent of contacts marked as landline out of sent messages
- landline_target_percent - Percent of contacts marked as landline out of total contacts
- err_percent - Percent of messages undelivered due to error out of sent messages
- err_target_percent - Percent of messages undelivered due to error out of total contacts
- skipped_percent - Percent of messages skipped out of sent messages
- skipped_target_percent - Percent of messages skipped out of total contacts
- replies_percent - Percent of replies received out of sent messages
- err_target_percent - Percent of replies received out of total contacts

Deprecated 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
}

Get an Project

Endpoint: /api/project/get/{project_id}
Method: GET
Description: Retrieve details about a specific project by ID. This is faster and simpler way to get an project details if the ID is known.
Request Parameters:
{project_id} (required, Number): ID of the project to retrieve (action property)
Returns:
A single Project object.

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
}

Create an 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.
  - Supported Flags:
    - outsourced (required for the outsource_* information to be used)
      Note: 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.
- 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:
- 400
  An input field validation error details in the message

CSV file columns:
- phone (required)
- name (required if first_name is not present)
- first_name (required if name is not present)
- email
- url
- icon
- source
- notes
- question
- custom1, custom2, custom3, custom4, custom5

Outsource Date Format:
ISO 8601 Date-Time Format:
YYYY-MM-DDTHH:MM:SS±HH:MM
Example

2024-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
}

Update an 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.
  - Supported Flags:
    - 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 TZ
- outsource_end (optional): Updated end date & time for outsourcing the project, same format as the start
- outsource_email (optional): Updated email for outsourcing the project.
- outsource_notes (optional): Updated additional notes or description for outsourcing
- shorturl_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:
- 400
  An input field validation error details in the message

Example 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
}

Send a Test Message

Endpoint: /api/project/test/{project_id}
Method: POST
Description: Send a test message for an project before submitting.
Request Parameters:
- {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.
Returns:
A single Project object.

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
}

Submit an Project for Sending (Outsource Only - Most Common)

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:
- 400
  An input field validation error details in the message

Note: 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.

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
}

Make an Project Live for Sending (Send Yourself Only - Least Common)

Endpoint: /api/project/send/{project_id}
Method: POST
Description: Make an project live.
Request Parameters:
- {project_id} (required, Number): ID of the project to send
Returns:
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
}

Stop an Project

Endpoint: /api/project/stop/{project_id}
Method: POST
Description: Stop a specific project from sending, moving it to “Testing” mode.
Request Parameters:
- {project_id} (required, Number): ID of the project to stop
Returns:
A single Project object.

Example 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
}

Get Projects Statistics

Endpoint: /api/project/stats
Method: POST
Description: Retrieve statistics for recent projects. Returns CSV with stats for all projects created or sent in the last 24 hours by default.
Request Parameters:
- format (optional): Response format (xml, json, csv).
- 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.
Returns:
A list of Project objects.

Example Request:
Stats in JSON format:

curl -X POST https://app.rumbleup.com/api/project/stats?format=json -u 'CID:APIKEY' -d

Example Response:

[
 {
   "cid": "c_abc123",
   "action": 1,
   "status": "Testing",
   // Additional details specific to the sending response
 },
 {
   "cid": "c_abc123",
   "action": 2,
   "status": "Live",
   // Additional details specific to the sending response
 },
 ...
]

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

Common Errors

`403 Please include opt-out instructions in your message`

If 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 used`

If 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.

Other

Outsourced Project API Terms

These terms are represented by the terms_agree fields in the API.

I authorize RumbleUp to send this message
I understand changes may not be made once the program has begun
I understand that submitting this order with less than 48 hours notice may limit the number of texts which can be successfully delivered
I authorize RumbleUp to exercise discretion to make changes necessary to optimize the success rate of this program (any such changes will not alter the intent of the program)
I acknowledge that projects submitted with less than 24 hours until their start time may encounter higher spam rates and that projects with a sending window of less than 1 hour per 10,000-group contacts may also encounter higher spam rates. I accept this additional risk if applicable to my project.

Relevant Links

General API Overview
Project Project Workflow

Home

For Developers

Project API

Project Object

Get an Project

Create an Project

Update an Project

Send a Test Message

Submit an Project for Sending (Outsource Only - Most Common)

Make an Project Live for Sending (Send Yourself Only - Least Common)

Stop an Project

Get Projects Statistics

Common Errors

`403 Please include opt-out instructions in your message`

`400 The group must be Active in order to be used`

Other

Outsourced Project API Terms

Relevant Links