contacts contacts/activities contacts/auditlog contacts/customfields contacts/emails contacts/phones contacts/tags content customfields dialsession dialsession/call dialsession/settings dialsession/usage folders members tags voicemails phonenumber

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":
    {
        "member_user_id": "13514766",
        "contacts":
        [

            {
                "contact_user_id": "30919237",
                "owner_id": "13514766",
                "first_name": "John",
                "last_name": "Demo",
                "date_added": "2023-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": "[email protected]",
                    "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"
                    }
                ],
                "external_crm_data": [
                    {
                        "crm_id": "123",
                        "crm_name": "SalesForce"
                    }
                ]
            }
        ],
        "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.
source_id form integer The lead source ID. Must belong to owner_id or one of the members of the team.
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 The contact "folder"
tags form array List of tags to add to the contact
question form array Question(s) - An array of questions. Each question must have a corresponding answer provided via. the `answer` key.
answer form array Answer(s) - An array of answers. Each question must have a corresponding question provided via. the `question` key
custom_fields form array Custom Fields - Each entry passed in must have a name, type, and value.
Currently available field types are (1=plain text, 2=checkbox, 3=date, 6=drop down, 7=numeric).
Note: When using a dropdown field the value must be an integer and be one of the option ids for that field. Those option ids can be found by fetching all the custom field data through the custom fields endpoint
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
rating form integer The star rating for a contact. Valid range: whole numbers between 1 and 5
duplicate_checks form object A list of checks, default is "duplicate_checks": { "email": true, "phone": true }
on_duplicate form String Can be set to "skip", default is "update"
duplicate_scrubbing_policy form String Set to 0 (default) to scrub duplicates from your account only. Set to 1 scrub against your contacts in your team (and downstream teams). Set to 2 to scrub against contacts in your entire organization.
allow_duplicates form integer Explicitly allow duplicate contact and bypass other duplicate checks
config form array Configuration values for import. 
curl "https://www.phoneburner.com/rest/1/contacts/" \
        -X POST \ 
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
        -d '{
                "owner_id":12345678,
                "email":"[email protected]",
                "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"}
                ],
                "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.",
                "config": {
                    "import_dnc": 2
                }
            }'

Response shape:

{
    "http_status": 201,
    "status": "success",
    "contacts":
    {
        "contacts":
        {
            "contact_user_id": "30919347",
            "first_name": "Johnny",
            "last_name": "Demo",
            "email_address": "[email protected]",
            "phone": "9495551000",
            "phone_label": "Any label",
            "date_added": "2023-10-20 14:38:42",
            "notes": null
        },
        "additional_messages": true,
        "total_results": 1,
        "page": 1,
        "page_size": 1,
        "total_pages": 1
    }
}
↑ Top

DELETE /rest/1/contacts

Deletes a list contacts. A successful response is '204 No Content'.

Parameters:
Name Type Data Type Required Description
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.
contact_user_ids body array Yes An array of contacts to remove. 
curl "https://www.phoneburner.com/rest/1/contacts/" \
        -X DELETE \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
        -d '{
                "contact_user_ids": [
                    404531653,
                    404531652
                ]
            }'
↑ 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
question form array Question(s) - An array of questions. Each question must have a corresponding answer provided via. the `answer` key.
answer form array Answer(s) - An array of answers. Each question must have a corresponding question provided via. the `question` key
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, 7=numeric).
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.
rating form integer The star rating for a contact. Valid range: whole numbers between 1 and 5
↑ 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

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/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 m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

{
    "_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 value to a contact. If the custom field is a dropdown, the value will attempt to match an existing option. If it does not match an existing option, a new dropdown option will be added.

Parameters:
Name Type Data Type Required Description
value form string Yes The custom field value. 
curl "https://www.phoneburner.com/rest/1/customfields/{custom_field_id}" \
    -X POST
    -H "Authorization: Bearer {bearer}"
    -d '{
  "value": "New Value"
}'

Response shape:

{
    "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 value of a custom field on a contact. If the custom field is a dropdown, the value will attempt to match an existing option. If it does not match an existing option, a new dropdown option will be added.

Parameters:
Name Type Data Type Required Description
value form string Yes The custom field value. 
curl "https://www.phoneburner.com/rest/1/customfields/{custom_field_id}" \
    -X PUT
    -H "Authorization: Bearer {bearer}"
    -d '{
  "value": "New Value"
}'

