Viber Number Lookup API: Check Registration, Name and Avatar

Published August 23, 2026 · UpdatedOctober 16, 2026

Irina reviews onboarding tickets for a consumer lender in Sofia. The mobiles on her desk are mostly Bulgarian, Ukrainian or Greek. A generic messenger check keeps dumping those tickets into the wrong queue: in her markets the inbox that still opens is Viber, and a yes/no flag with no name or photo leaves the agent guessing who she is about to call.

The constraint that actually breaks pipelines is not the phone format. A successful HTTP response is not a registration answer, and a Viber lookup is not a renamed clone of every other number check. You get a three-state registered flag, a public display name, and an avatar URL you can embed in the ticket — if you read the nested envelope instead of trusting the status line.

The inbox that still opens in Eastern Europe

Viber remains the default chat app across large parts of Eastern Europe, Greece, the Philippines and pockets of Southeast Asia. On a US-heavy list that barely matters. On a list from Sofia, Kyiv, Athens or Manila, a reminder, an OTP fallback or a support thread sent to the wrong app sits unread.

That is why this is its own product. The Viber Number Validation API answers three questions that belong together in those regions: is the number registered, which public name sits on the profile, and can you show a photo without a second round of guessing. Other lookups may stop at a boolean. Here the useful artifact is a name plus an image URL an agent can drop into the case.

Copy an authorized platform key from your dashboard after you sign in. Keep it on the server. The key travels in the query string, so redact request URLs in logs, screenshots, exceptions and shared links. Opening this page or copying the examples does not send a data request. Replacing YOUR_API_KEY and running the command does, and that call consumes credits.

The documented example number is 447700900123. Treat it as a placeholder shape — digits, optional leading +, international country code — not a promised live account.

Classify the number with one GET

Start with check. It is the cheap classifier: one GET, one number, no profile payload.

curl --get \
  'https://api.opendata-api.com/api/project/viber/check?key=YOUR_API_KEY' \
  --data-urlencode 'number=447700900123'

A leading + is optional; the API normalizes to digits. Use --data-urlencode (or a real query encoder) so + is not turned into a space.

registered is three-state, and that is the second trap:

  • true — the number is registered on Viber.
  • false — it is not registered.
  • null — undetermined. Timeouts and similar transient failures land here. The message field explains why. Re-queue later. Never count null as “not on Viber”.

Viber replies are wrapped as {"code", "data"}. HTTP status is always 200, even when the number is not registered, because the outcome lives in code and data.registered, not in the status line. The platform wraps that body once more, so in the raw JSON registered sits at data.data.registered. Checking only raise_for_status(), or treating HTTP 200 as “yes”, will mis-label the whole list.

Read the gateway code and message first, then unwrap until you are looking at the object that actually contains registered. The helper below does that unwrap. Comments are in English. Set OPENDATA_API_KEY in the server environment and install requests yourself. Call it only when you intend to spend a credit.

import os
import requests

BASE = "https://api.opendata-api.com/api/project/viber"


def viber_get(operation, **params):
    response = requests.get(
        f"{BASE}/{operation}",
        params={"key": os.environ["OPENDATA_API_KEY"], **params},
        timeout=30,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP failure: {response.status_code}")
    body = response.json()
    if not isinstance(body, dict) or body.get("code") not in (200, "200"):
        raise RuntimeError("Gateway business failure; inspect redacted diagnostics")
    # Viber wraps as {code, data}; the platform wraps once more
    while isinstance(body, dict) and "code" in body and isinstance(body.get("data"), (dict, list)):
        body = body["data"]
    return body

If registered is None, stop and retry later. If it is False, skip enrichment. Only True is worth a name or photo call.

Name and photo without a second guess

When check says registered, two heavier GETs fill the ticket. user-info returns the public display name (viberName), stable identifiers memberId and viberId, a human-readable message, lookup time durationMs, and serverStatus: 1 means registered, 3 means not registered. Use memberId or viberId as the CRM key so a later number change does not fork the contact.

curl --get \
  'https://api.opendata-api.com/api/project/viber/user-info?key=YOUR_API_KEY' \
  --data-urlencode 'number=447700900123'

get-avatar is the piece a boolean lookup never gives you: a photo you can actually embed.

  • signedUrl — a temporary image URL, valid for a few hours, fetchable from any client without the platform key.
  • imageUrl — a stable link for retrieving the current image.
  • imageBase64 / dataUrl — the bytes inlined, ready for an <img> tag.
  • hasImage — false means no public photo, or the account is not registered.
  • The same payload echoes registered, viberName and imageLen (size in bytes).
curl --get \
  'https://api.opendata-api.com/api/project/viber/get-avatar?key=YOUR_API_KEY' \
  --data-urlencode 'number=447700900123'

Do not hotlink signedUrl in production UI. It expires. If the photo has to survive the ticket, download the bytes once and store the file yourself. hasImage=false on a registered account is a missing public photo, not a failed lookup.

Screen the list with check first. Call user-info and get-avatar only for registered=true. That is how you avoid paying for names and photos that cannot exist.

What this API will not tell you

This is a public-profile lookup, not a Viber client.

It will not send messages, read chats, return last-seen or online state, or expose a private photo. It will not map the number to an email, a government ID or a device. viberName is the public display name at request time, not a legal name, and it can change.

signedUrl is not a CDN you can cache for weeks. Persist the file if your product needs the pixels later. An empty name or hasImage=false is valid data, not an error you should retry until it becomes a face.

HTTP 200 is not “registered”. Gateway code is not serverStatus. registered=null is not false. Treat those as three different facts or a list-cleaning job will drop numbers that were only temporarily undetermined.

The API does not rank Viber against other messengers and does not choose which channel to message. In Viber-heavy markets it tells you whether this number has a Viber identity you can show. Outside those markets a miss is a miss — do not invent a profile.

Per-request cost is on pricing. Field-level detail lives on check, user-info and get-avatar. Process only numbers you have a lawful basis to use.