CRM Contacts Save¶
CRM Contacts / Save API is used to save contacts from external sources in the While1 Voice CRM.
API URL¶
https://[YOUR-PBX-URL]/api/crm-contacts
The data is sent via POST or GET and must be of the form:¶
Array
(
[action] => save
[data] => Array
(
[0] => Array
(
[properties] => Array
(
[remote_id] => ASDF1234
[id] =>
[crm_type_id] => 1
[name] => John Doe
[telephones] => Array
(
[0] => 0700000001
[1] => 0700000002
)
[title] =>
[email] =>
[website] =>
[priority] => 0
[direct_line] =>
[address] =>
[start_date] =>
[end_date] =>
[comments] =>
[status] => active
)
[custom_fields] => Array
(
[8] => Acme company // text fields
[9] => Array
(
[0] => 22 // enum fields
)
)
)
)
[api_hash] => 20b093246dac88454f390553e813aa0d
)
The action parameter must have the save value
Parameters:¶
- data: Array with contacts
- data - properties: Array with the standard properties of each contact
- data - custom_fields: Array with custom-fields set in CRM Config :: Custom fields of each contact
The key of each row in data is chosen by you (e.g. the ID from your own CRM) and is used in the response and in the error messages.
Required properties: crm_type_id and name; if id is not sent, remote_id and telephones are also required. Without id, the contact is looked up by remote_id (and crm_type_id): if it exists it is updated, otherwise it is created. For an existing contact, crm_type_id cannot be changed.
Other properties: project_id, title, company, email, website, address, queue_position (position in the queue, 1-254), direct_line, language, assigned_user_id, start_date, end_date, comments, status (active, pending, confirmed, invalid, suspended, deleted).
Each row is processed separately: valid rows are saved even if others have errors.
HTTP Headers:¶
Content-Type: application/json Authorization: Bearer <token>
Example of parameters generation:
$params = array(
'action' => 'save',
'data' => array(
'ASDF1234' => array(
// Contact properties
'properties' => array(
'remote_id' => "ASDF1234", // your own CRM ID
'id' => '', // will be matched by remote_id if left blank
'crm_type_id' => 1, // ID from CRM Config :: Element types
'name' => 'John Doe',
'telephones' => array('0700000001', '0700000002'),
'title' => null,
'email' => null,
'website' => null,
'queue_position' => null,
'direct_line' => null,
'address' => null,
'start_date' => null,
'end_date' => null,
'comments' => null,
'status' => 'active',
),
// Custom fields (Keys are IDs from CRM Config :: Custom fields). If specified, will be deleted, if not, will be ignored
'custom_fields' => array(
8 => 'Acme company', // Company
9 => array(22) // Department
)
)
)
);
Example of hash generation:
$params['api_hash'] = md5(json_encode($params) . 'your_api_key'); // make hash
Example for data sending:
$url = 'https://[YOUR-PBX-URL]/api/crm-contacts';
$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,
"remote_id": "ASDF1234"
}
}
}
Or in case of error (a missing required parameter has the key parameter::row key; the other errors: Invalid element type ID, Invalid contact ID: ..., Error on Contact update (...): ...):
{
"has_error": true,
"messages": {
"telephones::ASDF1234": "Required parameter is missing (ASDF1234): telephones",
"0": "Error on Contact update (QWER5678): The telephone number 0700 is not valid"
},
"results": [ ]
}
Available in other languages: RO