Response shape:

{
    "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 m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
↑ Top

contacts/emails

Manage e-mail addresses for a contact.

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

Get a list of email addresses. 

curl "https://www.phoneburner.com/rest/1/contact/{contact_id}/emails" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

Response shape

{
    "_link": {
        "self": {
            "href": "/rest/1/contacts/382390387/emails"
        }
    },
    "_links": {
        "self": {
            "href": "/rest/1/contacts/382390387/emails"
        }
    },
    "http_status": 200,
    "status": "success",
    "emails": {
        "emails": [
            {
                "id": 120954818,
                "email_address": "[email protected]",
                "is_primary": true
            }
        ],
        "total_results": 1,
        "page": 1,
        "page_size": 1,
        "total_pages": 1
    }
}
↑ Top

POST /rest/1/contacts/{contact_id}/emails

Add an e-mail address to a contact.

Parameters:
Name Type Data Type Required Description
email_address form string Yes Email address: [email protected]
is_primary form boolean Yes Make this e-mail address the primary 
curl "https://www.phoneburner.com/rest/1/contacts/{contact_id}/emails" \
    -X POST \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
-d '{
    "email_address": "Test field 1",
    "is_primary": true
    }'

Response shape:

{
    "_links": {
        "self": {
            "href": "/rest/1/contacts/382390388/emails"
        }
    },
    "http_status": 202,
    "status": "success",
    "email": {
        "id": 120954825,
        "email_address": "[email protected]",
        "is_primary": true
    }
}
↑ Top

PUT /rest/1/contacts/{contact_id}/emails

Bulk update all email addresses associated with a contact.

Parameters:
Name Type Data Type Required Description
emails form array Yes [ { "email": "[email protected]", "is_primary": false} ] 
curl "https://www.phoneburner.com/rest/1/contacts/{contact_id}/emails" \
    -X POST \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
-d '{
"emails": [
	{
	    "email_address": "[email protected]",
	    "is_primary": true

	},
	{
		"email_address": "[email protected]",
		"is_primary": false
	}
	]
}'

Response shape:

{
    "_links": {
        "self": {
            "href": "/rest/1/contacts/382391754/emails"
        }
    },
    "http_status": 202,
    "status": "success",
    "emails": [
        {
            "id": "120956183",
            "email_address": "[email protected]",
            "is_primary": 1
        },
        {
            "id": "120956182",
            "email_address": "[email protected]",
            "is_primary": false
        }
    ]
}
↑ Top

GET /rest/1/contacts/{contact_id}/emails/{email_id}

Get a specific email from a contact. 

curl "https://www.phoneburner.com/rest/1/contacts/{contact_id}/emails/{email_id}" \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

Response shape

{
    "_link": {
        "self": {
            "href": "/rest/1/contacts/382390387/emails/120954818"
        }
    },
    "_links": {
        "self": {
            "href": "/rest/1/contacts/382390387/emails/120954818"
        }
    },
    "http_status": 200,
    "status": "success",
    "email": {
        "id": 120954818,
        "email_address": "[email protected]",
        "is_primary": true
    }
}
↑ Top

PUT /rest/1/contacts/{contact_id}/emails/{email_id}

Update an e-mail address on a contact.

Parameters:
Name Type Data Type Required Description
email_address form string Yes Email address: [email protected]
is_primary form boolean Yes Make this e-mail address the primary 
curl "https://www.phoneburner.com/rest/1/contacts/{contact_id}/{email_id}" \
    -X PUT
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"
    -d '{
  "value": "New Value"
}'

Response shape:

{
    "_links": {
        "self": {
            "href": "/rest/1/contacts/382390388/emails/120954825"
        }
    },
    "http_status": 202,
    "status": "success",
    "email": {
        "id": 120954825,
        "email_address": "[email protected]",
        "is_primary": true
    }
}
↑ Top

DELETE /rest/1/contacts/{contact_id}/emails/{email_id}

Remove the e-mail address from a contact. 

curl "https://www.phoneburner.com/rest/1/contacts/{contact_id}/emails/{email_id}" \
        -X DELETE \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \

Response:

HTTP Status code 204 (no content) with an empty body. ↑ Top

contacts/phones

Get, Create, Update, and Delete phones for a member.

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

Get a list of phones. 

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

Response shape:

