Create recipient lookup
POST/recipient-lookups
Look up a Telegram recipient before quoting.
Sandbox: test money only. No request moves real money.
Authenticate with your sandbox key as a bearer token: Authorization: Bearer nbk_test_..
Resolves a username to the account the provider found there: its display name and photo, exactly as returned (null where the provider returned none), for your customer to confirm before you quote. Read-only: it never charges, reserves, prices or delivers anything. Cite the lookup's id as recipient_lookup in POST /v1/quotes; it is valid until expires_at (10 minutes) and only for the same username, product and selection.
found: true means the provider found an account at that username. It does not verify who the account belongs to: show the name and photo and let your customer confirm. A provider that cannot answer is 503 provider_unavailable (retry after Retry-After), never recipient_not_found.
Draws on the lookups (per key), lookups_org and lookups_daily (per organisation) buckets, not on the quote buckets. No Idempotency-Key: a repeated lookup is answered from the organisation's own recent answer for the same username, product and selection (found within 30 seconds, not found within 60) without asking the provider again.
In the sandbox the nasfam_test_ names in x-nb-sandbox-scenarios. choose the answer. In Live every nasfam_test_ name is refused 422 recipient_not_eligible.
When Nasfam turns real lookups on in the sandbox, any other username is looked up through the provider's read-only search (lookup_source: provider), within tighter limits: 20 per key or member every 10 minutes, 60 per organisation an hour and 300 a day (429 rate_limited with Retry-After); the quote and the order that follow stay synthetic. Otherwise the sandbox's simulator answers (lookup_source: simulated).
Call it from your server: the secret key never goes to a browser or an app.
Request
| Header | Value | Sent |
|---|---|---|
Authorization | Bearer nbk_test_... | Required |
Content-Type | application/json | Required |
Body
One of 2 shapes. Unknown fields are rejected.
product is telegram_stars
| Field | Description |
|---|---|
| Productproduct · string · required | Always telegram_stars. |
| Telegram usernametelegram_ | A username as a customer types it: name, @name, t.me/name, or that link with its scheme. Normalised server-side (the @ or link removed, lower-cased); the answer carries the normalised username. Pattern ^(?:@|(?:[Hh][Tt][Tt][Pp][Ss]?:/. Up to 64 characters. |
| Quantityquantity · integer · required | The quantity you will quote; bounded further by the offer configuration. Telegram Stars are 50 to 100,000 per order; GET /products gives the maximum in force. Above it the request is refused (400 invalid_request at /quantity), never split: for more, place several orders, each with its own quote and Idempotency-Key. 1 to 1000000. |
product is telegram_premium
| Field | Description |
|---|---|
| Productproduct · string · required | Always telegram_premium. |
| Telegram usernametelegram_ | A username as a customer types it: name, @name, t.me/name, or that link with its scheme. Normalised server-side (the @ or link removed, lower-cased); the answer carries the normalised username. Pattern ^(?:@|(?:[Hh][Tt][Tt][Pp][Ss]?:/. Up to 64 characters. |
| Monthsmonths · integer · required | One of 3, 6, 12. |
const response = await fetch( 'https:// sandbox-api. nasfampay. com/ v1/ recipient-lookups', { method: 'POST', headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, 'Content-Type': 'application/ json', }, body: JSON. stringify( { product: 'telegram_ stars', telegram_ username: 'nasfam_ test_ ok', quantity: 50, }),});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);Look up a recipient
// npm install axiosimport axios from 'axios';try { const { status, data: lookup } = await axios. post( 'https:// sandbox-api. nasfampay. com/ v1/ recipient-lookups', { product: 'telegram_ stars', telegram_ username: 'nasfam_ test_ ok', quantity: 50, }, { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, lookup);} 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})`);}Look up a Premium recipient
// npm install axiosimport axios from 'axios';try { const { status, data: lookup } = await axios. post( 'https:// sandbox-api. nasfampay. com/ v1/ recipient-lookups', { product: 'telegram_ premium', telegram_ username: '@nasfam_ test_ ok', months: 3, }, { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, lookup);} 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 |
|---|---|---|
| Created201 | An account was found at the username. 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.
). | RecipientLookup object |
| Content too large413 | The request body is over 16 KB (payload_too_large). Refused before authentication; nothing is read further. Headers: Request-Id. | Problem 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 lookup object
| Field | Description |
|---|---|
| IDid · string · required | Pattern ^rlk_[0-9A-HJKMNP-TV-Z]{26}$. |
| Foundfound · boolean · required | An account was found at the username. A lookup that finds nobody is 422 recipient_not_found. Always true. |
| Resolution statusresolution_ | How the username resolved. Every other resolution is a Problem with its own code: recipient_not_found, recipient_not_eligible, provider_unavailable. Always found. |
| Product eligibilityproduct_ | The provider did not refuse this account for this product and selection. It states no eligibility of its own, so this is not a promise of delivery: a refusal at purchase fails the order and releases its hold. An account the provider refuses is 422 recipient_not_eligible. Always not_refused. |
| Telegram usernametelegram_ | The normalised username, as quotes and orders carry it. |
| Display namedisplay_ | The name the provider returned, cleaned of control characters; null when it returned none. Up to 64 characters. |
| Photo URLphoto_ | An https URL of the profile photo on a Telegram image host, as returned; null when the provider returned none or anything else. Load it in an image element only; it may stop working after expires_at. Up to 2048 characters. |
| 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. |
| Selectionselection · Selection object · required | |
| Quantityselection. | |
| Monthsselection. | |
| Expires atexpires_ | Until when a quote may cite this lookup. Format date-time. |
| Created atcreated_ | Format date-time. |
| Lookup sourcelookup_ | Who answered the lookup. provider: the Telegram provider's read-only search found this account (always in Live; in the sandbox while real lookups are on, for any username that is not a nasfam_test_ scenario). simulated: the sandbox's simulator answered, and the account is a sample. In the sandbox the quote, the order and its delivery are synthetic either way: nothing is bought or sent to Telegram. Tolerate new values. One of provider, simulated. |
Responses are extensible: ignore fields, enum values and event types you do not know. Any other status is a Problem (see Errors).
{ "id": "rlk_ 01K7SAMP000000000000000001", "found": true, "resolution_ status": "found", "product_ eligibility": "not_ refused", "telegram_ username": "nasfam_ test_ ok", "display_ name": null, "photo_ url": null, "product": "telegram_ stars", "selection": { "quantity": 50, "months": 3 }, "expires_ at": "2026-10-10T10:05:02Z", "created_ at": "2026-10-10T10:05:02Z", "lookup_ source": "provider"}{ "id": "rlk_ 01K7SAMP000000000000000090", "found": true, "resolution_ status": "found", "product_ eligibility": "not_ refused", "telegram_ username": "nasfam_ test_ ok", "display_ name": "Sandbox user @nasfam_ test_ ok", "photo_ url": null, "lookup_ source": "simulated", "product": "telegram_ stars", "selection": { "quantity": 50 }, "expires_ at": "2026-10-10T10:25:00.000Z", "created_ at": "2026-10-10T10:15:00.000Z"}{ "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"}{ "type": "about:blank", "title": "Recipient not found", "status": 422, "code": "recipient_ not_ found", "category": "validation", "param": "/ telegram_ username", "request_ id": "req_ 01K7SAMP000000000000000091"}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 | Takes no key. |
| In the sandbox | Nothing reaches Telegram. A nasfam_test_ username chooses the answer; any other is found, with a test name and no photo. 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, and a quote may cite it until its expires_at. |
| Webhook events | None. |
For telegram_stars: One order sends 50 to 100,000 Stars. For more, up to 1,000,000 Stars, place several orders. Each one is quoted and confirmed on its own. GET /products holds the bounds in force.
Error responses
This operation can also answer with recipient_not_found, recipient_not_eligible, product_unavailable, provider_unavailable, payload_too_large, unknown_field.
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.
