Signal Number Lookup API: true, false, and null

Published August 23, 2026 · UpdatedOctober 16, 2026

The request did not fail in the access log. GET https://api.opendata-api.com/api/project/signal/check returned HTTP 200, the gateway envelope had code: 200, and the job still wrote not_on_signal. The payload was "registered": null with a timeout in message. That is the failure this Signal number lookup API article is about: an undetermined check delivered as HTTP success, then a pipeline that treated null as no.

Opening this page or copying an example does not send a lookup. Running a command does, and it spends credits. Keep the authorized platform key out of logs, screenshots and source control. Sign in, copy a key from the dashboard, and read it from OPENDATA_API_KEY on the server (curl examples use the YOUR_API_KEY placeholder). Query URLs carry the key, so do not paste them into tickets.

A null is not a no

check is the light call. It takes number in international form, with or without a leading +, and normalizes to digits. Always include the country code. After a successful gateway unwrap, the record you classify is the number, its e164 form, and registered.

registered is three-state:

  • true — the number is a registered Signal account.
  • false — it is not registered. That is a clean miss. Do not retry it as a timeout.
  • null — the answer could not be determined. message says why (a timeout is the usual case). Queue it. Do not store it as unregistered.

HTTP status and gateway status are not the same layer as registered. A missing or unauthorized key, a validation error, or a transport failure shows up as HTTP 4xx/5xx or as a gateway code other than 200. There is no Signal verdict in that envelope — fix credentials or retry transport; do not write false. HTTP 2xx with gateway code: 200 means the check was delivered. Only then read registered. A delivered null is still a business result: undetermined, not a crash.

The bug that produces the opening failure is almost always truthiness. None is falsy, and so is False:

# Wrong: null and false both look like "no"
if not payload.get("registered"):
    mark_unregistered(number)

Diagnose with identity checks (is True, is False, is None), never with if registered. Classify the inner record before you enqueue anything:

def classify_registered(registered):
    if registered is True:
        return "registered"
    if registered is False:
        return "not_registered"
    if registered is None:
        return "undetermined"
    return "malformed"

A reply can be wrapped more than once as {"code": ..., "data": {...}}. Unwrap until you are looking at the inner record. The number below is a documented example shape, not a guaranteed hit.

curl --get "https://api.opendata-api.com/api/project/signal/check" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "number=15551234567"

Registration, then ACI and PNI

user-info is the identity call. It still takes number. When the account is registered it can return the public identity: ACI (Account Identifier, a UUID) and PNI (Phone Number Identifier, usually PNI:<uuid>), plus optional plaintext metadata such as identityKey, unrestrictedUnidentifiedAccess, capabilities and badges. It also returns a machine-readable status (for example found, not_found, timeout), a human-readable message, and durationMs.

Call it only after check returned registered is True. A clean false has no identity to fetch. A null is not permission to enrich — you still do not know whether the number is on Signal. Spending user-info on those rows burns credits and mixes timeouts with misses in your store.

When fieldsEncrypted is true, Signal is withholding display name, about text and avatar because they are end-to-end encrypted with a profile key that only the person's contacts hold. That is a privacy property of Signal, not a gap in the lookup. Do not ship a feature that promises a name or photo for strangers.

If you already stored an ACI, profile refreshes public metadata without resolving the phone number again. It returns plaintext fields only: identityKey, unidentifiedAccess, unrestrictedUnidentifiedAccess, capabilities, badges and uuid (the same value as the ACI). Name, about and avatar are never present on this path for non-contacts. Keep the ACI even when the phone number later changes.

curl --get "https://api.opendata-api.com/api/project/signal/user-info" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "number=15551234567"

curl --get "https://api.opendata-api.com/api/project/signal/profile" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "aci=3bc3a597-297d-4f8c-821a-13aaa9ede5ea"

Those URLs are request shapes. They are not a promise that 15551234567 is registered or that the sample ACI still exists.

Retry only the undetermined rows

Production lists fail in batches. Split every check row into three buckets and give each bucket one policy:

  • true — persist registered, then call user-info once if you need ACI/PNI. Cache by number with a timestamp. Do not re-check on every page view.
  • false — persist not registered. A clean miss is finished work. Revisit on a schedule if the list is long-lived, not because the last HTTP status was 200.
  • null — persist undetermined plus message. Retry check only, with backoff. Cap attempts. If it is still null, leave it undetermined. Never promote it to false to close the ticket.

Do not retry HTTP 401/403 as if they were timeouts. Do not retry a gateway failure that is a bad key or a missing number. Those will not become true because you slept two seconds.

import os
import time

import requests

BASE = "https://api.opendata-api.com/api/project/signal"
KEY = os.environ["OPENDATA_API_KEY"].strip()


def get(operation, **params):
    try:
        response = requests.get(
            f"{BASE}/{operation}",
            params={"key": KEY, **params},
            timeout=30,
        )
    except requests.RequestException:
        raise RuntimeError("Transport failure; inspect redacted logs") from None
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP failure: {response.status_code}")
    body = response.json()
    while isinstance(body, dict) and "code" in body and isinstance(
        body.get("data"), (dict, list)
    ):
        if body.get("code") != 200:
            raise RuntimeError(f"Gateway failure: {body.get('message')}")
        body = body["data"]
    return body


def lookup(number, retries=2):
    last_message = None
    for attempt in range(retries + 1):
        data = get("check", number=number)
        registered = data.get("registered")
        if registered is True:
            return {
                "number": number,
                "registered": True,
                "identity": get("user-info", number=number),
            }
        if registered is False:
            return {"number": number, "registered": False}
        last_message = data.get("message")
        time.sleep(2 * (attempt + 1))
    return {"number": number, "registered": None, "reason": last_message}


# Documented example number — not a guaranteed registration.
print(lookup("15551234567"))

Only the three-state value drives control flow. Store other fields as returned so a missing badges array does not abort the batch. After retries, registered is None is an honest leftover, not a defect in the helper.

Where this sits next to WhatsApp and Telegram

Signal answers registration and stable identifiers. It does not answer "what is this person's display name." WhatsApp and Telegram expose different public surfaces, so a Signal null is not a reason to skip those checks, and a Signal true is not a reason to skip them either.

Use check when the question is only whether the number is on Signal. Use user-info when you need ACI/PNI for deduplication. For Viber presence, see the Viber number lookup. For Telegram existence, handle, bio and avatar via a 24-hour userHash, see the Telegram number checker. When several channels must be decided together, follow the lead verification workflow.

Because Signal withholds profile details from non-contacts by design, treat this lookup as a registration and identity signal, not as a profile-enrichment source. Operation references: check, user-info, profile. Product page: Signal Number Validation. Per-request cost: pricing.