{
    "_link": {
        "self": {
            "href": "/rest/1/contacts/382390388/phones"
        }
    },
    "_links": {
        "self": {
            "href": "/rest/1/contacts/382390388/phones"
        }
    },
    "http_status": 200,
    "status": "success",
    "phones": {
        "phones": [
            {
                "id": 223987053,
                "type": 1,
                "phone_number": "716-293-9978",
                "label": "An updated title",
                "is_primary": true
            }
        ],
        "total_results": 1,
        "page": 1,
        "page_size": 1,
        "total_pages": 1
    }
}
↑ Top

POST /rest/1/contacts/{contact_id}/phones

Add a phone to a contact.

Parameters:
Name Type Data Type Required Description
phone_number form string Yes The phone number. Unformatted: 12061234567
type form integer Yes Default is 1. Valid options: HOME = 1; WORK = 2; CELL = 3; FAX = 4; OTHER = 5;
label form string A human friendly label to give the phone. 
curl "https://www.phoneburner.com/rest/1/contact/{contact_id}/phones" \
    -X POST \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
    -d '{"phone_number": 2063728000,"label": "Example Cell","is_primary" : false,"type": 3}'

Response shape:

{
    "_link": {
        "self": {
            "href": "/rest/1/contacts/382390392/phones/223987058"
        }
    },
    "_links": {
        "self": {
            "href": "/rest/1/contacts/382390392/phones/223987058"
        }
    },
    "http_status": 200,
    "status": "success",
    "phone": {
        "id": 223987058,
        "type": "3",
        "phone_number": "4251234567",
        "label": "fake",
        "is_primary": true
    }
}
↑ Top

PUT /rest/1/contacts/{contact_id}/phones

Add a phone to a contact.

Parameters:
Name Type Data Type Required Description
phones form array Yes An array of phone objects. Format: {"phone_number": string, "is_primary": bool, "type": integer: HOME = 1; WORK = 2; CELL = 3; FAX = 4; OTHER = 5;} 
curl "https://www.phoneburner.com/rest/1/contacts/{contact_id}/phones" \
    -X POST \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
-d '{
"phones": [
	{
	    "phone_number": "1234567890",
	    "is_primary": true,
	    "type": 1

	},
	{
		"phone_number": "1234567891",
		"is_primary": false,
		"type": 5
	}
	]
}'

Response shape:

{
    "_links": {
        "self": {
            "href": "/rest/1/contacts/382391754/phones"
        }
    },
    "http_status": 202,
    "status": "success",
    "phones": [
        {
            "phone_number": "1234567890",
            "is_primary": true,
            "type": 0
        },
        {
            "phone_number": "1234567891",
            "is_primary": false,
            "type": 1
        }
    ]
}
↑ Top

GET /rest/1/contacts/{contact_id}/phones/{phone_id}

Get a specific phone from a contact. 

curl "https://www.phoneburner.com/rest/1/contacts/{contact_id}/phones/{phone_id}" \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

Response shape:

{
    "_link": {
        "self": {
            "href": "/rest/1/contacts/382390392/phones/223987058"
        }
    },
    "_links": {
        "self": {
            "href": "/rest/1/contacts/382390392/phones/223987058"
        }
    },
    "http_status": 200,
    "status": "success",
    "phone": {
        "id": 223987058,
        "type": "3",
        "phone_number": "4251234567",
        "label": "fake",
        "is_primary": true
    }
}
↑ Top

PUT /rest/1/contacts/{contact_id}/phones/{phone_id}

Update the contents of a phone on a contact.

Parameters:
Name Type Data Type Required Description
phone_number form string Yes The phone number. Unformatted: 12061234567
type form integer Yes Default is 1. Valid options: HOME = 1; WORK = 2; CELL = 3; FAX = 4; OTHER = 5;
label form string A human friendly label to give the phone. 
curl "https://www.phoneburner.com/rest/1/phones/{phone_id}" \
    -X PUT \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
    -d '{"phone_number": "14251234567","label": "Daytime Cell","is_primary" : false,"type": 3}'

Response shape:

{
    "_links": {
        "self": {
            "href": "/rest/1/contacts/382390388/phones/223987053"
        }
    },
    "http_status": 202,
    "status": "success",
    "phone": {
        "id": 223987053,
        "type": 1,
        "phone_number": "716-293-9978",
        "label": "An updated title",
        "is_primary": true
    }
}
↑ Top

