Project

General

Profile

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