Home

For Developers

Help Docs Developer Resources Contact API Contacts API

Contacts API

The Contacts API allows you to manage contact information, including importing and syncing contacts, retrieving contact group details, and downloading contact data.

Endpoint:

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

Contact Object

The Contact object comprises the following fields

Basic contact fields (can be imported)

  • phone - phone number, will be used as rupid by default
  • name - full contact name
  • first_name
  • last_name
  • email
  • street
  • city
  • zipcode
  • county
  • url - general purpose url
  • icon - contact specific icon url
  • descr - general purpose description
  • question - general purpose question

Reference fields (can be imported)

  • source - mostly to keep unique reference in your system
  • custom1 - general purpose fields to be used in messasge placeholders or shorturls
  • custom2
  • custom3
  • custom4
  • custom5

System fields

  • group - a list of groups this contact belongs to, during import a group is created automatically

  • action - a list of actions/projects this contact has been contacted in

  • reaction - a list of actions/projects this contact replied to

  • create_time - time the contact was first created/imported

  • update_time - last time the contcat was manually updated

  • sent_time - last time the contact received a message or sent a message

  • flags - contains all of the tags applied to the contact, both defined by you and system tags. Here are the reserved system tags:

    • dnd - Do Not Disturb (system-applied and non-removable tag when the contact has opted out with a STOP request)
    • bad - Opt-Out (user-applied and removable tag when a contact has opted out using language other than a STOP request)
    • landline - This number has been checked against the landline database and is a landline
    • unreachable - After several messages with failed deliveries, this contact is deemed unreachable
    • replied - The contact has replied
    • rude - The contact used profanity or was otherwise marked as rude
    • tester - This contact has been sent test texts
    • optin - This contact has opted in to keyword or form for receiving texts

Example Object:

{
  "phone": "5551234567",
  "name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "street": "123 Maple Street",
  "city": "Springfield",
  "zipcode": "12345",
  "url": "https://www.johndoewebsite.com",
  "icon": "https://www.johndoewebsite.com/icon.png",
  "source": "UNIQUE12356",
  "descr": "This is a sample description for John Doe.",
  "custom1": "Custom field 1 data",
  "custom2": "Custom field 2 data",
  "custom3": "Custom field 3 data",
  "custom4": "Custom field 4 data",
  "custom5": "Custom field 5 data",
  "group": [ "46","48"],
  "action": [ "23", "26" ],
  "create_time": "11/22/2024 12:53pm CDT",
  "update_time": "04/15/2025 01:15am CDT",
  "sent_time": "02/22/2025 06:27pm CDT"
}

Select Contacts

  • Endpoint: /api/contact/select
  • Method: GET or POST
  • Description: Select contacts by query filter.
  • Request Body Parameters:
    • action - A list of projects contacts receive messages
    • filter - A filter type: in, out, reply, dnd, unread, delivered, error, modified
    • actions - A list of projects contacts received messages and replied
    • group - A list of groups contacts belong to.
    • since - Last message received after this timestamp, if 2 timestamps given (T1,T2) then last messages received in that period of time
    • flags - Contacts with given list of flags
    • noflags - Contats without given flags
    • q - text to match in any field

Example Request:

curl -XPOST -u CID:KEY -d 'action=4' https://app.rumbleup.com/api/contact/select

Example Response:

{
    "count": 3,
    "total": 3,
    "next_token": "....",
    "data": [...]
}

Contact Sync

  • Endpoint: /api/contact/sync
  • Method: POST
  • Description: Perform the import of individual contact.
  • Request Body Parameters:
    • phone: (required) Contact’s phone number
    • name or first_name: (required) Contact’s full name or first name
    • first_name: Contact’s first name
    • last_name: Contact’s last name
    • email: Contact’s email address
    • street: Contact’s street address
    • city: Contact’s city of residence
    • zipcode: Contact’s postal code
    • url: Contact’s website URL
    • icon: URL to the contact’s icon/image
    • source: Source of the contact information
    • descr: Description or notes about the contact
    • custom1, custom2, custom3, custom4, custom5: Custom fields for additional information
  • Example Request:
curl -X GET https://app.rumbleup.com/api/contact/sync -d '{"phone": "1234567890", "name": "John Doe", // more contact parameters... }' -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'
  • Example Request Data:
{
  "phone": "1234567890",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "city": "Cityville",
  "zipcode": "12345",
  "url": "https://example.com",
  "icon": "https://example.com/avatar.jpg",
  "source": "Import",
  "descr": "A valuable contact",
  "custom1": "Custom Field 1",
  "custom2": "Custom Field 2"
}

Contact Import

  • Endpoint: /api/contact/import

  • Method: POST

  • Description: To perform contact imports programmatically, you can use RumbleUp’s API as an alternative to the Basic Contact Import available in the portal.

  • Request Body Parameters:

    • csv (File, required): CSV file with contact information

  • File Format
    The file to be imported must be in CSV format. The first line of the file should serve as the header row, containing column names.

    • Required Columns

      • phone
      • name or first_name

    • Allowed Columns

      • phone
      • name
      • first_name
      • last_name
      • email
      • street
      • city
      • zipcode
      • url
      • icon
      • source
      • descr
      • custom1
      • custom2
      • custom3
      • custom4
      • custom5

  • Common Errors
    No required columns provided: phone and (name or first_name)

    • Steps to Fix
      1. Verify the CSV file has a header row with the required fields.
      2. Check the data submission argument; it should be -F with Content-Type as multipart/form-data or --data-binary.
      3. Ensure each column is in lowercase; otherwise, the API will not recognize them.

Example Request

curl -X POST -F 'csv=@exampleFile.csv' https://app.rumbleup.com/api/contact/import -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'

Example Response

{
    "cid": "c_abc123,
    "descr": "exampleFile",
    "gid": "2",
    "name": "exampleFile"
}

Get Contact Group

  • Endpoint: /api/group/get/{group_id}
  • Method: GET or POST
  • Description: Retrieve information about a specific group.
  • Request Body Parameters:
    • cid: (required) Contact ID
    • group_id: (required) Group ID

Example Request

curl "https://app.rumbleup.com/api/group/get/1 -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'

Example Response

{
    "cid": "c_abc123",
    "gid": "1",
    "name": "My Group Name",
    "status": "ok",
    "item_count": 2,                                // Number of contacts in the group
    "item_ready": 2,                                // Number of good contacts in the group
    "filter": "",
    "item_stats": {                                 // Stats associated with the project
        "count": {                                  // Contact detail breakdown
            "zipcode": 1,
            "first_name": 1,
            "phone": 1,
            "city": 1,
            "street": 1
        },
        "flags": {                                  // Tag breakdown
            "optin": 1,
            "new": 1
        },
        "name": {
            "0-10": 1
        },
        "area": {                                   // Areacode breakdown
            "555": 1
        }
    },
    "tasks": [                                     // Tasks associated with group
        {
           "name": "Statistics",
           "status": "finished",
           "count": "11",
           "total": "11",
           "status_time": "04/20/2025 03:34pm CDT"
        }
    ],
    "create_time": "04/20/2025 03:34pm CDT",                         
    "status_time": "04/20/2025 03:34pm CDT",                        
    "update_time": "04/20/2025 03:34pm CDT",                        
}

Download Contacts

  • Endpoint: /api/contact/download
  • Method: GET or POST
  • Description: Download contacts based on specified criteria.
  • Request Body Parameters:
    • gid: Group ID
    • flags: Flags
    • q: Query parameters

Example Request

curl -X GET "https://app.rumbleup.com/api/contact/download?gid=your_group_id&flags=your_flags&q=your_query_parameters" -o output.csv -u '<YOUR_ACCOUNT_CID>:<YOUR_API_KEY>'

Example Response

Downloaded CSV File