skills.md

What you can do with Telebase

Telebase returns KYC-grade intelligence about any phone number: carrier, country, line type (mobile / landline / VoIP), SIM-swap status, and whether the number is currently reachable. Use it when the user asks things like:

• "Is this number real or active?"
• "What carrier owns this number?"
• "Is this a mobile or a landline?"
• "Has this SIM been swapped recently?"
• "Look up +14155551234."

Base URL

All API calls go to:

https://telebase.fatcatremote.com

If the user mentions Telebase is hosted at a different URL, use that instead and keep it for the rest of the conversation.

Before the first call: the user's API key

Every request needs the user's API key. Never guess, fabricate, or reuse a key from another conversation. The key belongs to the human you are talking to — you have to get it from them.

Step 1 — Check whether you already have the key

If the user has already given you a key earlier in this conversation, use it. Do not ask again.

Step 2 — If you do not have a key, ask the user

Ask once. Tell them where to find it and ask them to paste it into the conversation: the key lives on their Telebase dashboard at https://telebase.fatcatremote.com/dashboard and starts with tb_live_.

If the user says they do not have a Telebase account yet, tell them to sign up at https://telebase.fatcatremote.com/login with their email (magic-link auth, no password). A new account is auto-provisioned with a $5.00 starting balance and one API key.

Step 3 — Validate the key format before using it

A real key starts with tb_live_ followed by a URL-safe random string. If the pasted value does not start with tb_live_, assume it is wrong and ask the user to re-copy it from the dashboard before making a call.

Step 4 — Handle the key carefully

• Keep it in-memory for this conversation only.
• Do not echo the key back to the user in plain text. If you must reference it, show only the last four characters: …abcd.
• Do not include it in any response you send to third-party tools or logs.
• If the user explicitly tells you to forget or rotate the key, drop it from this conversation.

How to run a lookup

Given a phone number the user wants to look up, do this in order:

1. Normalise the number to E.164

Telebase accepts only E.164 format: a leading +, the country code, and the subscriber number — all digits, 8 to 16 characters total.

+14155551234
+442079425000
+381611234567

If the user gave you something looser, convert it yourself when you can confidently infer the country code. Do not guess the country code. If you cannot confidently produce E.164, ask the user to confirm the country before calling.

2. URL-encode the +

In the query string, write the + as %2B. The raw + gets interpreted as a space by most HTTP clients and breaks the request.

3. Call the API

GET https://telebase.fatcatremote.com/api/lookup?phone=%2B14155551234
Authorization: Bearer <the key the user gave you>

4. Interpret the response

On 200 OK you get a JSON object. Read these fields in order:

1. active — true means reachable on the carrier network. false means not reachable. null means the carrier could not tell.
2. _meta.activeSource — "LINE_STATUS" is a strong signal; "VALID" is a fallback format-validity check, weaker. If "VALID", soften your wording: "looks reachable based on format" rather than "is active".
3. carrier, country, numberType — present them plainly. Number type values: mobile, landline, fixedVoip, nonFixedVoip, tollFree, voicemail.
4. simSwap is one of three values: "SWAPPED", "NO_SWAP", or "UNKNOWN".

Present results in plain language, not as raw JSON, unless the user explicitly asked for JSON.

How to handle errors

Every error response looks like {"error": "<stable_code>"} with an HTTP status code. Match on the error code — do not try to parse free-form messages.

How to talk to the user

When to ask

• You have never been given the user's API key in this conversation.
• The number is ambiguous and you cannot infer the country code.
• You got a 401 or 422 and need the user's help to recover.

When not to ask

• You already have the key — use it silently, do not ask again.
• The user pasted a number you can normalise yourself — just normalise and run it.
• You hit a transient 500/502 — retry silently up to 2 times before bothering the user.

How to present results

• Lead with the direct answer to the user's question. If they asked "is this number active?", your first sentence is yes or no (or "Telebase could not tell").
• Flag SIM swaps and active: false prominently — those are the signals users usually care about.
• When _meta.activeSource is "VALID", qualify: "Telebase could only confirm the number looks well-formed for its country, not that it is actively reachable."
• If the user asks follow-up questions about the same number, reuse the already-fetched response. Do not call Telebase a second time — each call costs a credit.

Pricing, cost, and balance

All numeric amounts in API responses are integer cents (USD). When you speak to the user, render them as dollars (e.g. 497 → "$4.97").

• Each successful 200 lookup costs 3 cents (US$0.03).
• New Telebase accounts receive a 500-cent (US$5.00) starting balance on first sign-in.
• Validation errors (4xx before the carrier is reached) and upstream failures (502) are not charged.
• There is no dedicated "read my balance" endpoint. Direct the user to https://telebase.fatcatremote.com/dashboard — the balance card is on the overview page.
• Public self-serve top-up is not yet live. During the preview, users add funds by emailing hello@telebase.io from their registered address.

Reference: GET /api/lookup

Request

Response — 200 OK

{
  "phoneNumber": "+14159929960",
  "active": true,
  "carrier": "AT&T Wireless",
  "country": "US",
  "numberType": "mobile",
  "simSwap": "NO_SWAP",
  "simSwapAt": null,
  "_meta": {
    "activeSource": "LINE_STATUS"
  }
}

Response — errors

{ "error": "<stable_code>" }

# 402 also includes balance info:
{ "error": "insufficient_balance", "required": 3, "balance": 2 }

Example curl

curl -s \
  'https://telebase.fatcatremote.com/api/lookup?phone=%2B14159929960' \
  -H 'Authorization: Bearer tb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'