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.

Warning

Your API key is just like another password. Anyone that knows you API key can gain access to your account through the API, so keep it secret, keep it safe!

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.

Please note

All examples are provided using curl, and they can be copied and pasted to your console for testing purposes, just remember to replace credentials and IDs with your own.

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.

Please note

All examples are provided using curl, and they can be copied and pasted to your console for testing purposes, just remember to replace credentials and IDs with your own.

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.

On Error

Make sure your API responds with a 410 status code if something is permanently wrong and the subscription to the failing hook should be removed (unsubscribe)

Any other 4xx or 5xx status codes will be treated as temporary and ignored.

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.