How the Number Lookup API Works

This is an API used to connect a number provider to our number lookup service.

Intended audience

This API is designed for third-party phone number information providers.

This includes phone book services, spam detection services, and any other services that offer insights about phone numbers.

Usage

When you integrate as a number information provider, you'll receive a lookup request that contains a phone number. Your task will be to classify them and provide a display name lookup.

The information you provide will assist the core in enhancing the call experience, such as setting the display name for incoming calls.

Including display name as part of call setup

Get number information from provider

When a subscriber receives a call over VoLTE, we will check if there is any configured Number Lookup Providers for the subscriber.

incoming call, triggers looking for available providers

During call setup a number lookup request will be sent to each of the enabled Number Lookup Providers, if any.

core sends request to provider, gets response back, forwards display name to subscriber

Show display name

If we have received any display name from the providers, we will show it to the subscriber.

This will be visible in the call screen, as seen in the image below where the display name is "Potential Spam".

potential spam on mobile phone call screen

Note: If the phone has the number stored as a contact, the phone will typically use this.

Error handling

If the provider returns a empty display name (no hit in the phonebook) or fails to respond within the deadline, the call will be displayed as usual.

If there are no healthy connections for the provider, the provider will be ignored.

Results will be cached for a period of time to avoid unnecessary requests and latency.

Should the provider fail to respond within the set deadline, it will be treated as if it returned an empty result.

For upstream errors, the provider must return an error, accompanied by a descriptive, human-readable message.

Flow

The API is implemented as a bidirectional gRPC service, where the provider responds to requests from the server.

The Number Provider sets up one or more connections to our API. This connection should use keep-alive, and has a max connection age of one hour +/- a 10 % jitter. Once max connection age is reached, or any exception occurs, the connection should be re-established.

Note: Although the connection is set up from the provider to the core, all requests are initiated from the core.

provider client contacts the core to enable gRPC stream

Using round-robin, the core will send number lookup requests over these connections for which the provider will respond with the display name.

Responses will be cached for a period of time to avoid unnecessary requests and latency.

sequence diagram showing caching of display name

Request / Response

For matching the response to the original request, the provider must include the original request in the response.

The returned display name may be empty if the provider does not have a display name for the number, and may be cached for the duration specified.

Request

NumberLookupRequest {
  id: "opaque string"
  number {
    e164: "+1234567890"
  }
}

Response

NumberLookupResponse {
  number_lookup_request { } # Fields omitted for brevity

  result {
    name: "John Doe"
  }
}

Response, upstream error

NumberLookupResponse {
  number_lookup_request { } # Fields omitted for brevity

  error {
    message: "Database unavailable"
  }
}