Developer API Documentation

Before you can use the API, you need to authenticate. This section explains how.

You need to obtain the API key from your account under Manage -> Configure -> Integrations.

Users also have an API key, that the same access rights as the the corresponding user. The personal API key can be obtained from the users preferences page under 'Credentials'.

Our API has throttling that you'll need to respect.

The server will respond with 429 Too Many Requests if you exceed 60 rpm or 300 requests for 5 minutes.

When you implement your API integration, you need to make sure that your client can do an exponential backoff if you get a 429 response code from us.

429 responses will contain a “Ratelimit-Reset” header with a timestamp indicating when the next request can occur. Any API client should wait until at least the specified timestamp before continuing with requests.

If you don't do this, you risk losing data.

Use our RESTful API to automate different tasks, such as updating lead data from your CRM or other sources of data, or creating new events or comments to leads.

To view information about lists and leads, as well as create leads or events, you can use the following queries.

curl -XPOST -d '{"accept_charge_upon_invitation_acceptance": "1","user":{"first_name":"John","last_name":"Doe","email":"john.doe@example.com","listing_ids":["28885","29455"]}}' \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H 'Authorization: Token "<your_api_key>"' \
-D- https://demo.myphoner.com/api/v2/users
{
   "created_at" : "2017-11-08T10:04:27.822Z",
   "first_name" : "John",
   "updated_at" : "2017-11-08T10:04:27.822Z",
   "id" : 6941,
   "email" : "john.doe@example.com",
   "last_name" : "Doe"
}
            

Parameters:

accept_charge_upon_invitation_acceptance

This is a flag that must be set to "1". It indicates that the API consumer has acknowledged that creating a user will cause a higher subscription fee and corresponding charge once the user accepts the invitation.

user[first_name]

String - optional.

user[last_name]

String - optional.

user[email]

String - required.

user[agent]

Boolean - optional. This user has the "Agent" role. Default is true.

user[users_admin]

Boolean - optional. This user has the role "User manager". Default is false.

user[lists_admin]

Boolean - optional. This user has the role "Data manager". Default is false.

user[analyst]

Boolean - optional. This user has the role "Analyst". Default is false.

user[supervisor]

Boolean - optional. This user has the role "Supervisor". Default is false.

user[listing_ids]

Array of integers - optional. Ids describing which lists this user has access to when they have the role "Agent"

curl https://demo.myphoner.com/api/v2/lists \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H 'Authorization: Token "<your_api_key>"'

[{
  "name" : "Campaign 1",
  "location" : "/api/v2/lists/15288",
  "created_at" : "2016-11-15T12:36:28.024Z",
  "id" : 15288,
  "locked_on_defaults" : true,
  "leads_count" : 5
},
{
  "locked_on_defaults" : false,
  "created_at" : "2015-08-20T11:11:14.394Z",
  "id" : 4146,
  "location" : "/api/v2/lists/4146",
  "name" : "Campaign 2",
  "leads_count" : 5093
}]
            

Parameters:

locked_on_defaults

Boolean - if 'true' or '1' only lists that guarantee to have our default fields defined will be returned.

curl -XPOST -d '{"list":{"name":"New Campaign","columns_attributes":{"0":{"label":"Name","kind":"none"},"1":{"label":"Phone","kind":"phone"}}}}' \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -D- https://demo.myphoner.com/api/v2/lists
  {
     "leads_count" : 0,
     "categories" : {},
     "id" : 29999,
     "locked_on_defaults" : false,
     "location" : "/api/v2/lists/29999",
     "created_at" : "2017-11-08T10:19:19.643Z",
     "name" : "New Campaign"
  }
            

Parameters:

list[name]

String - required. The name of the list.

list[prepend_phone]

Boolean - optional.

list[inline_identifiers]

Boolean - optional.

list[show_avatars]

Boolean - optional.

list[lock_on_defaults]

Boolean - optional.

list[queue_new_before_call_backs]

Boolean - optional.

list[queue_new_before_due]

Boolean - optional.

list[duplicates_match_on_phone]

Boolean - optional.

list[duplicates_match_on_email]

Boolean - optional.

list[duplicates_match_on]

String - optional.

list[description]

String - optional. Script for the list.

list[call_back_categories]

String - optional. Comma-separated list of sub-categories for call backs.

list[winner_categories]

String - optional. Comma-separated list of sub-categories for winners.

list[loser_categories]

String - optional. Comma-separated list of sub-categories for losers.

list[archive_categories]

String - optional. Comma-separated list of sub-categories for archives.

list[skip_categories]

String - optional. Comma-separated list of sub-categories for skips.

list[user_ids]

Array of integers - optional. Ids of agents that should have access to this list.

list[columns_attributes]: %i[label kind visible]

Parameters for fields in the list. Should be in the form

