Help Docs Developer Resources Action API Action API Reference

Action API

The “Actions” resource in our API corresponds to UI RumbleUp Projects. You can create and manage actions via this API.

You can also send test messages and submit messages to be sent by your team or an outsourcing team.

Endpoint:

https://app.rumbleup.com/api/action

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

Action Object

The Action 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 action id
- name - The action name
- status - The action status (live, archived)
- num - The action number
- type - Message type (SMS, MMS)
- sent_by - The type of team that sent out the action (self, outsourced, fullservice)
- message - The action message
- media - The file attachment on the action
- campaignId - The Campaign Registry(TCR) Id (No if no ID)
- project - The action name
- proxy - Phone numbers the action sends from
- areacode - Areacode of the phone numbers the action sends from
- test_phone - Phone number that test messages are sent to
Contact Group
- group - ID of the contact group the action will be sent to
- group_name - Name of the contact group the action will be sent to
- group_count - Number of contacts of the contact group the action will be sent to
- contact_filter - Dynamic filter to filter groups in action before sending
- contact_count - Number of contacts the action will be sent to after the filter
Outsource
- submit_time - Date and time the action was submitted for outsourcing
- outsource_start_time - Start date and time for the action
- outsource_end_time - End date and time for the action
- outsource_email - Email for action updates to be sent to
- outsource_notes - Notes visible in portal for the action.
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 action was made live
- test_time - Date and time the action was first tested
- update_time - Date the time the action was last updated
- sent_time - Date and time of last action message sent
- reply_time - Date and time of last reply message received
Billing
- estimate_cost - Estimated total cost of the action including tax
- estimate_tax - Estimated tax of the action
- cost - Total billed cost of the action
- 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 action
- 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 Action

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

Example Request:

curl -X GET https://app.rumbleup.com/api/action/get/1 -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'

Example Response:

{
  "action": 1,
  "name": "Action 1",
  // Additional details specific to the action
}

Create an Action

Endpoint: /api/action/create
Method: POST
Description: Create a new action.
Request Parameters:
- name (required): Name of the action.
- message (required): Message associated with the action.
- media (optional): Media file associated with the action (e.g., image, video)…
- group (optional): Group associated with the action.
- group_file (optional): CSV file containing group information (if group is “null”)
- campaignId (optional): TCR campaign ID for the action. 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 action.
  - Supported Flags:
    - outsourced (required for the outsource_* information to be used)
      Note: Outsourced actions require a minimum of 2500 after any contact filtering is applied. Actions 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 action, 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 action, same format as the start
- outsource_email (optional): Email for outsourcing the action.
- outsource_contact (optional): Contact name for outsourcing the action.
- outsource_notes (optional): Additional notes or description for outsourcing
- shorturl_domain (optional): Domain for short URLs associated with the action.
- shorturl_tracking (optional): Enable tracking for short URLs.
Returns:
A single Action object.

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/action/create -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'
-d "name=New Action&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 Action",
    "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 action
}

Update an Action

Endpoint: /api/action/update/{action_id}
Method: POST
Description: Create a new action.
Request Parameters:
- {action_id} (required): ID of the action to update in the path
- name (optional): Updated name of the action.
- message (optional): Updated message associated with the action.
- media (optional): Updated media file associated with the action (e.g., image, video)…
- group (optional): Updated group associated with the action.
- group_file (optional): Updated CSV file containing group information (if group is “null”)
- campaignId (optional): TCR campaign Id for the action. 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 action.
  - Supported Flags:
    - outsourced (required for the outsource_ information to be used)
- outsource_start (optional): Updated start date & time for outsourcing the action, 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 action, same format as the start
- outsource_email (optional): Updated email for outsourcing the action.
- outsource_notes (optional): Updated additional notes or description for outsourcing
- shorturl_domain (optional): Updated domain for short URLs associated with the action.
- shorturl_tracking (optional): Update enable tracking for short URLs.
Returns:
A single Action object.

Example Request:

curl -X POST https://app.rumbleup.com/api/action/update/3 -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'
-d "name=Updated Action&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 action
}

Send a Test Message

Endpoint: /api/action/test/{action_id}
Method: POST
Description: Send a test message for an action before submitting.
Request Parameters:
- {action_id} (required): ID of the action to test
- 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 action.
Returns:
A single Action object.

Example Request

curl -X POST https://app.rumbleup.com/api/action/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 action
}

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

Endpoint: /api/action/submit/{action_id}
Method: POST
Description: Submit an action to be scheduled for outsourced sending.
Request Parameters:
{action_id} (required): ID of the action to submit
terms_agree (required): Indication that you’ve read and agree to the terms at the bottom of this doc.
Returns:
A single Action object.

Note: Outsourced actions require a minimum of 2500 after any contact filtering is applied. Actions 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/action/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 action
}

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

Endpoint: /api/action/send/{action_id}
Method: POST
Description: Make an action live.
Request Parameters:
- {action_id} (required): ID of the action to send
Returns:
A single Action object.
Note
Once an action is Live texters can start sending messages via our portal or via Message API.

Example Request:

curl -X POST https://app.rumbleup.com/api/action/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 Action

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

Example Request:

curl -X POST https://app.rumbleup.com/api/action/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 Actions Statistics

Endpoint: /api/action/stats
Method: POST
Description: Retrieve statistics for recent actions. Returns CSV with stats for all actions created or sent in the last 24 hours by default.
Request Parameters:
- format (optional): Response format (xml, json, csv, jsontext).
- 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.
- action (optional): Specific action ID.
- name (optional): Filter pattern for the name field.
Returns:
A list of Action objects.

Example Request:
Stats in JSON format:

curl -X POST https://app.rumbleup.com/api/action/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/action/stats

All stats for the last week:

curl -u CID:APIKEY https://app.rumbleup.com/api/action/stats?interval=604800000

All stats for the last week 7 days:

curl -u CID:APIKEY https://app.rumbleup.com/api/action/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/action/stats?since=1643673600000`

or as a date

curl -u CID:APIKEY https://app.rumbleup.com/api/action/stats?since=2022-02-01

Stats for a specific action:

curl -u CID:APIKEY https://app.rumbleup.com/api/action/stats?action=25

Stats for all actions that begin with the pattern:

curl -u CID:APIKEY https://app.rumbleup.com/api/action/stats?name=POLL

Return as CSV:

curl -u CID:APIKEY https://app.rumbleup.com/api/action/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 Action 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
Action Project Workflow

Home

For Developers

Action API

Action Object

Get an Action

Create an Action

Update an Action

Send a Test Message

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

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

Stop an Action

Get Actions 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 Action API Terms

Relevant Links