Pipelines and Stages of Sales

Adding and updating pipelines and stages of sales

The stages of sales are the sequence of steps that a potential customer (lead) passes through the sales pipeline before buying. In amoCRM, you can create multiple sales cranes in one account and set your own milestones to track the progress of the lead in each pipeline. In amoCRM, you can configure up to 10 pipelines in your account. Each pipeline can contain up to 100 stages (including successful and unsuccessful statuses). Configure pipelines and stages of sales can administrator account on the Settings -> Sales stages page.

Methods for working with the settings of the stages of sales of the account. These methods are only available to the account administrator. The method allows you to add pipelines and stages of sales one at a time or in batches, and also update data on existing pipelines and stages. When you change the pipeline, you must submit a complete list of steps, including those already existing.

Method URL

POST / private / api / v2 / json / pipelines / set

Parameters

Parameter Type Description
add array The list of added pipelines, if an error occurs, this key will be specified in the error description
update array Updating an existing hopper
All the parameters that are described in add also work in the update
add/name

require
string Pipeline name
add/sort int Pipeline ordinal number when displayed
add/is_main string Is the pipeline “main” (it is necessary to pass the value “on” if it is)
add/statuses array Stages of the pipeline, you must pass at least one step, except successfully / unsuccessfully completed.
As the key, you must pass the ID of the step, if it exists. For stages successfully / unsuccessfully completed (id 142/143 respectively) it is possible to transfer only the field name
add/statuses// array Inside it will be a description of each step
add/statuses//name string The name of the stage
add/statuses//sort int Sequence number of the stage when displayed (automatically recomputed after adding)
add/statuses//color string The color of the stage (you can learn more here)
update/id

require
int The unique identifier of the pipeline, which is indicated for the purpose of updating it
update/statuses//id

require
int The unique identifier of the step, which is specified for the purpose of updating it

Example response

{
  "request": {
    "pipelines": {
      "add": [
        {
          "name": "Test Pipeline",
          "statuses": {
            "0": {
              "color": "#fffeb2",
              "name": "Status #0",
              "sort": 0
            },
            "1": {
              "color": "#fffeb2",
              "name": "Status #1",
              "sort": 10
            },
            "2": {
              "color": "#d6eaff",
              "name": "Status #2",
              "sort": 20
            },
            "3": {
              "color": "#f3beff",
              "name": "Status #3",
              "sort": 30
            },
            "142": {
              "name": "Success"
            },
            "143": {
              "name": "Failed"
            }
          },
          "is_main": "false"
        }
      ]
    },
    "update": {
      "2521": {
        "id": 2521,
        "name": "Retest Pipeline",
        "sort": 12,
        "is_main": "on",
        "statuses": {
          "10223179": {
            "id": 10223179,
            "name": "Status #0",
            "sort": 10,
            "color": "#fffeb2"
          },
          "10223183": {
            "id": 10223183,
            "name": "Status #4",
            "sort": 50,
            "color": "#deff81"
          },
          "10223184": {
            "id": 10223184,
            "name": "Status #5",
            "sort": 60,
            "color": "#d6eaff"
          },
          "10223185": {
            "id": 10223185,
            "name": "Status #6",
            "sort": 70,
            "color": "#fffd7f"
          }
        }
      }
    }
  }
}

Response parameters

Parameter Description
add/pipelines//id The unique identifier of the pipeline
add/pipelines//value The unique identifier of the pipeline
add/pipelines//label Pipeline name
add/pipelines//name Pipeline name
add/pipelines//sort Ordinal number of the pipeline when displayed
add/pipelines//is_main Is the pipeline the “main”
add/pipelines//statuses//id The unique identifier of the step
add/pipelines//statuses//name The name of the stage
add/pipelines//statuses//pipeline_id The unique identifier of the pipeline
add/pipelines//statuses//sort Sequence number of the stage when displaying
add/pipelines//statuses//color The color of the stage (you can learn more here)
add/pipelines//statuses//editable Is it possible to change or delete this stage, the possible values ​​are “Y” or “N”
add/pipelines//leads The number of leads in this pipeline
update// Associative array where the key is the pipeline ID, and the value – whether the change was applied to the pipeline with this identifier
server_time Time stamp of the current server time with offset to the time zone of the account (transmitted in timestamp format)

