Developer API Documentation

We maintain a simple, restful json API to enable easy integration of data from and to Myphoner. Learn how to integrate your tool against the Myphoner API.

Authentication

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'.

Request Rate Limitation

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.

Querying the API

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.

Invite a new user to an account

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"

View lists

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.

Create a new list

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)

View details for a list

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"]
    }
  }
            

View column information for a list

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
  }]
            

View leads in a list

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.

View lead statistics for a list

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
}
            

Create a new lead

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
            

View a lead

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.

Update a lead

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

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

Search for leads

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.

Mark a lead as winner

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.

Mark a lead for call back

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.

Mark a lead as loser

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.

Archive a lead

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.

Delegate/Claim a lead

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.

Migrate/Move a lead between lists

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.

View call information

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"
     }]
  }
            

Subscribing to events using webhooks

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.

Subscribe to a webhook - scope by list

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.

Subscribe to a webhook - account wide

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.

Receive notifications from a 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.

Unsubscribe/delete a webhook

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.