Telebase skills.md

Agent Discovery File

Telebase API

This document is your operating manual for using the Telebase phone-intelligence API on behalf of the user you are talking to.
Read it end-to-end before the first call. Everything below is addressed directly to you.

Table of contents

• What you can do with Telebase

• Base URL

• Before the first call: the user's API key

• How to run a lookup

• How to handle errors

• How to talk to the user

• Pricing, cost, and balance

• Reference: GET /api/lookup

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 / active?"

• "What carrier owns this number?"

• "Is this a mobile or a landline?"

• "Has this SIM been swapped recently?"

• "Look up +14155551234."

Use Telebase only for those kinds of questions. It is not a reverse directory, a spam database, or a name-to-number lookup. If the user asks for
something Telebase does not do, tell them so and do not call the API.

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, visible at https://telebase.fatcatremote.com/dashboard.

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. Tell them that rotating on the dashboard invalidates the old key immediately.

How to run a lookup

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

1. Normalize 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. Examples: +14155551234, +442079425000, +381611234567.

If the user gave you something looser — (415) 555-1234, 020 7942 5000, 0611234567 — convert it yourself when you can confidently infer the country code from the conversation (location clues, prior messages, the user telling you "this is a US number"). Do not guess the country code. If you cannot confidently produce E.164, ask the user to confirm which country the number belongs to before calling the API.

2. URL-encode the +

In the query string, write the + as %2B. The URL must look like /api/lookup?phone=%2B14155551234, not /api/lookup?phone=+14155551234 — 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>

No body, no other headers required.

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 Twilio could not tell.

2. _meta.activeSource — "LINE_STATUS" means active is a strong signal; "VALID" means it's a fallback format-validity check, weaker. If activeSource is "VALID", soften your wording ("looks reachable based on format" rather than "is active").

3. carrier, country, numberType — present them plainly. numberType values you may see: mobile, landline, fixedVoip, nonFixedVoip, tollFree, voicemail.

4. simSwap is one of three values: "SWAPPED", "NO_SWAP", or "UNKNOWN". If "SWAPPED", warn the user: the SIM tied to this number has been swapped. If they are about to trust this number for verification or payments, a recent swap is a red flag. The simSwapAt field (top-level, ISO 8601 timestamp) tells you how recent. "UNKNOWN" means Twilio has no SIM-swap data for this region or carrier — do not say "no SIM swap detected" in that case; say "no SIM-swap data available". "NO_SWAP" means Twilio confirmed there is no swap on record.

Present the 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. Decide what to do per code:

401 missing_api_key / 401 invalid_api_key

The key is missing, malformed, or not recognized. Do not retry. Tell the user the key was rejected, remind them where to find the current one
(https://telebase.fatcatremote.com/dashboard), and ask them to paste a fresh copy. If they mention they recently rotated the key, point out that rotation
invalidates the old one immediately.

400 missing_phone

Your own code did not include the phone query param. Fix and retry — do not tell the user, this is your bug.

400 invalid_phone_format

The number you sent is not valid E.164. Re-read How to run a lookup §1. If you cannot fix it on your own, ask the user to confirm the country and
the full number.

402 insufficient_balance

The user has run out of funds. The response body includes required and balance integers — both are integer cents (USD). Convert them to dollars before quoting to the user (e.g. balance: 2 → "$0.02"). Tell them that top-up during the preview is done by emailing hello@telebase.io from their registered address (self-serve top-up is not live yet). Do not retry. Do not call the endpoint again until the user confirms they have added funds.

422 phone_not_found

Twilio could not resolve this number. The format was valid but the number itself does not exist on any carrier's records. Tell the user the number could not be resolved and explain the likely causes (not in service, mistyped, or an unassigned range). Do not retry with the same number.

500 internal_error / 502 upstream_failure

Transient. Retry the exact same request up to 2 more times with exponential backoff (start at ~1 s, then ~3 s). If all three attempts fail, tell the user the upstream provider is having trouble right now and to try again in a few minutes.

Anything else / network error before you got a response

Treat like 500: retry once, then surface to the user as a transient outage.

How to talk to the user

When to ask

• You have never been given the user's API key in this conversation → ask (see Before the first call).

• The number is ambiguous and you cannot infer the country code → ask.

• You got a 401 or 422 and need the user's help to recover → ask.

When not to ask

• You already have the key → use it silently, do not ask again.

• The user pasted a number in a format you can normalize yourself → just normalize 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"). Follow with the supporting details (carrier, country, type).

• Flag SIM swaps and active: false prominently — those are the signals users usually care about.

• When _meta.activeSource is "VALID" (the weaker fallback), say so: "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 just to re-read the same data — each call costs a credit.

Tone

Be factual and concise. Do not editorialize. Do not make up details the API did not return. If a field is null, say the data is not available — do not guess.

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 Twilio is reached) and upstream failures (502) are not charged.

• There is no dedicated "read my balance" endpoint yet. If the user asks their balance, direct them to https://telebase.fatcatremote.com/dashboard — the balance card is on the overview page. The only way your code sees the balance is in the 402 insufficient_balance response body.

• Public self-serve top-up is not live. During the preview, users add funds by emailing hello@telebase.io from their registered address.

If a user asks "how much will this cost me?", say "$0.03 per lookup".

Reference: GET /api/lookup

This section is for when you need the exact shape. Use it after you've read the flow above, not instead of it.

Request

Part Name Required Description Header Authorization yes Bearer <api-key>. Scheme is case-insensitive. Query phone yes E.164. Leading + (URL-encoded as %2B), 8–16 characters total.

No request body.

Response — 200 OK

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

Field Type Meaning phoneNumber string The number, normalized to E.164. active `boolean \ null` carrier `string \ null` country `string \ null` numberType `string \ null` simSwap `"UNKNOWN" \ "NO_SWAP" \ simSwapAt `string \ null` _meta.activeSource `"LINE_STATUS" \ "VALID"`

Response — errors

All errors: {"error": "<code>"} with the HTTP status below. 402 also includes required and balance integers.

Status error Meaning 400 missing_phone phone query param absent. 400 invalid_phone_format Not E.164. 401 missing_api_key Authorization header absent. 401 invalid_api_key Wrong scheme, empty token, or key not recognized. 402 insufficient_balance Balance below cost. Body: {"error":"insufficient_balance","required":3,"balance":2} (integer cents). 422 phone_not_found Twilio could not resolve the number. 500 internal_error Unexpected server error. Retryable. 502 upstream_failure Upstream reachable but errored. Retryable.

Example

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