Documentation: API v1 (Deprecated)

The API v1 (Deprecated) In Depth

Warning

This version (v1) of the API is deprecated and will not be maintained. We recommend using the v2 API instead.

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


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.

View lists

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

[{
  id: 812,
  name: "My hot leads",
  locked_on_defaults: false,
  location: "/api/v1/lists/812",
  created_at: "2014-10-06T22:01:41.815+02:00",
  leads_count: 99
}]
Parameters:
locked_on_defaults
Boolean - if 'true' or '1' only lists that guarantee to have our default fields defined will be returned.

View column information for a list

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

[{
  id: 10113,
  type: "unicode",
  key: "myphoner_name",
  required: false,
  label: "Name"
},
{
  id: 10123,
  type: "unicode",
  key: "myphoner_company",
  required: false,
  label: "Company"
},
{
  id: 10118,
  type: "unicode",
  key: "myphoner_phone",
  required: false,
  label: "Phone"
},
{
  id: 10120,
  type: "unicode",
  key: "myphoner_email",
  required: false,
  label: "E-mail"
}]
<?php

$ch = curl_init();

$headers = array(
"Accept: application/json",
"Content-type: application/json",
"Authorization: Token \"JKrseYhYs-dPdB1xH37R\""
);

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_URL,"https://bcb.myphoner.com/api/v1/lists/14910/columns");

// receive server response ...
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec ($ch);
curl_close ($ch);
var_dump($response);

?>

View leads in a list

curl https://demo.myphoner.com/api/v1/lists/812/leads \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
[
   {
      "list_location" : "/api/v1/lists/4146",
      "events" : [
         {
            "kind" : "claim",
            "created_at" : "2016-04-11T12:34:11.000Z",
            "category" : null,
            "user_name" : "Elinore Legros",
            "comment" : null
         },
         {
            "comment" : "Rerum quo unde omnis culpa est qui nobis.",
            "category" : null,
            "user_name" : "Elinore Legros",
            "created_at" : "2016-04-11T12:34:11.000Z",
            "kind" : "call_back"
         }
      ],
      "location" : "/api/v1/leads/3819047",
      "state" : "call_back",
      "e_mail" : "sociis@Intinciduntcongue.co.uk",
      "created_at" : "2015-08-20T11:11:54.763Z",
      "phone" : "(362) 803-5319",
      "detected_duplicates" : [],
      "name" : "Kelly Patterson",
      "id" : 3819047,
      "claimed_at" : null,
      "url" : "http://demo.myphoner.dev/work/leads/3819047",
      "ignored_duplicates" : [],
      "company" : "Ultrices Consulting 2",
      "claimed_by" : null,
      "last_event" : {
         "kind" : "call_back",
         "created_at" : "2016-04-11T12:34:11.000Z",
         "user_name" : "Elinore Legros",
         "category" : null,
         "comment" : "Rerum quo unde omnis culpa est qui nobis."
      },
      "last_updated" : "2016-09-30T10:58:03.279Z",
      "tertiary_identifier" : "(362) 803-5319",
      "primary_identifier" : "Kelly Patterson",
      "secondary_identifier" : "Ultrices Consulting 2",
      "list_name" : "Campaign 2",
      "scheduled_for" : "2016-04-15T12:34:11.000Z"
    },
    {
      "secondary_identifier" : "Suscipit Nonummy Corp.",
      "list_name" : "Campaign 2",
      "scheduled_for" : "2016-10-01T13:57:57.334Z",
      "tertiary_identifier" : "(435) 991-6538",
      "last_updated" : "2016-09-30T10:57:57.418Z",
      "last_event" : {
         "user_name" : "Jeppe Liisberg",
         "category" : null,
         "created_at" : "2016-09-30T10:57:57.416Z",
         "kind" : "call_back",
         "comment" : "hest"
      },
      "primary_identifier" : "Murphy Cox",
      "ignored_duplicates" : [],
      "claimed_by" : "jeppe@myphoner.com",
      "company" : "Suscipit Nonummy Corp.",
      "url" : "http://demo.myphoner.dev/work/leads/3816971",
      "claimed_at" : "2016-09-30T10:57:57.335Z",
      "id" : 3816971,
      "name" : "Murphy Cox",
      "detected_duplicates" : [],
      "phone" : "(435) 991-6538",
      "e_mail" : "arcu.vel.quam@dolorsit.com",
      "created_at" : "2015-08-20T11:11:52.154Z",
      "state" : "call_back",
      "location" : "/api/v1/leads/3816971",
      "list_location" : "/api/v1/lists/4146",
      "events" : [
         {
            "kind" : "call_back",
            "created_at" : "2016-09-30T10:57:57.416Z",
            "category" : null,
            "user_name" : "Jeppe Liisberg",
            "comment" : "hest"
         },
         {
            "kind" : "claim",
            "created_at" : "2016-09-30T10:57:57.354Z",
            "user_name" : "Jeppe Liisberg",
            "category" : null,
            "comment" : null
         }
      ]
    }
  ]
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.