Example response

{
  "response": {
    "pipelines": {
      "add": {
        "pipelines":{
          "2116":{
            "id":2116,
            "value":2116,
            "label":"Pipeline",
            "name":"Pipeline",
            "sort":1,
            "is_main":true,
            "statuses":{
              "142":{
                "id":142,
                "name":"Closed - won",
                "color":"#CCFF66",
                "sort":10000,
                "editable":"N",
                "pipeline_id":2116
              },
              "143":{
                "id":143,
                "name":"Closed - lost",
                "color":"#D5D8DB",
                "sort":11000,
                "editable":"N",
                "pipeline_id":2116
              },
              "10216993":{
                "id":10216993,
                "name":"Initial Contact",
                "pipeline_id":2116,
                "sort":10,
                "color":"#99ccff",
                "editable":"Y"
              },
              "10216994":{
                "id":10216994,
                "name":"Offer made",
                "pipeline_id":2116,
                "sort":20,
                "color":"#ffff99",
                "editable":"Y"
              },
              "10216995":{
                "id":10216995,
                "name":"Negotiation",
                "pipeline_id":2116,
                "sort":30,
                "color":"#ffcc66",
                "editable":"Y"
              },
              "10216996":{
                "id":10216996,
                "name":"Contract Negotiation",
                "pipeline_id":2116,
                "sort":40,
                "color":"#ffcccc",
                "editable":"Y"
              }
            },
            "leads":14
          }
        }
      },
    "update": {
      "2521": true
    }
    }
  }
}

Adding a pipeline

To add a pipeline, you need to describe an array containing information about the pipeline and put it into an array of the following form: $ pipelines [‘request’] [‘pipelines’] [‘add’] Our API also supports the simultaneous addition of several pipelines. To do this, we put several arrays into the $ pipelines [‘request’] [‘pipelines’] [‘add’] array, each of which describes the necessary data to create the appropriate pipeline.

Example integration

$pipelines['request']['pipelines']['add'] = array(
  array(
    'name'     => 'Test Pipeline',
    'statuses' => array(
      array(
        'color' => '#deff81',
        'name'  => 'Status #0',
        'sort'  => 0,
      ),
      array(
        'color' => '#ffeab2',
        'name'  => 'Status #1',
        'sort'  => 10,
      ),
      array(
        'color' => '#ffdc7f',
        'name'  => 'Status #2',
        'sort'  => 20,
      ),
      array(
        'color' => '#deff81',
        'name'  => 'Status #3',
        'sort'  => 30,
      ),
      array(
        'color' => '#ebffb1',
        'name'  => 'Status #4',
        'sort'  => 40,
      ),
      array(
        'color' => '#fffeb2',
        'name'  => 'Status #5',
        'sort'  => 50,
      ),
      array(
        'color' => '#ffc8c8',
        'name'  => 'Status #6',
        'sort'  => 60,
      ),
      array(
        'color' => '#c1e0ff',
        'name'  => 'Status #7',
        'sort'  => 70,
      ),
      array(
        'color' => '#f3beff',
        'name'  => 'Status #8',
        'sort'  => 80,
      ),
      array(
        'color' => '#ccc8f9',
        'name'  => 'Status #9',
        'sort'  => 90,
      ),
    ),
    'is_main'  => 'on',
  ),
);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account is a subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/private/api/v2/json/pipelines/set';
/* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about work with this library you can read in the manual. */
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary parameters for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($pipelines));
curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
  301=>'Moved permanently',
  400=>'Bad request',
  401=>'Unauthorized',
  403=>'Forbidden',
  404=>'Not found',
  500=>'Internal server error',
  502=>'Bad gateway',
  503=>'Service unavailable'
);
try
{
  #If the response code is not 200 or 204, we return an error message
 if($code!=200 && $code!=204)
    throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
  die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}
 
/**
 * The data is obtained in the JSON format, therefore, to obtain readable data,
 * We will have to translate the response into a format that PHP understands
 */
