Documentation: API

The API In Depth

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

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"
  },
  {
    "required" : false,
    "input_type" : "string",
    "id" : 188751,
    "type" : "unicode",
    "key" : "last_name",
    "label" : "Last Name"
  },
  {
    "id" : 188752,
    "input_type" : "string",
    "required" : false,
    "label" : "Title",
    "key" : "title",
    "type" : "unicode"
  },
  {
    "id" : 188753,
    "input_type" : "string",
    "required" : false,
    "key" : "company_name",
    "label" : "Company Name",
    "type" : "unicode"
  },
  {
    "id" : 188754,
    "input_type" : "url",
    "required" : false,
    "label" : "Website",
    "key" : "website",
    "type" : "unicode"
  },
  {
    "type" : "unicode",
    "key" : "work_office_phone",
    "label" : "Work/Office Phone",
    "required" : false,
    "input_type" : "tel",
    "id" : 188755
  },
  {
    "input_type" : "tel",
    "id" : 188756,
    "required" : false,
    "key" : "mobile_phone",
    "label" : "Mobile Phone",
    "type" : "unicode"
  },
  {
    "label" : "E-mail",
    "key" : "e_mail",
    "type" : "unicode",
    "input_type" : "email",
    "id" : 188757,
    "required" : false
  },
  {
    "label" : "Full Name",
    "key" : "name",
    "type" : "unicode",
    "id" : 188758,
    "input_type" : "string",
    "required" : false
  },
  {
    "key" : "birthday",
    "label" : "Birthday",
    "type" : "datetime",
    "id" : 188759,
    "input_type" : "date",
    "required" : false
  }]
<?php

$ch = curl_init();

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

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_URL,"https://bcb.myphoner.com/api/v2/lists/15288/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/v2/lists/15288/leads \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'