"0":{"label":"Name","kind":"none"},
"1":{"label":"Phone","kind":"phone"}
                  

The order of the fields will match their index in the "columns_attributes".
Kind can be any of:

• "none" (String (standard))
• "phone" (Phone)
• "email" (E-mail)
• "url" (www)
• "boolean" (Yes/No)
• "integer" (Number)
• "date" (Date)
• "text" (Multi-line Text)
• "options" (Options)
• "address" (Street Address)

curl https://demo.myphoner.com/api/v2/lists/15288 \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'

  {
    "name" : "Campaign 1",
    "location" : "/api/v2/lists/15288",
    "created_at" : "2016-11-15T12:36:28.024Z",
    "id" : 15288,
    "locked_on_defaults" : true,
    "leads_count" : 5,
    "categories" : {
      "call_back" : ["sooner", "later"],
      "winner" : ["bigger", "smaller"]
    }
  }
            

curl -i https://demo.myphoner.com/api/v2/lists/15288/columns \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'

  [{
    "id" : 188750,
    "input_type" : "string",
    "required" : false,
    "label" : "First Name",
    "key" : "first_name",
    "type" : "unicode"
  },
  ...
  {
    "key" : "birthday",
    "label" : "Birthday",
    "type" : "datetime",
    "id" : 188759,
    "input_type" : "date",
    "required" : false
  }]
            

curl https://demo.myphoner.com/api/v2/lists/15288/leads \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'

[
  {
    "id" : 13722815,
    "last_updated" : "2016-11-15T12:37:25.331Z",
    "list_location" : "/api/v2/lists/15288",
    "primary_identifier" : "Craig Tillman",
    "secondary_identifier" : "nunc nulla",
    "tertiary_identifier" : "mauris erat eget",
    "state" : "new",
    "scheduled_for" : null,
    "list_name" : "Campaign 1",
    "claimed_by" : null,
    "claimed_at" : null,
    "category" : null,
    "detected_duplicates" : [],
    "url" : "http://demo.myphoner.dev/work/leads/13722815",
    "location" : "/api/v2/leads/13722815",
    "created_at" : "2016-11-15T12:37:25.331Z",
    "ignored_duplicates" : [],
    "lead_data" : {
       "mobile_phone" : "1 35 195 6007-0909",
       "first_name" : "Craig",
       "company_name" : "mauris erat eget",
       "title" : "nunc nulla",
       "" : "",
       "e_mail" : "non.justo.Proin@ipsumnunc.ca",
       "last_name" : "Tillman",
       "birthday" : "1980-06-12 20:10:36",
       "work_office_phone" : "1 57 733 2671-8905",
       "full_name" : "Crãig Tillman"
    }
  },
  ...
]
            

Parameters:

per_page

Integer - number of leads returned (default: 50)

page

Integer - page number (default: 1)

order

String - if present and equals 'last_updated_first' leads will be returned in the order of last_updated descending (most recently updated first)

By default leads are returned newest first (created_at descending), so you can update your own records by fetching the first page(s) until you encounter a known lead.

curl https://demo.myphoner.com/api/v2/lists/29455/stats \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
{
   "location" : "/api/v2/lists/29455",
   "id" : 29455,
   "created_at" : "2017-10-26T09:34:00.043Z",
   "name" : "5000leads",
   "leads_count" : 5099,
   "leads_counts" : {
      "archived" : {
         "uncategorised" : 2,
         "total" : 2
      },
      "call_back" : {
         "bad_time" : 1,
         "uncategorised" : 16,
         "positive" : 3,
         "no_answer" : 6,
         "voicemail" : 2,
         "gatekeeper" : 0,
         "total" : 28
      },
      "won" : {
         "total" : 4,
         "uncategorised" : 4
      },
      "lost" : {
         "uncategorised" : 5,
         "total" : 5
      },
      "new" : {
         "total" : 5060,
         "uncategorised" : 5060
      },
      "total" : 5099
   },
   "locked_on_defaults" : false
}
            

curl -XPOST -d '{"lead":{"first_name":"John","last_name":"Doe","mobile_phone":"12345678"}}' \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -D- https://demo.myphoner.com/api/v2/lists/15288/leads
            

curl https://demo.myphoner.com/api/v2/leads/13722811 \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
            

The 'detected_duplicates' and 'ignored_duplicates' keys returned for a lead holds arrays of integers of lead ids. After uploading an entire new list, this information might not be updated for up to an hour (depending on the size of the list), since duplicate detection can take some time to run. Creation of a single lead will have duplicate detection done within a couple of minutes.

curl -XPATCH -d '{"lead":{"full_name":"John Doe","company_name":"Doe Inc."}}' \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -D- https://demo.myphoner.com/api/v2/leads/13722820
            

