CRM Leads / Save¶
API CRM Leads / Save is used to save leads from external sources in the While1 Voice CRM.
API URL¶
https://[YOUR-PBX-URL]/api/crm-leads
The data is transmitted by POST or GET and must be of the form:¶
Array
(
[action] => save
[data] => Array
(
[ASDF1234] => Array
(
[properties] => Array
(
[id] => null
[crm_type_id] => 1
[remote_id] => null
[subject] => New API Lead
[contact_name] => John Doe
[contact_email] => test@example.com
[contact_telephone] => 0700000001
[referrer_source] => contact form
)
[custom_fields] => Array
(
[11] => array(1, 3, 4)
[13] => array(1)
[16] => Test company
)
)
)
[api_hash] => 20b093246dac88454f390553e813aa0d
)
The action parameter must have the value save
Parameters:¶
- data: Array with leads
- data - properties: Array with the standard properties of each lead
- data - custom_fields: Array with custom-fields set in CRM Config :: Custom fields of each lead (the keys are the field IDs). Only the fields sent are updated; an empty value clears the field value.
The keys in data (e.g. ASDF1234) are used in the response, for the results and errors of each lead.
Properties:¶
- crm_type_id - required, the ID from CRM Config :: Element types (leads type); it cannot be changed for an existing lead
- subject - required
- project_id - required only if CRM_LEADS_PROJECT_REQUIRED is enabled
- id - the ID of the lead in While1 Voice, for updates
- remote_id - the ID of the lead in your application; if id is missing, the existing lead is looked up by remote_id (and crm_type_id) and updated, otherwise a new lead is created
- contact_id - the ID of the contact in While1 Voice. If it is missing, the contact is looked up by contact_telephone (if contact phone numbers are unique) or contact_email. If it is not found, contact_name and contact_telephone are required (and contact_email, if the contact email is required)
- contact_name, contact_email, contact_telephone - the contact data
- referrer_source, extra_info, comments, reason, source - texts, optional
- due_date - due date (YYYY-MM-DD), optional
- value, currency - the value of the lead; currency is required if value is filled in
- assigned_user_id - the ID of the assigned user, optional
- status - pending (default), prospecting, inprogress, feedback, scheduled, completed, cancelled, lost
Leads are saved independently: if one has errors, the others are saved, and the response contains both results for the saved ones and messages for the errors.
HTTP headers:¶
Content-Type: application/json Authorization: Bearer <token>
Example of parameter generation:
$params = array(
'action' => 'save',
'data' => array(
'ASDF1234' => array(
// Lead properties
'properties' => array(
'id' => '', // will be matched by remote_id if left blank
'crm_type_id' => 1, // ID from CRM Config :: Element types
'remote_id' => null,
'subject' => 'New API Lead',
'contact_name' => 'John Doe',
'contact_email' => 'test@example.com',
'contact_telephone' => '0700000001',
'referrer_source' => 'contact form',
),
// Custom fields (keys are IDs from CRM Config :: Custom fields). Only the specified fields are updated, an empty value clears the field
'custom_fields' => array(
11 => 'source: test',
13 => 'product: test',
16 => 'Test company',
)
)
)
);
Example of hash generation:
$params['api_hash'] = md5(json_encode($params) . 'your_api_key'); // make hash
Example for sending data:
$url = 'https://[YOUR-PBX-URL]/api/crm-leads';
$token = 'your_api_token';
echo curlPost($url, json_encode($params), array("Authorization: Bearer {$token}", "Content-Type: application/json"));
Response¶
If successful:
{
"has_error": false,
"messages": [],
"results": {
"ASDF1234": {
"id": 3,
"contact_id": 23,
"remote_id": null
}
}
}
Or in case of error:
{
"has_error": true,
"messages": [
"Error on Lead update (ASDF1234): Contact ID is required"
],
"results": [ ]
}
Available in other languages: RO