API Reference

Explore the details of the PhoneBurner API routes.

contacts

Retrieve, add and delete contacts


GET /rest/1/contacts

Retrieves all contacts for the vendor, or restricted by category_id

Parameters:
Name Type Data Type Required Description
category_id query integer The contact "folder"
updated_from query string Include contacts that have been updated after this date/time YYYY-MM-DD HH:ii:ss
update_to query string Include contacts that have been updated up to this date/time YYYY-MM-DD HH:ii:ss. If updated_from is included, this will default to current date time if ommitted.
include_new query integer Include contacts that have been created as well as updated. This requires updated_from to be set.
email_address query string This endpoint isn't meant to be a full search tool, but you have the ability to search by email address.
include_trashed query integer By default, we only include active contacts, use this parameter to include contacts that have been trashed.
include_archived query integer By default, we only include active contacts, use this parameter to include contacts that have been archived.
sort_order query string Default is 'DESC'. 'ASC' for oldest first
page_size query string number of results to fetch. default is 25. 1...100 is valid
page query string page number to fetch. default is 1.
curl "https://www.phoneburner.com/rest/1/contacts?page_size=1&page=1" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

{
    "http_status": 200,
    "status": "success",
    "contacts":
    {
        "user_id": "13514766",
        "contacts":
        [

            {
                "user_id": "30919237",
                "owner_id": "13514766",
                "first_name": "John",
                "last_name": "Demo",
                "date_added": "2014-10-15 10:38:07",
                "original_ip": "108.66.113.199",
                "unique_id": "QS1KCYL3",
                "ad_code": "",
                "language": "en",
                "region": "US",
                "time_zone": "America\/Phoenix",
                "location_name": "PHOENIX, AZ",
                "latitude": "33.424500",
                "longitude": "112.065002",
                "raw_zip": "85034",
                "raw_phone": "6025551234",
                "last_login": "0000-00-00 00:00:00",
                "total_logins": "0",
                "points": "0",
                "do_not_call": "0",
                "call_result": null,
                "gender": "",
                "date_of_birth": "0000-00-00",
                "category_id": "0",
                "site_id": "30",
                "archived": "0",
                "trashed": "0",
                "removed": "0",
                "viewed": "0",
                "rating": "0",
                "contacted": "0000-00-00 00:00:00",
                "notes":
                {
                    "notes": "These are my notes on this contact",
                },
                "primary_email":
                {
                    "email_address": "johndemo@fakedomain.com",
                    "status": "1",
                    "soft_bounce_count": "0",
                    "hard_bounce_count": "0",
                    "is_primary": "1",
                    "double_opt_status": "0",
                    "double_opt_ip": "",
                    "type": "1"
                },
                "primary_phone":
                {
                    "phone": "(602) 555-1234",
                    "raw_phone": "6025551234",
                    "type": "5",
                    "is_primary": "1",
                    "label": null
                },
                "phones": null,
                "primary_address":
                {
                    "address": "555 W. 5th Street",
                    "address_2": "Apt #105",
                    "city": "PHOENIX",
                    "state": "Arizona",
                    "state_other": "",
                    "zip": "85034",
                    "country": "United States",
                    "type": "1",
                    "is_primary": "1"
                },
                "custom_fields": [
                    {
                        "name": "My custom field",
                        "type": "1",
                        "value": "my value"
                    }
                ]
            }
        ],
        "page_size": 1,
        "total_results": "68",
        "page": 1,
        "total_pages": 68
    }
}

↑ Top

POST /rest/1/contacts

Creates a new contact

Parameters:
Name Type Data Type Required Description
owner_id form integer The member ID that will be owner of the contact.
owner_username form string The member username that will be owner of the contact.
email form string Email address
first_name form string First name of the contact.
last_name form string Last name of the contact.
additional_name form array Additional names(s) of the contact.
additional_phone form array Additional phone(s) for the contact.
phone form string Telephone number
phone_type form integer Phone Type: 1=Home, 2=Work, 3=Cell, 5=Other
phone_label form string Label for the telephone number
address1 form String Address line 1
address2 form String Address line 2
city form String City
state form String State
state_other form String State if not in standard list
zip form String Zipcode
country form String Country
ad_code form String Promo code. Useful for attaching an identifier on each contact. Often use for advertising tracking.
notes form String Contact notes. Free form text which is added into the notes field of the contact.
viewed form integer Mark the contact as viewed by setting to '1'. The default is '0', not viewed
category_id form integer Yes The contact "folder"
tags form array List of tags to add to the contact
q_and_a form array Question(s) and answer(s)
custom_fields form array Custom Fields - Each entry passed in must have a name, type, and value.
Currently available types are (1=plain text field, 2=checkbox, 3=date field).
social_accounts form array Social Accounts - Each entry passed in must have a type and an account.
Currently available types are (1=Twitter, 2=Facebook, 3=LinkedIn, 4=About Me, 5=Google Profile, 6=Google Plus, 7=Quora, 8=Foursquare, 9=YouTube, 10=Picasa, 11=Plancast, 12=Klout, 13=Flickr).
token form String Vendor token
return_lead_token form String Vendor return_lead_token
lead_id form String Vendor lead_id
order_number form String Vendor order number
lead_vendor_product_name form String Vendor product name
allow_duplicates form String Set to 1 (true) to allow duplicates. Set to 0 (false) to restrict duplicates.
curl "https://www.phoneburner.com/rest/1/contacts/" \
        -X POST \ 
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
        -d '{
                "owner_id":12345678,
                "email":"johnnydemo@fakedomain.com",
                "first_name":"Johnny",
                "last_name":"Demo",
                "address1":"14 Main Street",
                "city":"Los Angeles",
                "state":"CA",
                "zip":"90001",
                "additional_phone":[
                    {"number":"9495551234","phone_type":2,"phone_label":"Spouse's work"},
                    {"number":"9495551235","phone_type":3,"phone_label":"Spouse's cell"}
                ],
                "additional_name":[
                    {"first_name":"Jon","last_name":"Demo"},
                    {"first_name":"John","last_name":"Example"}
                ],
                "q_and_a":{"question":["Question1","Question2"],"answer":["Answer1","Answer2"]},
                "custom_fields":[
                    {"name":"Age Range","type":1,"value":"25-34"},
                    {"name":"Tried Product","type":2,"value":"yes"}
                ],
                "tags": [
                    "Tag Name 1",
                    "Tag Name 2",
                    "Tag Name 3"
                ],
                "phone":"9495551000",
                "phone_type":1,
                "phone_label":"Any label",
                "lead_id":3734,
                "category_id":"13186",
                "notes":"Add some notes to this contact."
            }'