Parameters: any key specified in the list columns. Valid keys can be retrieved from the list column information

If the request is successful, a status of 204 (no content) is returned.

Find leads by one or more fields' data.

curl https://demo.myphoner.com/api/v2/lists/15288/leads/find?mobile_phone=15324083898652 \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
            

The 'detected_duplicates' and 'ignored_duplicates' keys returned for a lead hold arrays of integers of lead ids. After uploading an entire new list, this information might not be updated for up to an hour (depending on the size of the list), since duplicate detection can take some time to run. Creation of a single lead will have duplicate detection done within a couple of minutes.

Multiple parameters can be submmitted. If you want leads to be found on matching any of the supplied parameters (instead of all by default) supply a 'matchall=false' parameter in addition.

Parameters:

field_name

String - value of the field your are finding by

matchall

concatenate multiple field/value conditions with OR instead of AND

Free text search for leads. Just like the in-app search.

curl "https://demo.myphoner.com/api/v2/leads/search?query=Houston&list_ids=812,4146" \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
{
   "total" : 2,
   "leads" : [
     ...
   ]
}
              

Parameters:

query

String - The query string. All lead data including activity logs will be searched. Just like the search field within Myphoner.

list_ids

colon-separated list of list IDs to scope the search for. Can be used to limit the search to one or a limited number of lists.

per_page

Integer - maximum number of leads returned (default: 50)

page

Integer - page number (default: 1)

The 'detected_duplicates' and 'ignored_duplicates' keys returned for a lead hold arrays of integers of lead ids. After uploading an entire new list, this information might not be updated for up to an hour (depending on the size of the list), since duplicate detection can take some time to run. Creation of a single lead will have duplicate detection done within a couple of minutes.

curl -XPOST -d '{"lead":{"call_back_in":"10","scheduled_for":"2016-06-04 08:04:55 UTC","comment":"My comment","category":""}}' \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -D- https://demo.myphoner.com/api/v2/leads/13722820/winner
              

Parameters:

call_back_in

Integer - Minutes until scheduled call back

scheduled_for

DateTime (YYYY-MM-DD HH:MM:SS UTC) - Time of call back. Takes precedence over 'call_back_in' if present.
Please refer to the getting started guide for understanding behavior when setting a schedule for leads that are not marked for call back.

comment

String - Text inserted as a comment on the "winner"-event.

category

String - The category of the "winner"-event - make sure it matches an existing category exactly, including case.

All parameters are optional.

If the request is successful, a status of 204 (no content) is returned.

curl -XPOST -d '{"lead":{"call_back_in":"10","scheduled_for":"2016-06-04 08:04:55 UTC","comment":"My comment","category":""}}' \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -D- https://demo.myphoner.com/api/v2/leads/13722820/call_back
              

Parameters:

call_back_in

Integer - Minutes until scheduled call back

scheduled_for

DateTime (YYYY-MM-DD HH:MM:SS UTC) - Time of call back. Takes precedence over 'call_back_in' if present.

comment

String - Text inserted as a comment on the "winner"-event.

category

String - The category of the "winner"-event - make sure it matches an existing category exactly, including case.

All parameters are optional.

If the request is successful, a status of 204 (no content) is returned.

curl -XPOST -d '{"lead":{"call_back_in":"10","scheduled_for":"2016-06-04 08:04:55 UTC","comment":"My comment","category":""}}' \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -D- https://demo.myphoner.com/api/v2/leads/13722820/loser
              

Parameters:

call_back_in

Integer - Minutes until scheduled call back

scheduled_for

DateTime (YYYY-MM-DD HH:MM:SS UTC) - Time of call back. Takes precedence over 'call_back_in' if present.
Please refer to the getting started guide for understanding behavior when setting a schedule for leads that are not marked for call back.

comment

String - Text inserted as a comment on the "winner"-event.

category

String - The category of the "winner"-event - make sure it matches an existing category exactly, including case.

All parameters are optional.

If the request is successful, a status of 204 (no content) is returned.

curl -XPOST -d '{"lead":{"call_back_in":"10","scheduled_for":"2016-06-04 08:04:55 UTC","comment":"My comment","category":""}}' \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -D- https://demo.myphoner.com/api/v2/leads/13722820/archive
              

Parameters:

call_back_in

Integer - Minutes until scheduled call back

scheduled_for

DateTime (YYYY-MM-DD HH:MM:SS UTC) - Time of call back. Takes precedence over 'call_back_in' if present.
Please refer to the getting started guide for understanding behavior when setting a schedule for leads that are not marked for call back.

comment

String - Text inserted as a comment on the "winner"-event.

category

String - The category of the "winner"-event - make sure it matches an existing category exactly, including case.

All parameters are optional.

If the request is successful, a status of 204 (no content) is returned.

