Developer Docs

Table of contents

Contact search

Method for searching contacts in the Contact Book. In the search, it is possible to use operations: like, =, >, >=, <, <=.

Search is possible by the following fields: 

  • id:  =, >, >=, <, <=
  • phone: like, =
  • {field_id}:
    • for field with “Text” type: like, =
    • for field with “Number” type:  =, >, >=, <, <=
    • for field with “Date” type: =, >, >=, <, <=

To make contact search, send a request to this URL:


Request parameters:

page[offset]Noint0Get contacts starting from offset
page[limit]Noint50Number of contacts in response
sortNostringidSort by conditions: id, phone
wayNostringascSorting options: asc, desc
search[operation]Nostring=Operator for finding values: like, =, >, >=, <, <=
search[field]NostringnoField for search. Possible values: id, phone, group_id, date, {field_id}
{field_id} – custom field ID; can be got from GET /api/contacts/fields
search[value]Value for search:Nostringno
idContact ID
phoneContact phone number. 9 to 15 digits.
dateContact creation date in ISO 8601 format
{field_id}Value specified in the contacts field

Response parameters:

idintegerContact ID
phoneintegerContact phone number
fieldsContains nested custom field parameters
created_atdatetimeContact creation date – set automatically by the BSG system when adding a contact to the Contact Book. Format ISO 8601 yyyy-mm-dd hh:mm:ss
groups – contains nested parameters of the list to which the contact is added:
idstringID of the contact list to which the contact is added
namestringName of the contact list to which the contact is added
descriptionstringDescription of the contact list to which the contact is added
defaultbooleanSpecifies whether the list is the default
created_atdatetimeDate of creation/editing of the list to which the contact was added. Format ISO 8601 yyyy-mm-dd hh:mm:ss
hlr_statusstringStatus of checking the contact’s phone number in HLR. Possible values: barred, absent, active, unknown, failed.
hlr_last_checkdatetimeDate and time when the contact’s phone number was last checked in HLR. Format ISO 8601 yyyy-mm-dd hh:mm:ss

If the request is successful, you will receive a response:

  "data": [
      "id": 1,
      "phone": 33601148802,
      "fields": [
          "code": 0,
          "text": "string"
      "created_at": "2022-04-28 14:21:16",
      "groups": [
          "id": 1,
          "name": "string",
          "description": "string",
          "default": 0,
          "created_at": "2022-04-28 14:21:16"
      "hlr_status": "string",
      "hlr_last_check": "2022-04-28 14:21:16"
  "meta": {
    "page": {
      "total": 1,
      "limit": 50,
      "offset": 0
    "search": {
      "field": 0,
      "operation": "like",
      "value": "string"