Skip to content

Lookup recipient

GET/recipients/lookup

Check a Telegram username before ordering (optional).

Sandbox: test money only. No request moves real money.

Authenticate with your sandbox key as a bearer token: Authorization: Bearer nbk_test_....

Only a username and a product: whether an account was found at the username and whether the provider refused it for the product. Optional: an order never needs it and never cites it, and it returns no id. product is asked because the provider's search is per product (Telegram Stars or Premium), and it can refuse an account for one and not the other. found: true means an account is at the username, nothing more: it never verifies who owns it, and no Premium status is returned because the provider reports none. A definitive answer is 200: found: false with reason: recipient_not_found, or found: true with eligibility: refused and reason: recipient_not_eligible. A provider that cannot answer is 503 provider_unavailable with Retry-After, never found: false. Draws on the same lookups, lookups_org and lookups_daily buckets as POST /v1/recipient-lookups; a repeated question is answered from this organisation's own recent answer (found within 30 seconds, not found within 60) without asking the provider again. In the sandbox the nasfam_test_ names of x-nb-sandbox-scenarios.lookups choose the answer; Live refuses every one, 422 recipient_not_eligible. On in the sandbox and in Live. Call it from your server.

Request

HeaderValueSent
AuthorizationBearer nbk_test_...Required

No Idempotency-Key is needed: a read changes nothing, so it is safe to send again.

Parameters

FieldDescription
Usernameusername · query string · requiredA username as your customer types it (name, @name, t.me/name); the answer carries it normalised. Pattern ^(?:@|(?:[Hh][Tt][Tt][Pp][Ss]?://)?[Tt]\.[Mm][Ee]/)?[A-Za-z0-9_]{5,32}/?$. Up to 64 characters.
Productproduct · query string · requiredOne of stars, premium, telegram_stars, telegram_premium.
The request in cURL, JavaScript and Python
GET /v1/recipients/lookupSandbox, test key
const response = await fetch('https://sandbox-api.nasfampay.com/v1/recipients/lookup?username=nasfam_test_ok&product=stars', {  headers: {    Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,  },});if (!response.ok) {  const problem = await response.json();  throw new Error(`${problem.status} ${problem.code}: ${problem.title} (request ${problem.request_id})`);}const result = await response.json();console.log(response.status, result);
Code for Request
GET /v1/recipients/lookupSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: check } = await axios.get(    'https://sandbox-api.nasfampay.com/v1/recipients/lookup',    {      params: {        username: 'nasfam_test_ok',        product: 'telegram_stars',      },      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,      },    },  );  console.log(status, check);} catch (error) {  if (!axios.isAxiosError(error) || !error.response) throw error;  const problem = error.response.data;  throw new Error(`${problem.status} ${problem.code}: ${problem.title} (request ${problem.request_id})`);}

Responses

StatusMeaningBody
OK200The provider's answer for this username and product. Headers: RateLimit (draft-ietf-httpapi-ratelimit-headers-11. the same buckets, each "<bucket>";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>. ), RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11. a structured field list with one item per bucket the request drew on (orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org, lookups_daily), each "<bucket>";q=<quota>;w=<window seconds>. no partition key (pk) is sent. ).RecipientCheck object
Too many requests429Too many requests (rate_limited), or your queued orders are at your cap (queue_limit). A bucket that cannot be read at once because of contention is answered here too, never waited on. Honour Retry-After. . Headers: Request-Id, Retry-After (seconds to wait before retrying), RateLimit (draft-ietf-httpapi-ratelimit-headers-11. the same buckets, each "<bucket>";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>. ), RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11. a structured field list with one item per bucket the request drew on (orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org, lookups_daily), each "<bucket>";q=<quota>;w=<window seconds>. no partition key (pk) is sent. ).Problem object
Any other statusdefaultError (RFC 9457). A 503 service_unavailable with Retry-After means the request was not processed: the rate limiter or the database could not answer, and the API refuses rather than serve unlimited (reads included). For a money-moving operation, retrying with the same Idempotency-Key is always safe. . Headers: Request-Id, Retry-After (on 429 and some 503 responses).Problem object

The recipient check object

FieldDescription
Usernameusername · string · requiredThe normalised username, as an order carries it.
Productproduct · string · requiredtelegram_premium is a Telegram Premium subscription for 3, 6 or 12 months, given to the account at the username. An order succeeds only when the provider's own record of our one purchase for it, found by our reference, says it was delivered; a purchase answer, a timeout or an undocumented status is never taken as delivery. Until then the order is processing (or under_review, when people must decide) and its amount stays held. It fails, and the amount is released, only on the provider's documented failure or a two-person decision. One of telegram_stars, telegram_premium.
Foundfound · boolean · requiredThe provider found an account at the username.
Display namedisplay_name · string or null · requiredThe name the provider returned for an account it did not refuse, cleaned of control characters; null otherwise. Up to 64 characters.
Eligibilityeligibility · string · requirednot_refused: the provider did not refuse this account for this product (it states no eligibility of its own). refused: an order would be refused. Tolerate new values. One of not_refused, refused.
Reasonreason · string or null · requiredWhy, when eligibility is refused; null otherwise. Tolerate new values. One of recipient_not_found, recipient_not_eligible, null.

Responses are extensible: ignore fields, enum values and event types you do not know. Any other status is a Problem (see Errors).

Every kind of response
200 OKSynthetic sandbox data
{  "username": "nasfam_test_ok",  "product": "telegram_stars",  "found": true,  "display_name": null,  "eligibility": "not_refused",  "reason": null}
Code for Responses
Response
JSON
200 OKSynthetic sandbox data
{  "username": "nasfam_test_ok",  "product": "telegram_stars",  "found": true,  "display_name": "Sandbox user @nasfam_test_ok",  "eligibility": "not_refused",  "reason": null}
Not found
JSON
200 OKSynthetic sandbox data
{  "username": "nasfam_test_missing",  "product": "telegram_stars",  "found": false,  "display_name": null,  "eligibility": "refused",  "reason": "recipient_not_found"}
Error
JSON
429 Too Many RequestsSynthetic sandbox data
{  "type": "about:blank",  "title": "Too many requests",  "status": 429,  "code": "rate_limited",  "category": "rate_limit",  "detail": "Too many requests. Retry after the time in Retry-After.",  "param": null,  "request_id": "req_01K7SAMP000000000000000090"}

How it behaves

What to expect
AuthenticationYour key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host.
IdempotencyNot needed: a GET changes nothing, so it is safe to send again.
In the sandboxNothing reaches Telegram. A nasfam_test_ username chooses the answer; any other is found, with a test name. See Recipient lookup.
On LiveEvery nasfam_test_ username is refused with recipient_not_eligible. The same request, on the Live host with a live key, which exists only for a workspace activated for Live. See Go live.
FundingNone. This request does not touch your balance.
Status changesNone. It reads, returns no id, and an order never needs it.
Webhook eventsNone.

Error responses

This operation can also answer with provider_unavailable, recipient_not_eligible.

Any request can answer with invalid_request, invalid_api_key, key_expired, key_environment_mismatch, insufficient_scope, rate_limited, service_unavailable, internal_error. Errors says what to do about each one.