$Response=json_decode($out,true);
$Response=$Response['response']['pipelines']['add'];
$output='The ID of the pipelines added:'.PHP_EOL;
$output .= implode(PHP_EOL, array_keys($Response));
return $output;

Updating pipelines

To update the pipeline information, you need to describe an array containing information about the pipeline and put it into an array of the following form: $ pipelines [‘request’] [‘pipelines’] [‘update’] Our API also supports the simultaneous updating of several pipelines simultaneously. To do this, we put several arrays in the $ pipelines [‘request’] [‘pipelines’] [‘update’ array, each of which describes the necessary data for updating the corresponding pipeline.

Example of integration

$pipelines['request']['pipelines']['update'] = array(
  2116 => array(
    'id'       => 2116,
    'name'     => 'Renamed Pipeline',
    'sort'     => 1,
    'is_main'  => FALSE,
    'statuses' => array(
      10216993 => array(
        'id'          => 10216993,
        'name'        => 'Initial Contact',
        'sort'        => 10,
        'color'       => '#99ccff',
      ),
      10216994 => array(
        'id'          => 10216994,
        'name'        => 'Offer made',
        'sort'        => 20,
        'color'       => '#ffff99',
      ),
      10216995 => array(
        'id'          => 10216995,
        'name'        => 'Negotiation',
        'sort'        => 30,
        'color'       => '#ffcc66',
      ),
      array(
        'name'        => 'New status#1',
        'sort'        => 40,
        'color'       => '#ffff99',
      ),
      array(
        'name'        => 'New status#2',
        'sort'        => 50,
        'color'       => '#99ccff',
      ),
      array(
        'name'        => 'New status#3',
        'sort'        => 60,
        'color'       => '#ffcccc',
      ),
      142      => array(
        'name'        => 'Closed_won',
      ),
      143      => array(
        'name'        => 'Closed_lost',
      ),
    ),
    'leads'    => 14,
  ),
);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account is a subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/private/api/v2/json/pipelines/set';
/* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about work with this library you can read in the manual. */
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary parameters for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($pipelines));
curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
  301=>'Moved permanently',
  400=>'Bad request',
  401=>'Unauthorized',
  403=>'Forbidden',
  404=>'Not found',
  500=>'Internal server error',
  502=>'Bad gateway',
  503=>'Service unavailable'
);
try
{
  #If the response code is not 200 or 204, we return an error message
 if($code!=200 && $code!=204)
    throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
  die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}

Removing pipelines

The method allows you to remove pipelines one by one or batch.

Removing one pipeline in your account is not possible, if you delete the last pipeline, you get an error “Impossible to delete last pipeline”

Method URL

POST / private / api / v2 / json / pipelines / delete

Parameters

Parameter Type Description
id array The ID of the pipelines you want to delete. You can pass both a single number and an array of numbers.

Example response

{"request":{"id":123}}
{"request":{"id":[123,456]}}

Response parameters

Parameter Description
response// Associative array, where the key is the id of the pipeline, and the value is whether it was possible to remove the pipeline
response//errors If you can not delete the pipeline, the reason will be written here.
server_time Time stamp of the current server time with offset to the time zone of the account (transmitted in timestamp format)

Example response

{
  "response": {
    123: true,
    456: {"errors": "Impossible to delete last pipeline"}
  }
}

Removing the pipeline

To delete a pipeline, you need to describe the array containing the identifier (s) of the pipeline to be removed and put it into an array of the form: $ pipelines [‘request’] [‘id’]

Example integration

$pipelines['request']['id'] = array(123);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account is a subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/private/api/v2/json/pipelines/delete';
/* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
work with this
library you can read in the manual. */
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary parameters for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($pipelines));
curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
  301=>'Moved permanently',
  400=>'Bad request',
  401=>'Unauthorized',
  403=>'Forbidden',
  404=>'Not found',
  500=>'Internal server error',
  502=>'Bad gateway',
  503=>'Service unavailable'
);
try
{
  #If the response code is not 200 or 204, we return an error message
 if($code!=200 && $code!=204)
    throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
  die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}