DELETE /rest/1/contacts/{contact_id}/phones/{phone_id}

Remove the phone from a contact. 

curl "https://www.phoneburner.com/rest/1/phones/{phone_id}" \
    -X DELETE \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

Response shape

An empty body with an HTTP Status code of 204 (no content).

↑ Top

contacts/tags

Manage tags by contact

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

Get a list of tags. 

curl "https://www.phoneburner.com/rest/1/contacts/{contact_id}/tags" \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

Response shape:

{
    "_link": {
        "self": {
            "href": "/rest/1/contacts/382390387/tags"
        }
    },
    "_links": {
        "self": {
            "href": "/rest/1/contacts/382390387/tags"
        }
    },
    "http_status": 200,
    "status": "success",
    "tags": {
        "tags": [
            {
                "id": 4406098,
                "title": "SampleTag"
            }
        ],
        "total_results": 1,
        "page": 1,
        "page_size": 1,
        "total_pages": 1
    }
}
↑ Top

POST /rest/1/contacts/{contact_id}/tags

Add a tag to a contact.

Parameters:
Name Type Data Type Required Description
title form string Yes The title of the tag that will be displayed 
curl "https://www.phoneburner.com/rest/1/contact/{contact_id}/tags" \
    -X POST \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
    -d '{"title": "Your tag title goes here"}'

Response shape:

{
    "_links": {
        "self": {
            "href": "/rest/1/contact/382390387/tags/4406099"
        }
    },
    "http_status": 202,
    "status": "success",
    "tag": {
        "id": 4406099,
        "title": "Sample Tag"
    }
}
↑ Top

GET /rest/1/contacts/{contact_id}/tags/{tag_id}

Get a specific tag from a contact. 

curl "https://www.phoneburner.com/rest/1/contacts/{contact_id}/tags/{tag_id}" \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

Response shape:

{
    "_links": {
        "self": {
            "href": "/rest/1/contact/382390387/tags/4406099"
        }
    },
    "http_status": 202,
    "status": "success",
    "tag": {
        "id": 4406099,
        "title": "Sample Tag"
    }
}
↑ Top

PUT /rest/1/contacts/{contact_id}/tags/{tag_id}

Update the contents of a tag on a contact.

Parameters:
Name Type Data Type Required Description
title form string Yes The title of the tag that will be displayed
↑ Top

DELETE /rest/1/contacts/{contact_id}/tags/{tag_id}

Remove the tag from a contact. 

curl "https://www.phoneburner.com/rest/1/tags/{tag_id}" \
        -X DELETE \
        -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd"

Response shape

An empty body with an HTTP Status code of 204 (no content).

↑ Top

content

CM Content

GET /rest/1/content

Get current content

Parameters:
Name Type Data Type Required Description
type query Must be one of (onetouch, script, aac_email, add_appt_email, wmw_invitation, affiliate_invitation)
list query 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. Valid types:
1 (Text field)
2 (Checkbox)
3 (Date)
7 (Numeric)		 
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. Valid types:
1 (Text field)
2 (Checkbox)
3 (Date)
7 (Numeric)		 
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

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.
include_recording query integer If set to 1, a url to the recordings will be included. Please be aware this will slow down the total request.
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": "2023-08-06 10:59:53",
            "end_when": "2023-08-06 11:02:09",
            "connected_when": "2023-08-06 11:01:01",
            "disconnected_when": "2023-08-06 11:02:09",
            "call_count": 2,
            "calls":
            [

                {
                    "call_id": "1767709",
                    "phone": "9495551212",
                    "start_when": "2023-08-06 11:01:37",
                    "end_when": "2023-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, 2023 9:01 am - PB - Got a busy signal.",
                    "disposition": "Busy Phone"
                },

                {
                    "call_id": "1767710",
                    "phone": "9495551414",
                    "start_when": "2023-08-06 11:01:50",
                    "end_when": "2023-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, 2023 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": "2023-04-30 15:31:03",
                "end_when": "2023-04-30 15:33:29",
                "connected_when": "2023-04-30 15:33:15",
                "disconnected_when": "2023-04-30 15:33:29",
                "call_count": 1
            },

            {
                "dialsession_id": "70385",
                "callerid": "9495551234",
                "start_when": "2023-04-30 15:33:44",
                "end_when": "2023-04-30 15:34:25",
                "connected_when": "2023-04-30 15:34:02",
                "disconnected_when": "2023-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.
dialing_disposition_set_id body integer Yes The id of the dialing disposition set you want the dialer to default to. This is obtained through the disposition editor. Look at the URL in your browser for something like /dialer/disposition/edit_buttons?group_id=3223
answer_disposition_set_id body integer Yes The id of the answer disposition set you want the dialer to default to. This is obtained through the disposition editor. Look at the URL in your browser for something like /dialer/disposition/edit_buttons?group_id=3223
preview_mode body integer Yes A value of 0 or 1. 0 = Power Mode, 1 = Preview Mode.

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": "[email protected]",
                  "lead_id": "your_systems_id",
                  "category_id": 12345 },
                { "first_name": "Mary",
                  "last_name": "Doe",
                  "phone": "9495551235",
                  "email": "[email protected]",
                  "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"
            },
            "dialing_disposition_set_id": 1234,
            "answer_disposition_set_id": 5678,
            "preview_mode": 1
        }'

