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. choose the answer; Live refuses every one, 422 recipient_not_eligible.
On in the sandbox and in Live. Call it from your server.
Request
| Header | Value | Sent |
|---|---|---|
Authorization | Bearer nbk_test_... | Required |
No Idempotency-Key is needed: a read changes nothing, so it is safe to send again.
Parameters
| Field | Description |
|---|---|
| Usernameusername · query string · required | A username as your customer types it (name, @name, t.me/name); the answer carries it normalised. Pattern ^(?:@|(?:[Hh][Tt][Tt][Pp][Ss]?:/. Up to 64 characters. |
| Productproduct · query string · required | One of stars, premium, telegram_stars, telegram_premium. |
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);// 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
| Status | Meaning | Body |
|---|---|---|
| OK200 | The 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 requests429 | Too 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 statusdefault | Error (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
| Field | Description |
|---|---|
| Usernameusername · string · required | The normalised username, as an order carries it. |
| Productproduct · string · required | telegram_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 · required | The provider found an account at the username. |
| Display namedisplay_ | The name the provider returned for an account it did not refuse, cleaned of control characters; null otherwise. Up to 64 characters. |
| Eligibilityeligibility · string · required | not_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 · required | Why, 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).
{ "username": "nasfam_ test_ ok", "product": "telegram_ stars", "found": true, "display_ name": null, "eligibility": "not_ refused", "reason": null}{ "username": "nasfam_ test_ ok", "product": "telegram_ stars", "found": true, "display_ name": "Sandbox user @nasfam_ test_ ok", "eligibility": "not_ refused", "reason": null}{ "username": "nasfam_ test_ missing", "product": "telegram_ stars", "found": false, "display_ name": null, "eligibility": "refused", "reason": "recipient_ not_ found"}{ "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 | |
|---|---|
| Authentication | Your key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host. |
| Idempotency | Not needed: a GET changes nothing, so it is safe to send again. |
| In the sandbox | Nothing reaches Telegram. A nasfam_test_ username chooses the answer; any other is found, with a test name. See Recipient lookup. |
| On Live | Every 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. |
| Funding | None. This request does not touch your balance. |
| Status changes | None. It reads, returns no id, and an order never needs it. |
| Webhook events | None. |
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.