{
    "http_status": 201,
    "status": "success",
    "contacts":
    {
        "contacts":
        {
            "user_id": "30919347",
            "first_name": "Johnny",
            "last_name": "Demo",
            "email_address": "johnnydemo@fakedomain.com",
            "phone": "9495551000",
            "phone_label": "Any label",
            "date_added": "2014-10-20 14:38:42",
            "notes": null
        },
        "additional_messages": true,
        "total_results": 1,
        "page": 1,
        "page_size": 1,
        "total_pages": 1
    }
}
↑ Top

GET /rest/1/contacts/{contact_id}

Retrieves a specific contact

Parameters:
Name Type Data Type Required Description
contact_id path String Yes contact_id
sort_order query string Default is 'DESC'. 'ASC' for oldest first
page_size query string number of results to fetch. default is 25. 1...100 is valid
page query string page number to fetch. default is 1.
↑ Top

DELETE /rest/1/contacts/{contact_id}

Deletes a contact

Parameters:
Name Type Data Type Required Description
contact_id path String Yes contact_id
permanent query Integer By default, deleting just puts the contact in the trash. However, if permanent is set to 1, the contact will be permanently deleted. Use with caution.
↑ Top

PUT /rest/1/contacts/{contact_id}

Updates a contact

Parameters:
Name Type Data Type Required Description
contact_id path String Yes contact_id
email form string Email address
first_name form string First name of the contact.
last_name form string Last name of the contact.
additional_name form array Additional names(s) of the contact.
additional_phone form array Additional phone(s) for the contact.
phone form string Telephone number
phone_type form integer Phone Type: 1=Home, 2=Work, 3=Cell, 5=Other
phone_label form string Label for the telephone number
address1 form String Address line 1
address2 form String Address line 2
city form String City
state form String State
state_other form String State if not in standard list
zip form String Zipcode
country form String Country
ad_code form String Promo code. Useful for attaching an identifier on each contact. Often use for advertising tracking.
notes form String Contact notes. Free form text which is added into the notes field of the contact.
viewed form integer Mark the contact as viewed by setting to '1'. The default is '0', not viewed
category_id form integer The contact "folder"
tags form array List of tags to add to the contact
q_and_a form array Question(s) and answer(s)
custom_fields form array Custom Fields - Each entry passed in must have a name, type, and value.
Currently available types are (1=plain text field, 2=checkbox, 3=date field).
social_accounts form array Social Accounts - Each entry passed in must have a type and an account.
Currently available types are (1=Twitter, 2=Facebook, 3=LinkedIn, 4=About Me, 5=Google Profile, 6=Google Plus, 7=Quora, 8=Foursquare, 9=YouTube, 10=Picasa, 11=Plancast, 12=Klout, 13=Flickr).
token form String Vendor token
return_lead_token form String Vendor return_lead_token
lead_id form String Vendor lead_id
order_number form String Vendor order number
lead_vendor_product_name form String Vendor product name
transfer_to_user_id form integer Only available in the PUT endpoint. This will transfer the contact to another member while {id} is transfer_to_user_id.
↑ Top

content

CM Content


GET /rest/1/content

Get current content

Parameters:
Name Type Data Type Required Description
type query Yes Must be one of (onetouch, script, aac_email, add_appt_email, wmw_invitation, affiliate_invitation)
list query Yes Must be one of (user, system, both)
curl "https://www.phoneburner.com/rest/1/content?type=onetouch&list=both" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"
    
        {
            "http_status": 200,
            "status": "success",
            "content": {
                "emails": [
                    {
                        "cm_content_id": "1234",
                        "display_name": "System message",
                        "description": "This is an email shared from the master account",
                        "message_id": "4046217",
                        "display_order": "0",
                        "system_message": 1
                    },
                    {
                        "cm_content_id": "23295",
                        "display_name": "User generated message",
                        "description": "This message was created by the user",
                        "message_id": "4046239",
                        "display_order": "0",
                        "system_message": 0
                    }
                ]
            }
        }
    
↑ Top

dialsession

Retrieve and create dial-sessions


GET /rest/1/dialsession/{dialsession_id}

Get the details of a specific dial session. Paging for this route is used to limit the number of calls returned.

Parameters:
Name Type Data Type Required Description
dialsession_id path integer Yes The dialsession_id of the dial session to retrieve.
page query integer The page number of calls to be returned.
page_size query integer The page size of calls you wish to be returned.

To get a list of your dial-sessions.

curl "https://www.phoneburner.com/rest/1/dialsession/70951" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