[
   {
      "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"
      },
      "id" : 13722815,
      "last_updated" : "2016-11-15T12:37:25.331Z",
      "tertiary_identifier" : "mauris erat eget",
      "list_location" : "/api/v2/lists/15288",
      "secondary_identifier" : "nunc nulla",
      "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" : [],
      "primary_identifier" : "Craig Tillman"
   },
   {
      "ignored_duplicates" : [],
      "created_at" : "2016-11-15T12:37:25.331Z",
      "primary_identifier" : "Eaton Frederick",
      "category" : null,
      "detected_duplicates" : [],
      "location" : "/api/v2/leads/13722814",
      "url" : "http://demo.myphoner.dev/work/leads/13722814",
      "claimed_at" : null,
      "claimed_by" : null,
      "secondary_identifier" : "ut, sem.",
      "scheduled_for" : null,
      "state" : "new",
      "list_name" : "Campaign 1",
      "tertiary_identifier" : "consectetuer",
      "list_location" : "/api/v2/lists/15288",
      "lead_data" : {
         "last_name" : "Frederick",
         "e_mail" : "aliquet.nec@pede.ca",
         "full_name" : "Eaton Frederick",
         "work_office_phone" : "1 56 940 8648-8643",
         "birthday" : "1973-05-28 17:57:49",
         "company_name" : "consectetuer",
         "first_name" : "Eaton",
         "mobile_phone" : "1 79 599 2762-7050",
         "" : "",
         "title" : "ut, sem."
      },
      "id" : 13722814,
      "last_updated" : "2016-11-15T12:37:25.331Z"
   },
   {
      "list_name" : "Campaign 1",
      "secondary_identifier" : "ipsum non arcu.",
      "scheduled_for" : null,
      "state" : "lost",
      "tertiary_identifier" : "felis ullamcorper viverra. Maecenas",
      "last_action_or_note" : {
         "user_name" : "Jeppe Liisberg",
         "category" : "hostile",
         "comment" : "",
         "created_at" : "2016-11-15T12:54:04.466Z",
         "kind" : "loser"
      },
      "list_location" : "/api/v2/lists/15288",
      "id" : 13722813,
      "last_updated" : "2016-11-15T12:54:04.468Z",
      "lead_data" : {
         "birthday" : "1970-12-05 05:42:26",
         "work_office_phone" : "+1742623126-9481",
         "full_name" : "Zachéry Knox",
         "e_mail" : "mi.Aliquam@pellentesque.org",
         "last_name" : "Knox",
         "title" : "ipsum non arcu.",
         "" : "",
         "mobile_phone" : "+1586879476-2967",
         "first_name" : "Zachery",
         "company_name" : "felis ullamcorper viverra. Maecenas"
      },
      "primary_identifier" : "Zachery Knox",
      "ignored_duplicates" : [],
      "created_at" : "2016-11-15T12:37:25.331Z",
      "detected_duplicates" : [],
      "location" : "/api/v2/leads/13722813",
      "url" : "http://demo.myphoner.dev/work/leads/13722813",
      "category" : "hostile",
      "claimed_at" : null,
      "claimed_by" : null,
      "last_event" : {
         "user_name" : "Jeppe Liisberg",
         "category" : "hostile",
         "kind" : "loser",
         "created_at" : "2016-11-15T12:54:04.466Z",
         "comment" : ""
      }
   },
   {
      "last_event" : {
         "comment" : "",
         "created_at" : "2016-11-15T12:53:54.403Z",
         "kind" : "call_back",
         "category" : "maybe_later",
         "user_name" : "Jeppe Liisberg"
      },
      "claimed_by" : "jeppe@myphoner.com",
      "claimed_at" : "2016-11-15T12:53:54.336Z",
      "category" : "maybe_later",
      "detected_duplicates" : [],
      "location" : "/api/v2/leads/13722812",
      "url" : "http://demo.myphoner.dev/work/leads/13722812",
      "created_at" : "2016-11-15T12:37:25.331Z",
      "ignored_duplicates" : [],
      "primary_identifier" : "Hamilton Dillon",
      "lead_data" : {
         "birthday" : "1968-12-01 17:29:57",
         "full_name" : "Hamilton Dillon",
         "work_office_phone" : "11221375469714",
         "last_name" : "Dillon",
         "e_mail" : "dignissim@rhoncusidmollis.edu",
         "" : "",
         "title" : "Suspendisse",
         "first_name" : "Hamilton",
         "mobile_phone" : "1 29 106 6379-3946",
         "company_name" : "at augue id ante"
      },
      "id" : 13722812,
      "last_updated" : "2016-11-15T12:53:54.406Z",
      "tertiary_identifier" : "at augue id ante",
      "last_action_or_note" : {
         "category" : "maybe_later",
         "user_name" : "Jeppe Liisberg",
         "kind" : "call_back",
         "created_at" : "2016-11-15T12:53:54.403Z",
         "comment" : ""
      },
      "list_location" : "/api/v2/lists/15288",
      "secondary_identifier" : "Suspendisse",
      "state" : "call_back",
      "scheduled_for" : "2017-01-07T08:59:54.336Z",
      "list_name" : "Campaign 1"
   },
   {
      "state" : "won",
      "scheduled_for" : null,
      "secondary_identifier" : "Ullamcærper",
      "list_name" : "Campaign 1",
      "list_location" : "/api/v2/lists/15288",
      "last_action_or_note" : {
         "user_name" : "Jeppe Liisberg",
         "category" : null,
         "comment" : "Called me back, he want's to move on :-)",
         "kind" : "winner",
         "created_at" : "2016-11-15T12:54:34.855Z"
      },
      "tertiary_identifier" : "ARCU ltd.",
      "lead_data" : {
         "work_office_phone" : "14871028890053",
         "full_name" : "Åge Bøhmann",
         "birthday" : "1967-09-06 16:03:58",
         "e_mail" : "fermentum@phasellusornare.com",
         "last_name" : "Bøhmann",
         "title" : "Ullamcærper",
         "" : "",
         "company_name" : "ARCU ltd.",
         "mobile_phone" : "15324083898652",
         "first_name" : "Åge"
      },
      "last_updated" : "2016-11-15T12:54:34.857Z",
      "id" : 13722811,
      "created_at" : "2016-11-15T12:37:25.331Z",
      "ignored_duplicates" : [],
      "primary_identifier" : "Åge Bøhmann",
      "category" : null,
      "location" : "/api/v2/leads/13722811",
      "url" : "http://demo.myphoner.dev/work/leads/13722811",
      "detected_duplicates" : [],
      "claimed_at" : "2016-11-15T12:53:39.482Z",
      "last_event" : {
         "user_name" : "Jeppe Liisberg",
         "category" : null,
         "comment" : "Called me back, he want's to move on :-)",
         "created_at" : "2016-11-15T12:54:34.855Z",
         "kind" : "winner"
      },
      "claimed_by" : "jeppe@myphoner.com"
   }
]
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":{"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
{
   "id" : 13722820,
   "secondary_identifier" : null,
   "scheduled_for" : null,
   "url" : "http://demo.myphoner.dev/work/leads/13722820",
   "events" : [],
   "tertiary_identifier" : null,
   "claimed_by" : null,
   "detected_duplicates" : [],
   "created_at" : "2016-11-15T13:01:35.952Z",
   "category" : null,
   "lead_data" : {
      "first_name" : "John",
      "last_name" : "Doe",
      "mobile_phone" : "12345678"
   },
   "location" : "/api/v2/leads/13722820",
   "list_location" : "/api/v2/lists/15288",
   "claimed_at" : null,
   "last_updated" : "2016-11-15T13:01:35.952Z",
   "primary_identifier" : "John Doe",
   "ignored_duplicates" : [],
   "list_name" : "Campaign 1",
   "state" : "new"
}
<?php

