Skip to content

Recipient lookup and confirmation

Show your customer the Telegram account behind a username, with its name and photo, before you quote Stars or Premium.

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

A recipient lookup resolves a Telegram username to the account found there: its display name and, when available, its profile image. Your customer sees the account and confirms it before you quote, so an order never goes to a mistyped username. It works for Telegram Stars and Telegram Premium, is read-only, and moves no money.

Availability: Available. Live and verified in production. Nothing reaches Telegram there: the test usernames choose the answer. A lookup is recommended and not required: without one, a quote checks the recipient itself.

What you send

Send the selection you will quote, because the answer is for one product and selection. Call it from your server, as every request.

FieldDescription
Productproduct · string · requiredtelegram_stars or telegram_premium.
Telegram usernametelegram_username · string · requiredThe username as your customer types it: name, @name, or a t.me/name link, with or without its scheme: 5 to 32 letters, digits and underscores. It is normalised for you, and the answer carries the normalised form.
Quantityquantity · integerStars only, and required for Stars: the quantity you will quote.
Monthsmonths · integerPremium only, and required for Premium: 3, 6 or 12, the months you will quote.

There is no Idempotency-Key: a repeated lookup of the same username, product and selection is answered from your own recent answer without asking the provider again (an account found within 30 seconds, nobody found within 60). It draws on its own rate limit buckets, lookups per key and lookups_org and lookups_daily per organisation, not on the quote buckets.

Code for What you send
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})`);}

What it returns

201 Created with the account found:

FieldDescription
IDid · string · requiredThe recipient reference: rlk_ and 26 characters. Cite it as recipient_lookup when you quote. It is your organisation's alone and bound to this username, product and selection.
Foundfound · boolean · requiredAlways true: an account was found at the username. It does not say who the account belongs to.
Resolution statusresolution_status · string · requiredThe lookup status. Always found on a 201; every other outcome is an error with its own code, below.
Product eligibilityproduct_eligibility · string · requiredAlways not_refused: the provider did not refuse this account for this product and selection. It is not a promise of delivery.
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, at most 64 characters. Null when it returned none.
Photo URLphoto_url · string or null · requiredThe profile image, when available: an https address on a Telegram image host. Null when the provider returned none, or returned anything else. Load it in an image element only, and draw initials when it is null.
Productproduct · string · requiredThe product you looked up for.
Selectionselection · object · requiredThe quantity or months you looked up for.
Expires atexpires_at · string · requiredUntil when a quote may cite this lookup: 10 minutes after it was made.
Created atcreated_at · string · requiredWhen the lookup was made.
Lookup sourcelookup_source · string · requiredWho answered: provider, the Telegram provider's read-only search (always on Live, and on the sandbox while Nasfam has real lookups on, for any name outside nasfam_test_), or simulated, the sandbox's simulator, whose account is a sample. On the sandbox the quote, the order and its delivery stay synthetic either way.

Nothing else is returned, because the provider returns nothing else: no stable account id and no statement of eligibility. Call it "Account found", never "Verified": a lookup does not prove who owns an account, so your customer stays the one who confirms.

The confirmation flow

  1. Look the recipient up with POST /recipient-lookups.
  2. Show your customer the display_name and the photo_url (initials when it is null), and ask them to confirm the account.
  3. Quote with POST /quotes, citing the lookup's id as recipient_lookup. The quote is refused unless the lookup is yours, unexpired, for the same username, product and selection, and the account at the username is still the one found. The quote echoes recipient_lookup.
  4. Create the order from the quote with POST /orders and an Idempotency-Key. The order shows its recipient_lookup; events and webhooks do not carry it.
  5. If a quote or an order answers lookup_expired or recipient_mismatch, nothing was held: look the recipient up again and show the account again. A retry of an order with the same key and body returns the first order, however old its lookup.

Errors

CodeWhen, and what to do
Invalid requestinvalid_request · 400The username is not a username, or the selection is not one the product sells. param names the field. Fix the value. Do not retry as it is.
Unknown fieldunknown_field · 400The body carries a field the lookup does not take. Remove the field.
Recipient not foundrecipient_not_found · 422The provider says nobody has this username. Ask your customer to check the username.
Recipient not eligiblerecipient_not_eligible · 422The account cannot receive this product. On Live, every nasfam_test_ name. Do not quote this recipient.
Product unavailableproduct_unavailable · 422The product is closed, or no lookup serves it. Read GET /products, and offer only what is available.
Rate limitedrate_limited · 429Past your own lookup buckets. Wait for Retry-After, then look up again.
Provider unavailableprovider_unavailable · 503The provider timed out, failed, or limited the requests Nasfam may send it. It never means the username is free. Wait for Retry-After (2 seconds, or 30 when the provider limited Nasfam), then look up again.
Not foundnot_found · 404A quote cites a lookup that is not your organisation's, not in this environment, or not found. Cite the id of a lookup you made.
Lookup expiredlookup_expired · 409A quote or an order cites a lookup past its expires_at. Nothing is held. Look the recipient up again and show your customer the account again.
Recipient mismatchrecipient_mismatch · 409The quote is for another username, product or selection, the account at the username changed since the lookup, or an order cites a lookup its quote was not made from. Nothing is held. Look the recipient up again and show the account again.
Recipient lookup requiredrecipient_lookup_required · 422Only once citing a lookup is made mandatory: a quote, or a direct order, that cites none. Look the recipient up first, and cite it.
Idempotency key reusedidempotency_key_reused · 422An order cites another lookup under an Idempotency-Key already used: that is another request. Use a new key for the new lookup.

As on every request, a lookup can also be refused with invalid_api_key, key_expired, key_environment_mismatch, insufficient_scope, browser_request_refused, payload_too_large, unsupported_media_type, internal_error, service_unavailable. A lookup needs the same right as creating a quote. A timeout of your own call means unknown: look up again, which is safe because a lookup moves no money.

Test usernames

On the sandbox host, these usernames choose the lookup's answer. Every other username is found, with the display name Sandbox user @ and the username, and no photo. Live refuses every nasfam_test_ name with recipient_not_eligible.

UsernameAnswer
Foundnasfam_test_okAn account, without a photo.
Found, with a photonasfam_test_photoAn account, with a photo_url.
Nobody therenasfam_test_missingrecipient_not_found.
Provider timeoutnasfam_test_lookup_timeoutprovider_unavailable, retry after 2 seconds: the provider did not answer in time.
Provider failurenasfam_test_lookup_unavailableprovider_unavailable, retry after 2 seconds: the provider failed.
Provider limitnasfam_test_lookup_rate_limitedprovider_unavailable, retry after 30 seconds: the provider limited Nasfam.
Expired lookupnasfam_test_lookup_expiredFound, already expired: a quote citing it is refused with lookup_expired.
Account changednasfam_test_renamedFound; the account at the username changes before the quote, which is refused with recipient_mismatch.

Quoting without a lookup

A quote that cites no lookup checks the recipient itself, before any money moves:

  • recipient.found and recipient.display_name come back on the quote only.
  • recipient_not_found means nobody has this username, and nothing is reserved.
  • recipient_not_eligible means the recipient cannot receive this product.

Show the name on the quote to your customer before you order.