{
    "http_status": 200,
    "status": "success",
    "dialsessions":
    {
        "page": 1,
        "page_size": 25,
        "total_pages": 1,
        "total_results": 2,
        "dialsessions":
        {
            "dialsession_id": "70951",
            "callerid": "9495551234",
            "start_when": "2014-08-06 10:59:53",
            "end_when": "2014-08-06 11:02:09",
            "connected_when": "2014-08-06 11:01:01",
            "disconnected_when": "2014-08-06 11:02:09",
            "call_count": 2,
            "calls":
            [

                {
                    "call_id": "1767709",
                    "phone": "9495551212",
                    "start_when": "2014-08-06 11:01:37",
                    "end_when": "2014-08-06 11:01:49",
                    "connected": "0",
                    "voicemail": "0",
                    "voicemail_sent": null,
                    "email_sent": null,
                    "email_ok": "0",
                    "hangup_status": null,
                    "message_id": null,
                    "note": "-- Aug 06, 2014 9:01 am - PB - Got a busy signal.",
                    "disposition": "Busy Phone"
                },

                {
                    "call_id": "1767710",
                    "phone": "9495551414",
                    "start_when": "2014-08-06 11:01:50",
                    "end_when": "2014-08-06 11:02:01",
                    "connected": "0",
                    "voicemail": "1",
                    "voicemail_sent": "Basic Voicemail",
                    "email_sent": null,
                    "email_ok": "0",
                    "hangup_status": null,
                    "message_id": null,
                    "note": "-- Aug 06, 2014 9:02 am - PB - Left a message. (Basic Voicemail)",
                    "disposition": "Left Message"
                },
            ]
        }
    }
}

↑ Top

GET /rest/1/dialsession

Get a list of dial sessions. Paging for this route is used to limit the number of dial-sessions returned.

Parameters:
Name Type Data Type Required Description
page query integer The page you wish to request
page_size query integer The page size you wish to be returned
date_start query date Limit by date range, starting on this date.
date_end query date Limit by date range, ending on this date.

This example demonstrates how to fetch a list of 3 dial-sessions. Note that the responses don't provide any details about the calls. Using this list, you can use the /rest/1/dialsession/{dialsession_id} route to request the call details.

curl "https://www.phoneburner.com/rest/1/dialsession?page_size=3&page=1" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

{
    "http_status": 200,
    "status": "success",
    "dialsessions":
    {
        "page": 1,
        "page_size": 3,
        "total_pages": 25,
        "total_results": 75,
        "dialsessions":
        [

            {
                "dialsession_id": "49463",
                "callerid": null,
                "start_when": "2013-11-04 08:16:08",
                "end_when": null,
                "connected_when": null,
                "disconnected_when": null,
                "call_count": 0
            },

            {
                "dialsession_id": "70384",
                "callerid": "9495551234",
                "start_when": "2014-04-30 15:31:03",
                "end_when": "2014-04-30 15:33:29",
                "connected_when": "2014-04-30 15:33:15",
                "disconnected_when": "2014-04-30 15:33:29",
                "call_count": 1
            },

            {
                "dialsession_id": "70385",
                "callerid": "9495551234",
                "start_when": "2014-04-30 15:33:44",
                "end_when": "2014-04-30 15:34:25",
                "connected_when": "2014-04-30 15:34:02",
                "disconnected_when": "2014-04-30 15:34:25",
                "call_count": 1
            }
        ]
    }
}

↑ Top

POST /rest/1/dialsession

Creates a new dialsession

Parameters:
Name Type Data Type Required Description
contacts body array Yes List of contacts, all of the options from the contacts endpoint apply hear
callbacks body array Yes An array of callbacks, currently callbegin and calldone are valid
custom_data body object Yes A key/value set of data that will be returned to your server during the callback phase.

To create a dial-session, set the header Content-Type: application/json and then specify the details inside the body of the message.

When creating a dial-session, pass all the details necessary for the system to setup the calls. In the example below, we're setting up dial-session to call 2 contacts. The details are explained below.

The response from the POST includes a redirect_url which you should use redirect the browser into the dialsession. The URL includes a one-time use SSO key so you won't be asked to login.

curl -X POST "https://www.phoneburner.com/rest/1/dialsession" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
        -H "Content-Type: application/json" \
        -d '{ "contacts": [
                { "first_name": "Johnny",
                  "last_name": "Demo",
                  "phone": "9495551234",
                  "email": "johnnydemo@fakedomain.com",
                  "lead_id": "your_systems_id",
                  "category_id": 12345 },
                { "first_name": "Mary",
                  "last_name": "Doe",
                  "phone": "9495551235",
                  "email": "marydoe@fakedomain.com",
                  "category_id": 12345 }
            ],
            "callbacks": [
                {
                  "callback_type": "api_callbegin",
                  "callback": "http://www.yourwebsite.com/api/callbegin.php"
                },
                {
                  "callback_type": "api_calldone",
                  "callback": "http://www.yourwebsite.com/api/calldone.php"
                }
            ],
            "custom_data": {
                "anykey1" : "anyvalue1",
                "anykey2" : "anyvalue2"
            }
        }'

{
    "http_status": 201,
    "status": "success",
    "dialsessions":
    {
        "redirect_url": "https://www.phoneburner.com/index/sso_key_login?single_sign_on_secret=6a0f4934203948e0727456a2001f07f7&redirect=%2Fphoneburner%2Fapi_begin_dialsession",
        "errors": null,
        "total_results": 0,
        "page": 1,
        "page_size": 0,
        "total_pages": 0
    }
}
contacts