Create a new lead

curl -XPOST -d '{"lead":{"myphoner_name":"My test lead","myphoner_phone":"12345678"}}' \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -D- https://demo.myphoner.com/api/v1/lists/4146/leads
{
  id: 2790825
}
<?php

$ch = curl_init();

$headers = array(
"Accept: application/json",
"Content-type: application/json",
"Authorization: Token \"JKrseYhYs-dPdB1xH37R\""
);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_URL,"https://bcb.myphoner.com/api/v1/lists/14910/leads'");

$post_params = array('lead' => array("myphoner_first_name" => "My test lead", "myphoner_phone" => "12345678"));
curl_setopt($ch, CURLOPT_POST, 0);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($post_params));

// receive server response ...
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec ($ch);
curl_close ($ch);
var_dump($response);

?>
Please note that although the create request will return more data, only the 'id' attribute is guaranteed to remain stable.

View a lead

curl -i https://demo.myphoner.com/api/v1/leads/2790825 \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
{
  "claimed_by" : null,
  "id" : 3820320,
  "ignored_duplicates" : [],
  "claimed_at" : null,
  "e_mail" : "a@Vivamus.net",
  "url" : "http://demo.myphoner.dev/work/leads/3820320",
  "list_name" : "Campaign 2",
  "created_at" : "2015-08-20T11:11:56.971Z",
  "company" : "Mauris Suspendisse Foundation",
  "detected_duplicates" : [],
  "primary_identifier" : "Nigel Boyd",
  "last_event" : {
     "comment" : "",
     "created_at" : "2016-04-27T17:54:09.095Z",
     "kind" : "call_back",
     "category" : null,
     "user_name" : "Elinore Legros"
  },
  "scheduled_for" : null,
  "name" : "Nigel Boyd",
  "tertiary_identifier" : "(920) 432-9600",
  "location" : "/api/v1/leads/3820320",
  "phone" : "(920) 432-9600",
  "last_updated" : "2016-04-27T17:54:09.098Z",
  "list_location" : "/api/v1/lists/4146",
  "events" : [
     {
        "created_at" : "2016-04-27T17:54:09.095Z",
        "category" : null,
        "kind" : "call_back",
        "comment" : "",
        "user_name" : "Elinore Legros"
     }
  ],
  "secondary_identifier" : "Mauris Suspendisse Foundation",
  "state" : "call_back"
}
The 'detected_duplicates' and 'ignored_duplicates' are 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.

Find a lead

curl https://demo.myphoner.com/api/v1/lists/4146/leads/find?myphoner_phone=%28390%29%20882-0469 \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
[
   {
      "secondary_identifier" : "Non Company",
      "claimed_at" : null,
      "list_name" : "Campaign 2",
      "phone" : "(390) 882-0469",
      "last_updated" : null,
      "claimed_by" : null,
      "company" : "Non Company",
      "name" : "Yeo Garrett",
      "url" : "http://demo.myphoner.dev/work/leads/3820331",
      "e_mail" : "odio.Nam.interdum@nonarcu.net",
      "list_location" : "/api/v1/lists/4146",
      "location" : "/api/v1/leads/3820331",
      "events" : [],
      "state" : "new",
      "tertiary_identifier" : "(390) 882-0469",
      "scheduled_for" : null,
      "ignored_duplicates" : [],
      "detected_duplicates" : [],
      "created_at" : "2015-08-20T11:11:56.971Z",
      "primary_identifier" : "Yeo Garrett",
      "id" : 3820331
   }
]
The 'detected_duplicates' and 'ignored_duplicates' are 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.

Update a lead

curl -XPATCH -d '{"lead":{"myphoner_name":"John Doe","myphoner_company":"Doe Inc."}}' \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -D- https://demo.myphoner.com/api/v1/leads/744655
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.

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/v1/leads/744655/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/v1/leads/744655/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 "call_back"-event.
category
String - The category of the "call_back"-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/v1/leads/744655/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 "loser"-event.
category
String - The category of the "loser"-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/v1/leads/744655/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 "archive"-event.
category
String - The category of the "archive"-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/v1/leads/744655/delegate
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":"4146"}}' \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -D- https://demo.myphoner.com/api/v1/leads/744655/migrate
If the request is successful, a status of 204 (no content) is returned.

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 lead on which the event is related.

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

curl -X POST https://<your_subdomain>.myphoner.com/api/v1/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
  • loser
  • archive
  • call_back
  • new_comment - when a new comment is created for a lead regardless of the state
  • new_event - any new event including all of the above
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
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/v1/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.