Skip to content

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.lookups 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

HeaderValueSent
AuthorizationBearer nbk_test_...Required
Content-Typeapplication/jsonRequired

Body

One of 2 shapes. Unknown fields are rejected.

product is telegram_stars

FieldDescription
Productproduct · string · requiredAlways telegram_stars.
Telegram usernametelegram_username · string · requiredA 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]?://)?[Tt]\.[Mm][Ee]/)?[A-Za-z0-9_]{5,32}/?$. Up to 64 characters.
Quantityquantity · integer · requiredThe 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

FieldDescription
Productproduct · string · requiredAlways telegram_premium.
Telegram usernametelegram_username · string · requiredA 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]?://)?[Tt]\.[Mm][Ee]/)?[A-Za-z0-9_]{5,32}/?$. Up to 64 characters.
Monthsmonths · integer · requiredOne of 3, 6, 12.
The request in cURL, JavaScript and Python
POST /v1/recipient-lookupsSandbox, test key
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);
Code for Request

Look up a recipient

POST /v1/recipient-lookupsSandbox, test key
// 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

POST /v1/recipient-lookupsSandbox, test key
// 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

StatusMeaningBody
Created201An 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 large413The request body is over 16 KB (payload_too_large). Refused before authentication; nothing is read further. Headers: Request-Id.Problem 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 lookup object

FieldDescription
IDid · string · requiredPattern ^rlk_[0-9A-HJKMNP-TV-Z]{26}$.
Foundfound · boolean · requiredAn account was found at the username. A lookup that finds nobody is 422 recipient_not_found. Always true.
Resolution statusresolution_status · string · requiredHow 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_eligibility · string · requiredThe 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_username · string · requiredThe normalised username, as quotes and orders carry it.
Display namedisplay_name · string or null · requiredThe name the provider returned, cleaned of control characters; null when it returned none. Up to 64 characters.
Photo URLphoto_url · string or null · requiredAn 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 · 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.
Selectionselection · Selection object · required
Quantityselection.quantity · integer
Monthsselection.months · integer
Expires atexpires_at · string · requiredUntil when a quote may cite this lookup. Format date-time.
Created atcreated_at · string · requiredFormat date-time.
Lookup sourcelookup_source · string · requiredWho 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).

Every kind of response
201 CreatedSynthetic sandbox data
{  "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"}
Code for Responses
Response
JSON
201 CreatedSynthetic sandbox data
{  "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"}
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"}
Not found
JSON
422 Unprocessable ContentSynthetic sandbox data
{  "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
AuthenticationYour key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host.
IdempotencyTakes no key.
In the sandboxNothing reaches Telegram. A nasfam_test_ username chooses the answer; any other is found, with a test name and no photo. 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, and a quote may cite it until its expires_at.
Webhook eventsNone.

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.