An array of contacts to be called. Each entry of the contacts array can use the same JSON structure as the POST /rest/1/contacts route. The key elements of that structure are listed here, but reference the documentation for the contacts route to learn about additional data that can be included.

KeyDescription
first_name The contact's first name.
last_name The contact's last name.
email The contact's email address.
phone The contact's primary phone number.
category_id A category_id (aka folder_id) from the folders route where the contact should live in the user's contact manager.
callbacks

An array of callbacks that the system will use to notify you of events. Even though this is an array of callbacks. To support new functionality, additional callback types may be added in the future.

KeyDescription
callback_type api_callbegin or api_calldone
callback The full URL of the callback route on your servers.

The "api_callbegin" callback is used to update your system before every phone call. We'll post this data in JSON format as the body of the message. Here is an example of the data that we'll send back to you. Your API should respond with an HTTP status of 200 to indicate that you received the data successfully.

{
    "lead_id": "12345",
    "custom_data": "",  // any data passed in initially
    "ds_id": "12345",   // This is the dial session id
    "call_id": "12345"  // This is the specific call id that is starting
}

The "api_calldone" callback is used to update your system after every phone call. We'll post this data in JSON format as the body of the message. Here is an example of the data that we'll send back to you. Your API should respond with an HTTP status of 200 to indicate that you received the data successfully.

{
    // The dispostion of the call.  This is the disposition value defined by the button they clicked.
    // It can include such values as Voicemail, Interested, Busy Signal, etc.
    "status":"No Answer",

    // The duration of the call in seconds.
    "duration":54,

    //  The call id record in our system.
    "call_id":"1767709",

    //  Set to 1 if the call was a live answer, 0 otherwise.
    "connected":"1",

    "contact":     
        {
            //  The unique contact id from our system.  It can be used in the /rest/1/contacts/{contact_id} route.
            "user_id":"__OUR_UNIQUE_CONTACT_ID__",

            //  The lead_id sent to us when you initiated the dialsession
            "lead_id":"abc123",

            // The phone number that was called
            "phone":"9495551212",

            // The contact's name including any updates the user might have made.
            "first_name":"Colby",
            "last_name":"Flesher",

            // All the contact's phone numbers. If they made changes to any of the numbers 
            // it'll be reflected here.
            "phones":
                [{"number":"9495551212","phone_type":"Home","phone_label":null}],
            "addresses":
                [{"address":"123 Main street", "address_2":"Apt 555", "city":"BIRMINGHAM”, "state":"Alabama”, "zip":"35203"}],
            "notes":"This is all the notes data from the dialer.  It includes all previous notes and new notes they've added."
        }
}
custom_data

A set of key/value pairs to be passed back to your callback URL. These values can be used to attach custom data to this dial-session. These values will be passed back to your callback API routes unmodified.

↑ Top

dialsession/call

Dialsession call data.


GET /rest/1/dialsession/call/{call_id}

Returns call detail

Parameters:
Name Type Data Type Required Description
call_id path integer Yes call id
curl "https://www.phoneburner.com/rest/1/dialsession/call/1766999" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

{
    "http_status": 200,
    "status": "success",
    "call":
    {
        "call":
        {
            "call_id": "1766999",
            "phone": "9495551234",
            "start_when": "2014-06-06 10:39:02",
            "end_when": "2014-06-06 10:39:18",
            "connected": "0",
            "voicemail": "1",
            "voicemail_sent": null,
            "email_sent": null,
            "email_ok": "0",
            "hangup_status": null,
            "message_id": null,
            "note": "-- Jun 06, 2014 8:39 am - PB - There was no answer.",
            "disposition": "No Answer"
        },
        "total_results": 1,
        "page": 1,
        "page_size": 1,
        "total_pages": 1
    }
}

↑ Top

dialsession/settings

Retrieve and update dial-session settings


GET /rest/1/dialsession/settings

Get current dial session settings

For an explanation of the values listed in the response, review the PUT method for this API route.

curl "https://www.phoneburner.com/rest/1/dialsession/settings" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

{
    "http_status": 200,
    "status": "success",
    "settings":
    {
        "settings":
        {
            "dialsecs": "30",
            "ringing": "1",
            "emails": "0",
            "busy": null,
            "badphone": null,
            "noanswer": null,
            "fax": null,
            "voicemail": null,
            "interested": null,
            "notinterested": null,
            "wrongperson": null,
            "calltime_max": "2100",
            "calltime_min": "0800",
            "connectme_preset": "null"
        },
        "total_results": 1,
        "page": 1,
        "page_size": 1,
        "total_pages": 1
    }
}

↑ Top

PUT /rest/1/dialsession/settings

Get current dial session settings

Parameters:
Name Type Data Type Required Description
payload body bodyModel Yes Update dialsession settings

Payload settings:

Key Description Valid settings
dialsec The number of seconds the dialer rings before giving up on the call. Once the max time is reached, the call is dispositioned as a no answer. Greater than 20 seconds
ringing Enable or disable the ringing sound in your headset during the dial-session. When this option is disabled, you will hear silence instead of the ringing sound normally heard when a call is trying to connect. 1 (enabled) or 0 (disabled)
emails Enable or disable email sending during the dial-session. When enabled the emails configured in the busy, badphone, noanswer, fax, voicemail, interested, notintereested and wrongperson fields are sent. 1 (enabled) or 0 (disabled)
busy, badphone, noanswer, fax, voicemail, interested, notinterested, wrongperson Dialing and live answer dispostion email settings. Valid message ids from your message library.
calltime_min, calltime_max Min and max values for times when the dialer is allowed to make calls. Times are relative to the called party's local time - not your local time. For example, if you don't want to call people outside of 9am to 5pm n their local time, set calltime_min=0900 and calltime_max=1700. 0800 to 2100
connectme_preset The ConnectMe feature is an optional service where the system calls your phone to initiate the dial-session. The connectme_preset pre-fills your phone number so you don't have to type it every time. Valid 10-digit phone number