/**
 * The data is obtained in the JSON format, therefore, to obtain readable data,
 * We will have to translate the response into a format that PHP understands
 */
$Response=json_decode($out,true);
$Response=$Response['response'];
$output = 'Query result:' . PHP_EOL;
foreach ($Response as $pipeline_id => $result) {
  if (isset($result['errors'])) {
    $output .= 'Pipeline "' . $pipeline_id . '" not removed, reason: "' . $result['errors'] . '"' . PHP_EOL;
  } else {
    $output .= 'Pipeline "' . $pipeline_id . '" removed' . PHP_EOL;
  }
}
return $output;

The list of pipelines and stages of sales

Method for obtaining a list of pipelines and stages of sales.

Method URL

GET / api / v2 / pipelines

GET parameters

Parameter Description
id Select the pipeline with the given ID

Response parameters

Parameter Type Description
id int The unique pipeline identifier
name string Pipeline name
sort int Pipeline number for display
is_main bool Is the pipeline the “main”
statuses array An array containing information about the stages of sales
statuses//id int The unique identifier of the step
statuses//name string The name of the phase
statuses//color string Stage color
statuses//sort int Sequence number of the stage when displayed
statuses//is_editable bool Is it possible to change or delete this step
_links array Array containing information about the request
_links/self array An array containing information about the current request
_links/self/href string Relative URL of the current request
_links/self/method string Method of the current request
_embedded array An array containing information adjacent to the query
_embedded/items array An array containing information for each individual element


Colors of the stages of sales

Code Example
#fffeb2 color example
#fffd7f color example
#fff000 color example
#ffeab2 color example
#ffdc7f color example
#ffce5a color example
#ffdbdb color example
#ffc8c8 color example
#ff8f92 color example
#d6eaff color example
#c1e0ff color example
#98cbff color example
#ebffb1 color example
#deff81 color example
#87f2c0 color example
#f9deff color example
#f3beff color example
#ccc8f9 color example
#eb93ff color example
#f2f3f4 color example
#e6e8ea color example

Example response

{
   _links: {
      self: {
         href: "/api/v2/pipelines",
         method: "get"
      }
   },
   _embedded: {
      items: {
         10104: {
            id: 10104,
            name: "Pipeline",
            sort: 1,
            is_main: true,
            statuses: {
               142: {
                  id: 142,
                  name: "Closed - Won",
                  color: "#CCFF66",
                  sort: 10000,
                  is_editable: false
               },
               143: {
                  id: 143,
                  name: "Closed - Lost",
                  color: "#D5D8DB",
                  sort: 11000,
                  is_editable: false
               },
               13667501: {
                  id: 13667501,
                  name: "Initial Contact",
                  color: "#99ccff",
                  sort: 10,
                  is_editable: true
               },
               13667502: {
                  id: 13667502,
                  name: "Negotiations",
                  color: "#ffff99",
                  sort: 20,
                  is_editable: true
               },
               13667503: {
                  id: 13667503,
                  name: "Make a decision",
                  color: "#ffcc66",
                  sort: 30,
                  is_editable: true
               },
               13667504: {
                  id: 13667504,
                  name: "Contract Negotiation",
                  color: "#ffcccc",
                  sort: 40,
                  is_editable: true
               }
            }
         }
      }
   }
}

Example integration

$subdomain='test'; #Our account is a subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/api/v2/pipelines';
/* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about work with this library you can read in the manual. */
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary parameters for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_HTTPHEADER,['Accept: application/json']);
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
curl_close($curl);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
  301=>'Moved permanently',
  400=>'Bad request',
  401=>'Unauthorized',
  403=>'Forbidden',
  404=>'Not found',
  500=>'Internal server error',
  502=>'Bad gateway',
  503=>'Service unavailable'
);
try
{
  #If the response code is not 200 or 204, we return an error message
 if($code!=200 && $code!=204)
    throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
  die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}
/**
 * The data is obtained in the JSON format, therefore, to obtain readable data,
 * We will have to translate the response into a format that PHP understands
 */
$Response=json_decode($out,true);
$Response=$Response['_embedded']['items'];