curl -XPATCH -d '{"lead":{"delegate_to":"1250"}}' \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -D- https://demo.myphoner.com/api/v2/leads/13722820/delegate
            

Parameters:

delegate_to

Integer or String - ID or E-mail of the user that should hold the claim of the lead.

If the request is successful, a status of 204 (no content) is returned.

curl -XPATCH -d '{"lead":{"to_list_id":"15288"}}' \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -D- https://demo.myphoner.com/api/v2/leads/13722820/migrate
            

Parameters:

to_list_id

Integer - ID of the list where the lead should be moved. Must be present, but can be the same as the current one, which can be desirable if you just want to give back the lead and keep it on the same list.

give_back_leads

String - "1" to release lead if it is claimed, "0" to leave it as is (same as not including this parameter)

If the request is successful, a status of 204 (no content) is returned.

Subscribe to the new_call or new_recording webhook to get callbacks when new call information is available.

  curl https://demo.myphoner.com/api/v2/calls/<call_id>/ \
    -H "Accept: application/json" \
    -H "Content-type: application/json" \
    -H 'Authorization: Token "<your_api_key>"'
  {
     "location" : "/api/v2/calls/<call_id>/",
     "user_email" : "john.doe@example.com",
     "destination_number" : "4512345678",
     "duration" : 68,
     "started_at" : "2020-11-18T08:43:12.000Z",
     "recordings" : [{
       "started_at" : "2020-11-18T08:43:12.000Z"
       "url" : "https://path.to/recording.wav"
     }]
  }
            

You can subscribe to events in Myphoner such as new winner, new loser, archiving of a lead or call backs through a pattern called "Notification REST Hooks".

Once subscribed, you'll get an instant notification at a url of your own choice, with information about the event and where to obtain further data about the entity to which the event is related.

Webhooks does NOT trigger when manipulating leads and events via the API.

Read on for a step by step guide on using our webhooks.

curl -X POST https://<your_subdomain>.myphoner.com/api/v2/lists/<list_id>/webhook \
  -H 'Authorization: Token "<your_api_key>"' \
  -H 'Content-Type: application/json' \
  -d '{"webhook": {"target_url": "https://yourdomain.com/path/to/target/endpoint",
       "event": "winner"}}'
            

Parameters:

target_url

String - Url on your domain that will receive and understand a POST request about this event (see below)

event

String - The event that triggers a notification. Valid values are:

• winner - the "Winner" action button was clicked
• loser - the "Loser" action button was clicked
• archive - the "Archive" action button was clicked
• call_back - the "Call back" action button was clicked
• text - a text message was sent to a lead
• inbound_text - a text message was received from a lead
• new_event - any new event (including all of the above) except "unclaim" and "migration"
• new_comment - when a new comment is created for a lead regardless of the state
• lead_created - a new lead was created in Myphoner by an agent
• lead_updated - a lead had it's lead information updated by an agent
• new_call - a new call has been conducted
• new_recording - a new recorded call has been conducted

All parameters are required.

If the request is successful, a status of 201 (created) is returned together with a json representation of the webhook. Make sure you save the webhook ID for later unsubscription/deletion of the webhook.

Webhooks does NOT trigger when manipulating leads and events via the API.

curl -X POST https://<your_subdomain>.myphoner.com/api/v2/webhooks \
  -H 'Authorization: Token "<your_api_key>"' \
  -H 'Content-Type: application/json' \
  -d '{"webhook": {"target_url": "https://yourdomain.com/path/to/target/endpoint",
       "event": "new_recording"}}'
            

Parameters:

target_url

String - Url on your domain that will receive and understand a POST request about this event (see below)

event

String - The event that triggers a notification. Valid values are:

• new_call - a new call has been conducted
• new_recording - a new recorded call has been conducted

All parameters are required.

If the request is successful, a status of 201 (created) is returned together with a json representation of the webhook. Make sure you save the webhook ID for later unsubscription/deletion of the webhook.

The url you provided when creating the webhook will be used for notifications of new events. Make sure you have a capable API listening for our call.

curl -X POST https://yourdomain.com/path/to/target/endpoint \
  -H 'Content-Type: application/json' \
  -d '{"resource_url": "<resources_url>"}'
            

Parameters:

resource_url

String - Url where the lead related to the event for this webhook subscription can be found

All parameters are required.

On a successful hook, you must return a 200 status code, content is irrelevant.

curl -X DELETE https://<your_subdomain>.myphoner.com/api/v2/webhook/<webhook_id> \
  -H 'Authorization: Token "<your_api_key>"' \
  -H 'Content-Type: application/json'
            

Parameters:

webhook_id

String - ID of the webhook that you saved when you created it.

All parameters are required.

If the request is successful, a status of 200 (ok) is returned.