This example demonstrates passing values in the payload to make the dialer ring a maximum of 30 seconds, enable ringing and disable the busy phone email.

curl -X PUT "https://www.phoneburner.com/rest/1/dialsession/settings" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
        -d '{
               "dialsecs": "30",
               "ringing": "1",
               "busy": 0
            }'

{
    "http_status": 200,
    "status": "success",
    "settings":
    {
        "settings":
        {
            "dialsecs": "30",
            "ringing": "1",
            "emails": "0",
            "busy": null,
            "badphone": null,
            "noanswer": null,
            "fax": null,
            "voicemail": null,
            "interested": null,
            "notinterested": null,
            "wrongperson": null,
            "calltime_max": "2100",
            "calltime_min": "0800",
            "connectme_preset": "null"
        },
        "total_results": 1,
        "page": 1,
        "page_size": 1,
        "total_pages": 1
    }
}

↑ Top

dialsession/usage

Dialsession usage data.


GET /rest/1/dialsession/usage

Returns Dialsession usage stats

Parameters:
Name Type Data Type Required Description
date_start query date Yes Limit by date range, starting on this date. Format is YYYY-MM-DD
date_end query date Yes Limit by date range, ending on this date. Limit your date_end value to a max of 90-days after your date_start value otherwise a 403 error is returned. Format is YYYY-MM-DD.

Retrieve dial-session usage summary data for you and everyone on your team. Date range searches are limited to a max of 90-days. The return value includes dialings stats for each person in your team. The key for the stats object is the user_id value returned from the GET /rest/1/members route.

Return values:
Return values are summarized across all dial-sessions during the specified time frame.
Value Description
sessions Total number of unique dial-sessions.
calls Total calls attempted. A call is attempted each time we start calling a phone number.
connected Total conversations that were dispositioned as live calls. To get an accurate stat for live calls, it's important that your disposition buttons are setup to mark a call as a live conversation.
voicemail Total voicemails.
emails Total emails sent.
talktime Total minutes spent on live calls. In the example below, the person had 2 live talks for a total of 30 minutes of talk time.
avg_talktime Average minutes of live talk time across all live calls. In the example below, the person averaged 15 minutes of talk time across their 2 live conversations.

curl "https://www.phoneburner.com/rest/1/dialsession/usage?date_start=2018-04-01&date_end=2018-04-31" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

{
    "http_status": 200,
    "status": "success",
    "usage": {
        "95074688": {
            "sessions": 1,
            "calls": 4,
            "connected": 2,
            "voicemail": 1,
            "emails": 0,
            "talktime": 30,
            "avg_talktime": 15 
        }
    }
}

↑ Top

voicemails

Voicemails


GET /rest/1/voicemails

Get currently available voicemail data. These voicemails can be left for your contacts during a dial session with the click of a button.

curl "https://www.phoneburner.com/rest/1/voicemails" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

{
    "http_status": 200,
    "status": "success",
    "voicemails":
    {
        "voicemails":
        [

            {
                "recording_id": "170999",
                "name": "Basic Voicemail",
                "playback_url": "http://sampledomain.com/pbx/dsrecording/AH-AEE-AAADGFF/170999/x.mp3",
                "created_when": "2013-11-07 10:16:56"
            }
        ],
        "total_results": 1,
        "page": 1,
        "page_size": 1,
        "total_pages": 1
    }
}

↑ Top

folders

Folder information


GET /rest/1/folders

Get a list of contact manager folders.

Parameters:
Name Type Data Type Required Description
structure query string If set to '1', we will return the folders with _embedded data to show the folder structure.
curl "https://www.phoneburner.com/rest/1/folders" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

{
    "http_status": 200,
    "status": "success",
    "folders":
    {
        "0":
        {
            "folder_id": "11888",
            "folder_name": "Folder #1"
        },
        "1":
        {
            "folder_id": "11999",
            "folder_name": "Folder #2"
        },
        "2":
        {
            "folder_id": "11000",
            "folder_name": "Folder #3"
        }
    }
}

curl "https://www.phoneburner.com/rest/1/folders?structure=1" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

{
    "http_status": 200,
    "status": "success",
    "folders":
    {
        "0":
        {
            "id": "11888",
            "folder_id": "11888",
            "folder_name": "Folder #1",
            "description": "A Description",
            "_links": {
                "self": {
                    "href": "rest/1/folders/118888"
                }
            }
        },
        "1":
        {
            "id": "11990",
            "folder_id": "11990",
            "folder_name": "Folder #2",
            "description": "A Description",
            "_links": {
                "self": {
                    "href": "rest/1/folders/11990"
                }
            }
            "_embedded": {
                "folders": [
                    {
                        "id": "11991",
                        "folder_id": "11991",
                        "folder_name": "Sub Folder #2 - 1",
                        "description": "A Description",
                        "_links": {
                            "self": {
                                "href": "rest/1/folders/11991"
                            }
                        }
                    },
                    {
                        "id": "11992",
                        "folder_id": "11992",
                        "folder_name": "Sub Folder #2 - 2",
                        "description": "A Description",
                        "_links": {
                            "self": {
                                "href": "rest/1/folders/11992"
                            }
                        }
                    }
                ]
            }
        }
    }
}

