Implemented API method

POST /api/v4/leads/complex

Official documentation of the method

Description

The method allows you to add transactions with a contact and a company to an account in batches. The added data can be checked in duplicate control.

Restrictions

• The method is available according to the user's rights.
• For one transaction, you can specify no more than 1 associated contact and 1 associated company.
• For added entities (transaction, contact, company), you can pass no more than 40 values of additional fields.
• The data being added participates in duplicate control if it is enabled for integration that adds data.
• The method does not deduplicate the transmitted data, but only searches for duplicates among the already added data.
• No more than 50 transactions can be transferred per request.
• When creating a new contact and company, they will be linked together.

Parameters

Return values

HTTP 200 Successful response

The return value corresponds to the amoCRM documentation for this method.

Sample response

stdClass Object
(
    [0] => stdClass Object
        (
            [id] => 21674949
            [contact_id] => 33860727
            [company_id] => 
            [request_id] => Array
                (
                    [0] => 0
                )

            [merged] => 
        )

)

HTTP 40x Failed response

The official documentation says about a possible response code 401 The user is not authorized. The WT Amocrm library returns an error object of the following structure:

stdClass Object
(
    [error_code] => 400
    [error_message] => createLeadsComplex function: Error while trying to create lead in Amo CRM. Amo CRM API response: <b>request_id</b>: 0
<b>code</b>: FieldMissing
<b>path</b>: _embedded.metadata.form_id
<b>detail</b>: This field is missing.
<b>title</b>: Bad Request
<b>type</b>: https://httpstatus.es/400
<b>status</b>: 400
<b>detail</b>: Request validation failed
)

Code example

This code example is taken from the plugin WT amoCRM - RadicalForm. In the PHP code example, an array of lead data is prepared according to the amoCRM documentation and transmitted by the createLeadComplex method:

use Joomla\CMS\Date\Date;
use Webtolk\Amocrm\Amocrm;
	
$lead_data = [
	'created_by' => 0, //The ID of the amoCRM user creating the transaction. When the value 0 is passed, the transaction will be considered created by the robot. The field is optional
];

// Lead name in AmoCRM
if (isset($input["rfSubject"]) && (!empty($input["rfSubject"])))
{
	$lead_data['name'] = $input["rfSubject"];

}
else
{
	$lead_data['name'] = $params->get('rfSubject');
}

if (isset($input['pipeline_id']) && (!empty($input['pipeline_id'])))
{
	$lead_data['pipeline_id'] = $input['pipeline_id'];
}
elseif (!empty($this->params->get('pipeline_id')))
{
	$lead_data['pipeline_id'] = $this->params->get('pipeline_id');
}

if (!empty($this->params->get('status_id')))
{
	$lead_data['status_id'] = $this->params->get('status_id');
}

$lead_data['_embedded']['metadata'] = [
	'category'     => 'forms',
	'form_id'      => (isset($input['form_id']) && !empty($input['form_id'])) ? $input['form_id']: 1,
	'form_name'    => (isset($input['rfSubject']) && !empty($input['rfSubject'])) ? $input['rfSubject']: 'Call back from site',
	'form_page'    => $input['url'],
	'form_sent_at' => (new Date('now'))->toUnix(),
];


//  URL of refferer page
if (isset($input["url"]) && (!empty($input["url"])))
{
	$lead_data['_embedded']['metadata']['referer'] = $input['url'];
}
$contact = [];


if (isset($input["name"]) && (!empty($input["name"])))
{
	$contact['first_name'] = $input['name'];
}
//  Process form data
foreach ($clear as $key => $value)
{

	if ($key == "PHONE" || $key == "phone")
	{
		$phones = [
			'field_code' => 'PHONE',
			'values'     => []
		];
		/*
		 * If any phone numbers or emails are found
		 */
		if (is_array($value))
		{

			foreach ($value as $phone)
			{
				$phones['values'][] = [
					'enum_code' => 'WORK',
					'value'     => $phone
				];

			}//end FOREACH


		}
		else
		{
			/**
			 * Single email or phone number
			 */
			$phones['values'][] = [
				'enum_code' => 'WORK',
				'value'     => $value
			];
		}
		$contact['custom_fields_values'][] = $phones;
		/*
		 * Other form data. Not email or phone
		 */
	}
	elseif ($key == "EMAIL" || $key == "email")
	{
		$emails = [
			'field_code' => 'EMAIL',
			'values'     => []
		];
		/*
		 * If any phone numbers or emails are found
		 */
		if (is_array($value))
		{

			foreach ($value as $email)
			{
				$emails['values'][] = [
					'enum_code' => 'WORK',
					'value'     => $email
				];

			}//end FOREACH


		}
		else
		{
			/**
			 * Single email or phone number
			 */
			$emails['values'][] = [
				'enum_code' => 'WORK',
				'value'     => $value
			];
		}
		$contact['custom_fields_values'][] = $emails;
		/*
		 * Other form data. Not email or phone
		 */
	}
}//end foreach Process form data

if(!empty($this->params->get('radicalform_to_amocrm_lead_custom_fields'))){
	foreach ($this->params->get('radicalform_to_amocrm_lead_custom_fields') as $key => $value){
		$radical_form_field_name = $value->radical_form_field_name;

		if(array_key_exists($radical_form_field_name,$input) && !empty($input[$radical_form_field_name])){

			$lead_custom_field_array = [
				'field_id' => (int) $value->lead_custom_field_id,
				'values'     => [
					[
						'value' => $input[$radical_form_field_name]
					]
				]
			];
			$lead_data["custom_fields_values"][] = $lead_custom_field_array;
		}
	}
}

$lead_data['_embedded']['contacts'][] = $contact;


if ($this->params->get('lead_tag_id', 0) > 0)
{
	$lead_data['_embedded']['tags'][0]['id'] = (int) $this->params->get('lead_tag_id');
}

/**
 * Add UTMs into array
 */

$lead_data = $this->checkUtms($lead_data);
$leads[]   = $lead_data;

/**
 * Create a lead
 */
$amocrm = new Amocrm();
$result = $amocrm->createLeadsComplex($leads);