Phonebook Search

Phonebook Search is a service that allows you to obtain information about a person's phone number based on their surname and address. The search process provides details such as whether the landline number exists, if the number is ex-directory, or if no number is available for the given surname at the specified address.

Minimum Requirements

To perform a Phonebook Search, the following minimum inputs are required:

Field	Minimum Requirement	Description
Surname	2 characters	Surname of the data subject.
Full Postcode	5 characters	Full postcode of the address for the data subject
Premise or Building Name	2 characters when using building name	Either premise or building name of the address for the data subject

Service Request

To request a Phonebook Search, include an PHONEBOOK_SEARCH action in the request body entity PeopleActionsRequest. Here is an example snippet of the action:

{
  "actions": [
    {
      "action": "PHONEBOOK_SEARCH"
    }
  ]
}

PeopleActionsRequest

	Array of objects (PersonAction) Actions to run with the given criteria
	object (PersonRequest) Person format used across the Investigate API
	object (Address) Address format used across the Investigate API
cohabitants	Array of strings (Cohabitants) Cohabitants at given address
sourceYears	Array of integers <int32> (SourceYears) [ items <int32 > ] Years when the matching datasets stored by GBG were issued. This could support customers compliance requirements.
tags	Array of strings Free text tags for tracking purposes.

{

• "actions": [

  • {

    • "action": "EMAIL_VERIFICATION"

    }

  ],
• "person": {

  • "firstName": "string",
  • "middleNames": [

    • "James"

    ],
  • "lastNames": [

    • "Smith"

    ],
  • "dateOfBirth": {

    • "day": 31,
    • "month": 12,
    • "year": 1981

    },
  • "gender": "U",
  • "phones": [

    • "+44 207 4281250"

    ],
  • "emails": [

    • "investigate@gbgplc.com"

    ],
  • "ageBand": {

    • "min": 31,
    • "max": 32

    }

  },
• "address": {

  • "premise": "128",
  • "building": "string",
  • "subBuilding": "string",
  • "thoroughfare": "Queen Victoria Street",
  • "locality": "London",
  • "postalCode": "EC4V 4BJ",
  • "country": "GBR"

  },
• "cohabitants": [

  • "John",
  • "Rita M Brown",
  • "Mary Williams"

  ],
• "sourceYears": [

  • 2021,
  • 2022

  ],
• "tags": [

  • "CASE_NUMBER=123",
  • "IMPORTANT"

  ]

}

Service Response

The results of the Phonebook Search request are included in the phonebookSearch property of the PersonActionsResponse entity.

PhonebookSearchActionResponse

	Array of objects (Phonebook) Matched Phonebook numbers.
	object (Meta) Metadata describing the response produced.

{

• "result": [

  • {

    • "phone": "+44 207 4281250"

    }

  ],
• "meta": {

  • "traceId": "7ab2ff08-728a-42e6-aa38-df191ffd4817",
  • "timestamp": "2019-01-04T14:38:25Z",
  • "investigationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0cmFjZUlkIjoiMTIzNDU2IiwibWF0Y2hJZHMiOltdLCJleHAiOjE1MTYyMzkwMjJ9.3SZoV56G0HT289QqP04OT5F1ITtsMqRCGkPok2-st50"

  }

}