{
    "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
include_recording query integer If set to 1, a url to the recordings will be included. Please be aware this will slow down the total request. 
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": "2023-06-06 10:39:02",
            "end_when": "2023-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, 2023 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

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": "[email protected]",
                                "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": "[email protected]",
                "date_added": "2023-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

GET /rest/1/members

Retrieves a list of members

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": 2,
                "members":
                [

                        {
                                "user_id": "1234567",
                                "username": "[email protected]",
                                "first_name": "Saul",
                                "last_name": "Goodman",
                                "email_address": "[email protected]",
                                "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"
                                }
                        },
                        {
                                "user_id": "1300000",
                                "username": "[email protected]",
                                "first_name": "Walter",
                                "last_name": "White",
                                "email_address": "[email protected]",
                                "date_added": "2013-01-18 17:12:15",
                                "phone": "9492187890",
                                "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

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": "[email protected]",
                "date_added": "2023-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 Must be one of (onetouch, script, aac_email, add_appt_email, wmw_invitation, affiliate_invitation)
list query 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

tags

Tags

GET /rest/1/tags

Tags by user account for all contacts. 

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

Response shape:

{
    "_link": {
        "self": {
            "href": "/rest/1/tags"
        }
    },
    "_links": {
        "self": {
            "href": "/rest/1/tags"
        }
    },
    "http_status": 200,
    "status": "success",
    "tags": {
        "tags": [
            {
                "id": 4406097,
                "title": "another tag"
            },
            {
                "id": 4406096,
                "title": "test"
            }
        ],
        "total_results": 2,
        "page": 1,
        "page_size": 2,
        "total_pages": 1
    }
}
↑ Top

POST /rest/1/tags

Add new tag

Parameters:
Name Type Data Type Required Description
title form string Yes String contents of the tag for display 
curl "https://www.phoneburner.com/rest/1/tags" \
    -X POST \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
    -d '{"title": "Your tag title goes here"}'

Response shape:

{
    "_links": {
        "self": {
            "href": "/rest/1/contact/tags"
        }
    },
    "http_status": 202,
    "status": "success",
    "tag": {
        "id": 4406100,
        "tag": "A new tag"
    }
}
↑ Top

PUT /rest/1/tags/{tag_id}

Update the tag's title.

Parameters:
Name Type Data Type Required Description
title form string Yes The tag's title 
curl "https://www.phoneburner.com/rest/1/tags/{tag_id}" \
    -X PUT \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
    -d '{"title": "Your tag title goes here"}'

Response shape:

{
    "_links": {
        "self": {
            "href": "/rest/1/tags"
        }
    },
    "http_status": 202,
    "status": "success",
    "tag": {
        "id": 4406100,
        "tag": "A new tag"
    }
}
↑ Top

DELETE /rest/1/tags/{tag_id}

Remove the tag recursively across all contacts. 

curl "https://www.phoneburner.com/rest/1/tags/{tag_id}" \
    -X DELETE \
    -H "Authorization: Bearer m8gZnWNplpHFAHFK79CLfSlBpqwCZ4THA9axa7dd" \
    -d '{"title": "Your tag title goes here"}'

Response shape:

204 no content
↑ 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

phonenumber

Delete by phone number

DELETE /rest/1/phonenumber/{phone_number}

Deletes all phone numbers out of a user's account. A successful response is '204 No Content'. 

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