↑ Top

POST /rest/1/folders

Create a new folder.

Parameters:
Name Type Data Type Required Description
name body string Yes Name of the new folder
description body string Description of this folder.
parent_id body int Parent ID. This allows to create sub folders. Currently limited to 1 layer of subfolders.
curl -X POST "https://www.phoneburner.com/rest/1/folders" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \

        -d '{
    "name": "Folder #1",
    "description": "My Description",
    "parent_id": 132022
}'

{
    "http_status": 200,
    "status": "success",
    "folders":
    {
        "0":
        {
            "folder_id": "11888",
            "folder_name": "Folder #1"
        }
    }
}

↑ Top

PUT /rest/1/folders/{folder_id}

Update a folder's details.

Parameters:
Name Type Data Type Required Description
folder_id path string Yes Specify which folder to update
name body string Name of the new folder
description body string Description of this folder.
parent_id body int Parent ID. This allows to create sub folders. Currently limited to 1 layer of subfolders.
curl -X PUT "https://www.phoneburner.com/rest/1/folders/132022" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \

        -d '{
    "name": "Folder #2",
    "description": "My Description",
    "parent_id": 0
}'

{
    "http_status": 200,
    "status": "success",
    "folders":
    {
        "0":
        {
            "folder_id": "132022",
            "folder_name": "Folder #2"
        }
    }
}

↑ Top

DELETE /rest/1/folders/{folder_id}

Delete a folder.

Parameters:
Name Type Data Type Required Description
folder_id path string Yes Specify which folder to delete
move_folder_id query integer If a folder has contacts, move them to this folder first.
curl -X POST "https://www.phoneburner.com/rest/1/folders/132022?move_folder_id=0" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"


204 No Content

↑ Top

members

Create and retrieve members.


GET /rest/1/members/{user_id}

Retrieves a member

Parameters:
Name Type Data Type Required Description
user_id path integer The user_id of the member to retrieve. If you are fetching your own member information, remove the user_id.

The API supports vendor access for retrieving multiple member accounts, so member data is sent back in an array of member objects.

curl "https://www.phoneburner.com/rest/1/members/" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

