Developer Docs

Table of contents

Get contacts

Get a list of existing contacts in the Contact Book of your account with detailed information on each of them. The method also allows you to get contacts from the certain lists that you specified in the query parameters.

To get a contact list, make a request to this URL:


Request parameters

page[limit]NointegerThe number of entries in the response. The value range for the parameter: min – 15, max – 500.
The default is 30.
per[offset]NointegerGet contacts starting from the offset.
groupsNoarray [integer]Index of IDs of the lists for which you want to display contacts.

Response parameters

idintegerContact ID in the BSG personal account, which is generated automatically when a contact is added to the Contact Book
phoneintegerContact’s phone number
fieldsarraycontains embedded custom fields data:
idintegerCustom field ID
valuestringCustom field data
created_atdatetimeDate when the contact was created in the system ― set by the system automatically when a contact is added to the Contact Book. Display format ― Y-m-d H:i:s
groupsarraycontains embedded data of the list where the contact is added
idstringID of the list (generated automatically when creating a contact list) where the contact is added
namestringName of the list where the contact was added
descriptionstringDescription of the list where the contact is added
defaultboolSpecifies whether the contact list is a default one
created_atdatetimeCreation date of the list where the contact was added. Display format ― Y-m-d H:i:s
itemsintegerThe number of numbers in the contact list.
stop_list_countintegerThe number of numbers from the list that are in the stop list of SMS and Viber.
hlr_statusstringStatus of the contact phone number verification against the HLR database. Possible values: sent, absent, active, unknown, failed.
hlr_last_checkdatetimeDate and time when the contact’s phone number was last verified against the HLR database. Display Format ― Y-m-d H:i:s

If request is successful, you will receive a response:

  "data": [
      "id": 1,
      "phone": 33601148802,
      "fields": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "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",
          "items": 11,
          "stop_list_count": 0
      "hlr_status": "string",
      "hlr_last_check": "2022-04-28 14:21:16"
  "total": 0