Number Lookup API - Technical Guide

This guide will show you how to set up a Number Lookup Provider.

You should have an understanding of how this works before continuing, see Overview.


This guide assumes you are able to create a OAuth 2.0 client and get an access token.

See Get client access token for how to get the access token.

For testing using our sandbox endpoint or the local test application, authentication headers may be skipped.

Required scope


How to use the API

When you connect to this API, you will get a stream of number lookup requests for which you should respond with information about the number.


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.

Although the connection is set up from the provider to wg2, all requests are initiated from wg2.

Using round-robin, wg2 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.

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.


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


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"

Limitations for display name

The display name returned must be max 60 characters, and may only contain the following:

  • alphanumeric (a-z, A-Z, 0-9)
  •  (space), -, _
  • ., !, %, *, ', +, ~, `

Characters not matching the above will be stripped.

Error handling

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

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.


As part of the response, the provider can include a cache TTL.

This is the time in seconds that the display name should be cached on the wg2 side. If not set, a default cache TTL documented in the proto file will be used.

NumberLookupResponse {
  number_lookup_request { } # Fields omitted for brevity

  result {
    name: "John Doe"

  # Optional, set to default if not set
  cache_control {
    max_age {
      seconds: 3600  # 1 hour, google.protobuf.Duration
keep-alive period1 minuteMust be ≥ 1 minute and ≤ 5 minutes
keep-alive timeout10 seconds
permit keep-alive without callstrue


The API Gateway hosting api.{region} (see environments for list of regions) will silently drop connections if they have been idle for 350 seconds (5m 50s).

To avoid this, the provider should send a keep-alive message every minute.

Local testing

For local testing, you can use our sandbox environment hosted at

In addition to that, we do provide a test application that can be used for testing which may be useful to see how your provider behaves under heavy load.

The test application is hosted at

By setting up a stream to this application, it will send number lookup requests at the configured rate. It will not do any flow control, but show number of in-flight messages (requests sent - responses received).


The test application is also available as a pre-built docker image. Usage:

docker run --network=host \
    --address :8118 \
    --rps 5 \
    --numbers 4799990001,4799990002,4799990003 \
    --print-progress \
    --print-requests \

Continue reading