{
        "http_status": 200,
        "status": "success",
        "members":
        {
                "total_results": 1,
                "members":
                [

                        {
                                "user_id": "1234567",
                                "username": "",
                                "first_name": "Saul",
                                "last_name": "Goodman",
                                "email_address": "callsaul@bettercallsaul.com",
                                "date_added": "2013-01-17 17:12:13",
                                "phone": "9492181234",
                                "display_name": "Standard Account",
                                "billing_item_id": "131",
                                "subscription_status": "1",
                                "oauth": {
                                    "bearer_token": "examplenEnTQoSx8sWmLBtbrhcgp8sReWxIvITGN"
                                }
                        }
                ],
                "page": 1,
                "page_size": 1,
                "total_pages": 1
        }
#! /usr/bin/php
<?php
$results = `curl -s -k "https://www.phoneburner.com/rest/1/members/" \
                 -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"`;
$data = json_decode($results);
$member = $data->members->members[0];
print "First Name: {$member->first_name}\n";

↑ Top

PUT /rest/1/members/{user_id}

Updates member fields

Parameters:
Name Type Data Type Required Description
payload body UpdatableMembersModel Yes Payload of fields to update
user_id path integer The user_id of the member to retrieve. If you are fetching your own member information, remove the user_id.

The API supports vendor access for modifying the following member account details: first_name, last_name, email_address, username, phone These can be sent in the body in the form first_name=foo&last_name=bar or as a JSON object:


    {
        "first_name": "foo",
        "last_name": "bar"
    }

curl "https://www.phoneburner.com/rest/1/members/25381104" \
        -X PUT \ 
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
        -d 'first_name=johnny5'

{
        "http_status": 200,
        "status": "success",
        "members": {
            "members": {
                "user_id": "25381104",
                "username": "gumby",
                "first_name": "johnny5",
                "last_name": "",
                "email_address": "gumby@networxonline.com",
                "date_added": "2014-09-22 14:51:38",
                "phone": null,
                "display_name": "7.5 Hour Account",
                "billing_item_id": "183",
                "subscription_status": "1",
                "oauth": {
                    "bearer_token": "examplenEnTQoSx8sWmLBtbrhcgp8sReWxIvITGN"
                }
            },
            "total_results": 1,
            "page": 1,
            "page_size": 1,
            "total_pages": 1
        }
}
#! /usr/bin/php
<?php
$results = `curl -s -k "https://www.phoneburner.com/rest/1/members/25381104" \
                 -X PUT \ 
                 -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
                 -d 'first_name=johnny5'";
$data = json_decode($results);
$member = $data->members->members[0];
print "Hello : {$member->username}\n";  //Hello : johnny5

↑ Top

DELETE /rest/1/members/{user_id}

Note: This operation requires vendor level access.
Deletes a member

Parameters:
Name Type Data Type Required Description
user_id path integer Yes The User Id of the member you wish to delete

The API supports vendor access for deleting member accounts. Note: Because a successful response will return 204 (no-content), there will be nothing output from curl. You can output the header with --head or output only the HTTP status code by adding: --output /dev/null --silent --head --write-out '%{http_code}\n';

curl "https://www.phoneburner.com/rest/1/members/25381104" \
        -X DELETE \ 
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
         --output /dev/null --silent --head --write-out '%{http_code}\n';
204
#! /usr/bin/php
<?php
$results = `curl -s -k "https://www.phoneburner.com/rest/1/members/25381104 \
        -X DELETE \ 
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \ 
         --output /dev/null --silent --head --write-out '%{http_code}\n';
var_dump( $results ); //204 on successful deletion

↑ Top

POST /rest/1/members

Note: This operation requires vendor level access.
Creates a new member

Parameters:
Name Type Data Type Required Description
username form string Yes Username for the member. This is what they will login with.
password form string Yes Must be > 4 characters
first_name form integer Yes First name of the user.
last_name form string Last name of the user.
email form string Yes Email address
phone form string Telephone number
billing_item_id form integer Yes Their account level. You must request a custom value for this.
billing_group_id form string Yes Required billing field. You must request a custom value for this.
subgroup_id form string Yes Puts them in the right bucket of users. You must request a custom value for this.
event form string Fires the event upon successful user creation.

The API supports vendor access for creating member accounts.

curl "https://www.phoneburner.com/rest/1/members/" \
        -X POST \ 
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
        -d 'username=gumby&password=abcdef&first_name=foobar&email=gumby%40networxonline.com&billing_item_id=183&billing_group_id=63&subgroup_id=1243'

{
        "http_status": 201,
        "status": "success",
        "members": {
            "members": {
                "user_id": "25381104",
                "username": "gumby",
                "first_name": "foobar",
                "last_name": "",
                "email_address": "gumby@networxonline.com",
                "date_added": "2014-09-22 14:51:38",
                "phone": null,
                "display_name": "7.5 Hour Account",
                "billing_item_id": "183",
                "subscription_status": "1",
                "oauth": {
                    "bearer_token": "examplenEnTQoSx8sWmLBtbrhcgp8sReWxIvITGN"
                }
            },
            "total_results": 1,
            "page": 1,
            "page_size": 1,
            "total_pages": 1
        }
}
#! /usr/bin/php
<?php
$results = `curl -s -k "https://www.phoneburner.com/rest/1/members/" \
                 -X POST \ 
                 -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
                 -d 'username=gumby&password=abcdef&first_name=foobar&email=gumby%40networxonline.com&billing_item_id=183&billing_group_id=63&subgroup_id=1243'";
$data = json_decode($results);
$member = $data->members->members[0];
print "Hello : {$member->username}\n"; //Hello : foobar

↑ Top

content

Get available scripts and emails used throughout the system.


GET /rest/1/content

Get current content

Parameters:
Name Type Data Type Required Description
type query Yes Must be one of (onetouch, script, aac_email, add_appt_email, wmw_invitation, affiliate_invitation)
list query Yes Must be one of (user, system, both)
curl "https://www.phoneburner.com/rest/1/content?type=onetouch&list=both" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"
    
        {
            "http_status": 200,
            "status": "success",
            "content": {
                "emails": [
                    {
                        "cm_content_id": "1234",
                        "display_name": "System message",
                        "description": "This is an email shared from the master account",
                        "message_id": "4046217",
                        "display_order": "0",
                        "system_message": 1
                    },
                    {
                        "cm_content_id": "23295",
                        "display_name": "User generated message",
                        "description": "This message was created by the user",
                        "message_id": "4046239",
                        "display_order": "0",
                        "system_message": 0
                    }
                ]
            }
        }
    
↑ Top

customfields

Get, Create, Update, and Delete custom fields for a member.


GET /rest/1/customfields

Get a list of custom fields.

curl "https://www.phoneburner.com/rest/1/customfields?page_size=1&page=1" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
        -d '{
    "http_status": 200,
    "status": "success",
    "customfields": {
        "customfields": [
            {
                "custom_field_id": "215",
                "display_name": "My custom field",
                "type_id": "1",
                "type_name": "Text Field",
                "display_order": "0",
                "_link": {
                    "self": {
                        "href": "rest/1/customfields/215"
                    }
                }
            }
        ],
        "page_size": 1,
        "total_results": "1",
        "page": 1,
        "total_pages": 1
    }
}'

↑ Top

POST /rest/1/customfields

Create a new custom field.

Parameters:
Name Type Data Type Required Description
display_name form string Yes The custom field text that is displayed in the UI.
display_order form string The order that this custom field is displayed in the UI.
type form integer Yes The custom field type, currently that is display in the UI.
curl "https://www.phoneburner.com/rest/1/customfields" \
    -X POST \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \ 
    -d '{
    "display_name": "Test field 1",
    "type": 1,
    "display_order": 5
    }'

↑ Top

GET /rest/1/customfields/{custom_field_id}

Get a list of custom fields.

curl "https://www.phoneburner.com/rest/1/customfields/{custom_field_id}" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
        -d '{
    "http_status": 200,
    "status": "success",
    "customfields": {
        "customfields": [
            {
                "custom_field_id": "215",
                "display_name": "My custom field",
                "type_id": "1",
                "type_name": "Text Field",
                "display_order": "0",
                "_link": {
                    "self": {
                        "href": "rest/1/customfields/215"
                    }
                }
            }
        ]
    }
}'

↑ Top

PUT /rest/1/customfields/{custom_field_id}

Create a new custom field.

Parameters:
Name Type Data Type Required Description
display_name form string The custom field text that is displayed in the UI.
display_order form string The order that this custom field is displayed in the UI.
type form integer The custom field type, currently that is display in the UI.
curl "https://www.phoneburner.com/rest/1/customfields/{custom_field_id}" \
    -X PUT
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"
    -d '{
  "display_name": "Updating",
  "display_order": 4,
  "type": 2
}'

↑ Top

DELETE /rest/1/customfields/{custom_field_id}

Remove a custom field value from a contact.

curl "https://www.phoneburner.com/rest/1/customfields/{custom_field_id}" \
    -X DELETE \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"
↑ Top

contacts/customfields

Get, Add, Update, and Delete custom fields for a contact.


GET /rest/1/contacts/{contact_id}/customfields

Get a list of custom fields.

curl "https://www.phoneburner.com/rest/1/customfields?page_size=1&page=1" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"


{
    "http_status": 200,
    "status": "success",
    "customfields": {
        "customfields": [
            {
                "custom_field_id": "77981",
                "display_name": "Example Text",
                "type_id": "1",
                "type_name": "Text Field",
                "display_order": "0",
                "value": "Example",
                "_link": {
                    "self": {
                        "href": "rest/1/customfields/{contact_id}/customfields/77981"
                    }
                }
            },
            {
                "custom_field_id": "34377",
                "display_name": "Example Check Box",
                "type_id": "2",
                "type_name": "Check Box",
                "display_order": "1",
                "value": null,
                "_link": {
                    "self": {
                        "href": "rest/1/customfields/{contact_id}/customfields/34377"
                    }
                }
            }
        ],
        "page_size": 1,
        "total_results": "1",
        "page": 1,
        "total_pages": 1
    }
}

↑ Top

GET /rest/1/contacts/{contact_id}/customfields/{custom_field_id}

Get a specific custom field from a contact.

curl "https://www.phoneburner.com/rest/1/customfields/{custom_field_id}" \
        -H "Authorization: Bearer {$auth_code}"

{
    "_link": {
        "self": {
            "href": "/rest/1/contacts/106556132/customfields/34377"
        }
    },
    "http_status": 200,
    "status": "success",
    "customfields": {
        "customfields": [
            {
                "custom_field_id": "34377",
                "display_name": "Example",
                "type_id": "2",
                "type_name": "Check Box",
                "display_order": "1",
                "value": null
            }
        ]
    }
}

↑ Top

POST /rest/1/contacts/{contact_id}/customfields/{custom_field_id}

Add a custom field to a contact.

Parameters:
Name Type Data Type Required Description
display_name form string Yes The custom field text that is displayed in the UI.
display_order form string The order that this custom field is displayed in the UI.
type form integer Yes The custom field type, currently that is display in the UI.
curl "https://www.phoneburner.com/rest/1/customfields/{custom_field_id}" \
    -X POST
    -H "Authorization: Bearer {bearer}"
    -d '{
  "Value": "New Value"
}'


{
    "http_status": 200,
    "status": "success",
    "customfields": {
        "customfields": [
            {
                "custom_field_id": "77981",
                "display_name": "Example Text",
                "type_id": "1",
                "type_name": "Text Field",
                "display_order": "0",
                "value": "Updated value"
            }
        ]
    }
}

    
↑ Top

PUT /rest/1/contacts/{contact_id}/customfields/{custom_field_id}

Update the contents of a custom field on a contact.

Parameters:
Name Type Data Type Required Description
display_name form string The custom field text that is displayed in the UI.
display_order form string The order that this custom field is displayed in the UI.
type form integer The custom field type, currently that is display in the UI.
curl "https://www.phoneburner.com/rest/1/customfields/{custom_field_id}" \
    -X PUT
    -H "Authorization: Bearer {bearer}"
    -d '{
  "value": "New Value"
}'


{
    "http_status": 200,
    "status": "success",
    "customfields": {
        "customfields": [
            {
            "custom_field_id": "77981",
            "display_name": "Example Text",
            "type_id": "1",
            "type_name": "Text Field",
            "display_order": "0",
            "value": "Updated value"
            }
        ]
    }
}

    
↑ Top

DELETE /rest/1/contacts/{contact_id}/customfields/{custom_field_id}

Remove the contents of a custom field from a contact.

curl "https://www.phoneburner.com/rest/1/customfields/{custom_field_id}" \
    -X DELETE \
    -H "Authorization: Bearer {bearer}" \

↑ Top

contacts/auditlog

Get the audit log of changes on a contact.


GET /rest/1/contacts/{contact_id}/auditlog

Retrieves the audit log for contact.

Parameters:
Name Type Data Type Required Description
contact_id path integer Yes The contact_id
curl "https://www.phoneburner.com/rest/1/contacts/{contact_id}/auditlog?page_size=1&page=1" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

    +{
    "http_status": 200,
    "status": "success",
    "contact_activities": {
        "contact_activities": [
            {
                "contact_id": "106558881",
                "member_id": "106556250",
                "action": "update",
                "data_type": "moved",
                "old": "131941",
                "new": "13186",
                "date_added": "2016-02-22 18:24:34"
            }
        ],
        "page_size": 1,
        "total_results": "68",
        "page": 1,
        "total_pages": 68
    }
}

↑ Top

contacts/activities

Get activities by contact for past X days.


GET /rest/1/contacts/{contact_id}/activities

Retrieves all activities for contact. The user_activitity_id is a unique key per activitiy. The activitiy_id is a type of activity.

Parameters:
Name Type Data Type Required Description
days path integer Yes Past X days of data to retrieve, up to 6 months.
contact_id path integer Yes The contact_id
curl "https://www.phoneburner.com/rest/1/contacts/{contact_id}/activities?days=7&page_size=1&page=1" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

{
    "http_status": 200,
    "status": "success",
    "contact_activities": {
        "contact_activities": [
            {
                "user_activity_id": "41",
                "activity_id": "41",
                "activity": "Called a Prospect",
                "date": "2016-02-17 17:13:47"
            }
        ],
        "page_size": 1,
        "total_results": "68",
        "page": 1,
        "total_pages": 68
    }
}

↑ Top