$ch = curl_init();

$headers = array(
"Accept: application/json",
"Content-type: application/json",
"Authorization: Token \"<your_api_key>\""
);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_URL,"https://bcb.myphoner.com/api/v2/lists/15288/leads'");

$post_params = array('lead' => array("first_name" => "John", "last_name" => "Doe", "mobile_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);

?>

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>"'
{
   "secondary_identifier" : "Ullamcærper",
   "primary_identifier" : "Åge Bøhmann",
   "claimed_by" : "jeppe@myphoner.com",
   "state" : "won",
   "tertiary_identifier" : "ARCU ltd.",
   "location" : "/api/v2/leads/13722811",
   "list_name" : "Campaign 1",
   "scheduled_for" : null,
   "detected_duplicates" : [],
   "id" : 13722811,
   "list_location" : "/api/v2/lists/15288",
   "claimed_at" : "2016-11-15T12:53:39.482Z",
   "category" : null,
   "ignored_duplicates" : [],
   "last_updated" : "2016-11-15T12:54:34.857Z",
   "events" : [
      {
         "category" : null,
         "comment" : "Called me back, he want's to move on :-)",
         "created_at" : "2016-11-15T12:54:34.855Z",
         "user_name" : "Jeppe Liisberg",
         "kind" : "winner"
      },
      {
         "user_name" : "Jeppe Liisberg",
         "kind" : "call_back",
         "created_at" : "2016-11-15T12:53:39.533Z",
         "comment" : "",
         "category" : "busy"
      },
      {
         "created_at" : "2016-11-15T12:53:39.491Z",
         "kind" : "claim",
         "user_name" : "Jeppe Liisberg",
         "comment" : null,
         "category" : null
      }
   ],
   "lead_data" : {
      "company_name" : "ARCU ltd.",
      "work_office_phone" : "14871028890053",
      "birthday" : "1967-09-06 16:03:58",
      "organization" : "",
      "title" : "Ullamcærper",
      "name" : "Åge Bøhmann",
      "e_mail" : "fermentum@phasellusornare.com",
      "first_name" : "Åge",
      "mobile_phone" : "15324083898652",
      "last_name" : "Bøhmann"
   },
   "last_event" : {
      "category" : null,
      "comment" : "Called me back, he want's to move on :-)",
      "created_at" : "2016-11-15T12:54:34.855Z",
      "kind" : "winner",
      "user_name" : "Jeppe Liisberg"
   },
   "last_action_or_note" : {
      "created_at" : "2016-11-15T12:54:34.855Z",
      "comment" : "Called me back, he want's to move on :-)",
      "kind" : "winner",
      "user_name" : "Jeppe Liisberg",
      "category" : null
   },
   "created_at" : "2016-11-15T12:37:25.331Z",
   "url" : "http://demo.myphoner.dev/work/leads/13722811"
}
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

Lookup a lead based on matching data for a specific field.

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>"'
[
   {
      "url" : "http://demo.myphoner.dev/work/leads/13722811",
      "detected_duplicates" : [],
      "last_event" : {
         "category" : null,
         "created_at" : "2016-11-15T12:54:34.855Z",
         "comment" : "Called me back, he want's to move on :-)",
         "kind" : "winner",
         "user_name" : "Jeppe Liisberg"
      },
      "created_at" : "2016-11-15T12:37:25.331Z",
      "list_name" : "Campaign 1",
      "id" : 13722811,
      "primary_identifier" : "Åge Bøhmann",
      "ignored_duplicates" : [],
      "location" : "/api/v2/leads/13722811",
      "category" : null,
      "scheduled_for" : null,
      "tertiary_identifier" : "ARCU ltd.",
      "secondary_identifier" : "Ullamcærper",
      "claimed_at" : "2016-11-15T12:53:39.482Z",
      "claimed_by" : "jeppe@myphoner.com",
      "last_updated" : "2016-11-15T12:54:34.857Z",
      "list_location" : "/api/v2/lists/15288",
      "lead_data" : {
         "name" : "Åge Bøhmann",
         "e_mail" : "fermentum@phasellusornare.com",
         "first_name" : "Åge",
         "work_office_phone" : "14871028890053",
         "title" : "Ullamcærper",
         "organization" : "",
         "company_name" : "ARCU ltd.",
         "last_name" : "Bøhmann",
         "birthday" : "1967-09-06 16:03:58",
         "mobile_phone" : "15324083898652"
      },
      "state" : "won"
   }
]
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.

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" : [
      {
         "claimed_by" : null,
         "scheduled_for" : "2016-04-03T09:23:43.000Z",
         "category" : null,
         "list_name" : "Campaign 2",
         "url" : "https://demo.myphoner.com/work/leads/3815596",
         "detected_duplicates" : [
            3815460
         ],
         "secondary_identifier" : "fringilla mi",
         "state" : "lost",
         "id" : 3815596,
         "location" : "/api/v2/leads/3815596",
         "created_at" : "2015-08-20T11:11:50.581Z",
         "highlight" : "name: Connor <em>Houston</em>\nemail: velit.Cras.lorem@Crasconvallisconvallis",
         "last_event" : {
            "created_at" : "2016-03-30T09:23:43.000Z",
            "user_name" : "Elinore Legros",
            "kind" : "loser",
            "category" : null,
            "comment" : "Quos saepe voluptatem vero. Dolores hic et consequatur. Eum in molestiae. Enim ea consequatur. Similique nemo quia aliquid."
         },
         "ignored_duplicates" : [],
         "last_updated" : "2016-03-30T09:23:43.000Z",
         "claimed_at" : null,
         "primary_identifier" : "Connor Houston",
         "last_action_or_note" : {
            "user_name" : "Elinore Legros",
            "created_at" : "2016-03-30T09:23:43.000Z",
            "category" : null,
            "comment" : "Quos saepe voluptatem vero. Dolores hic et consequatur. Eum in molestiae. Enim ea consequatur. Similique nemo quia aliquid.",
            "kind" : "loser"
         },
         "list_location" : "/api/v2/lists/4146",
         "tertiary_identifier" : "Pede Praesent Eu Corp.",
         "lead_data" : {
            "name" : "Connor Houston",
            "e_mail" : "velit.Cras.lorem@Crasconvallisconvallis.ca",
            "" : "(915) 427-9267",
            "phone" : "(935) 847-6461",
            "company" : "Pede Praesent Eu Corp.",
            "title" : "fringilla mi"
         }
      },
      {
         "claimed_by" : null,
         "scheduled_for" : "2016-04-03T08:00:00.000Z",
         "category" : null,
         "list_name" : "Campaign 1",
         "url" : "https://demo.myphoner.com/work/leads/744651",
         "detected_duplicates" : [],
         "secondary_identifier" : "fermentum@phasellusornare.com",
         "state" : "lost",
         "id" : 744651,
         "location" : "/api/v2/leads/744651",
         "last_event" : {
            "created_at" : "2016-03-30T08:00:00.000Z",
            "user_name" : "Blesse Besana",
            "kind" : "loser",
            "category" : null,
            "comment" : "Consequatur aspernatur qui ut sapiente excepturi quis placeat."
         },
         "highlight" : "name: Leo <em>Houston</em>\nemail: fermentum@phasellusornare … 1967-09-06 16:03:58\nlast_name: <em>Houston</em>\nfirst_name: Leo\ncustom_identifier:",
         "created_at" : "2014-10-06T20:01:44.104Z",
         "ignored_duplicates" : [],
         "claimed_at" : null,
         "last_updated" : "2016-05-31T08:54:35.886Z",
         "primary_identifier" : "Leo Houston",
         "last_action_or_note" : {
            "user_name" : "Blesse Besana",
            "created_at" : "2016-03-30T08:00:00.000Z",
            "comment" : "Consequatur aspernatur qui ut sapiente excepturi quis placeat.",
            "category" : null,
            "kind" : "loser"
         },
         "list_location" : "/api/v2/lists/812",
         "tertiary_identifier" : "Ullamcorper",
         "lead_data" : {
            "organization" : null,
            "company" : "ARCU ltd.",
            "phone" : "14871028890053",
            "last_name" : "Houston",
            "e_mail" : "fermentum@phasellusornare.com",
            "birthday" : "1967-09-06 16:03:58",
            "" : "10347",
            "title" : "Ullamcorper",
            "first_name" : "Leo",
            "name" : "Leo Houston",
            "mobile" : "15324083898652"
         }
      }
   ]
}
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' 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.

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.

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

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/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
  • 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/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.