The touchbase API
Put touchbase inside your own product. Render designed emails, write posts from facts you supply, and find real businesses of a kind you describe, each read from its own website.
Pay per call
From credit you buy up front. A call that fails costs nothing.
No subscription
No invoice and nothing you owe afterwards. Credit does not expire.
Test keys are free
Test keys spend nothing and answer with sample data. 2,000 calls a day.
Base address
https://touchbasetechnologies.com/api/v1Every path in these docs is relative to it.
What you can do
Quickstart
Make a test key, then render your first email. A test key spends nothing.
- 1
Sign in and make a key
Open Keys and credit. Choose a test key: it answers with sample data where a real answer would cost money.
- 2
Send the key as a bearer token
Put it in the Authorization header of every call.
- 3
Call an endpoint
The example below renders an email. It is free on a test key.
Your first call
curl https://touchbasetechnologies.com/api/v1/email/render \
-H "Authorization: Bearer vx_test_..." \
-H "Content-Type: application/json" \
-d '{
"subject": "Welcome, {{first_name}}",
"blocks": [{ "type": "heading", "props": { "text": "Welcome, {{first_name}}" } }],
"variables": { "first_name": "Ada" },
"brand": { "companyName": "Acme" }
}'Authentication
Send the key as a bearer token. Keep it on your server, never in a browser or an app you ship.
The key
Keys look like vx_live_ or vx_test_ followed by 43 characters. A key is shown once, when you make it. touchbase keeps a fingerprint of it, not the key, so it cannot be shown again.
Authorization: Bearer vx_live_...How keys are controlled
Permissions per key
A key can only call the things you ticked when you made it.
A verified sign-in
Making a key needs a Google or LinkedIn sign-in and agreement to the API terms. Making and revoking a key is written to your audit log.
A monthly cap
Each key can have a spending cap in dollars. Calls past it are refused.
Revoke at once
Revoking a key stops it immediately.
Render an email
Turns one of touchbase's templates, or your own blocks, into table-based HTML that holds up in Outlook, plus a matching plain-text part.
/v1/email/renderPriced per render. Free on a test key.Request and response
POST /v1/email/render
{
"template": "<a key from /v1/email/templates>", // or "blocks": [...] with "subject"
"brand": { "companyName": "Acme", "primaryColor": "#2447d6" },
"variables": { "first_name": "Ada" },
"transactional": false
}200
{ "subject": "...", "html": "<!doctype html>...", "text": "..." }Notes
- List the templates with
GET /v1/email/templates. It is free. - Merge values are escaped before they reach the page, so a customer’s name cannot inject markup into your email.
Write a post
Writes one post for LinkedIn, X, Facebook, Instagram or Threads, from the facts you send and nothing else.
/v1/content/postsPriced per post.Request and response
POST /v1/content/posts
{
"topic": "We launched instant quotes",
"platform": "linkedin",
"voice": "plain and direct",
"facts": ["Quotes now take under a minute", "Available to all customers from Monday"]
}200
{ "text": "...", "platform": "linkedin", "characters": 412, "warnings": [] }Notes
- A sentence with a number that is in neither your topic nor your facts is cut, and the response says so in
warnings. - It never runs past what the network allows.
- A topic can be up to 500 characters, with up to 20 facts.
Find companies
Finds real businesses of any kind you describe, in a US state, city or county. Each is read from its own website and checked against the kind you asked for.
/v1/leads/searchPriced per company found. A search that finds none is free.Request and response
POST /v1/leads/search
{
"kind": "solar installers",
"region": "Austin, Texas",
"count": 5,
"offer": "Quoting software for installers"
}200
{
"runId": "run_...",
"companies": [{ "id": "...", "name": "...", "website": "https://...", "location": "...", "description": "...", "whyFit": "..." }],
"searchedAs": "Solar installers",
"skipped": { "alreadyHad": 0, "notAFit": 3, "unverified": 1 }
}Notes
- A call returns at most five companies, because each is a website read and a judgement and a call has to finish in about half a minute.
- If a call times out on your side, fetch what it found, free, with
GET /v1/leads/runs/<runId>. - Each result carries a reason it fits, grounded in the company’s own words. The companies are also saved in your touchbase workspace.
- Data from OpenStreetMap contributors, ODbL.
Errors and retries
Every error has the same shape, with a code your program can act on and a message a person can read.
{ "error": { "code": "insufficient_credit", "message": "This call costs 0.05 dollars and the balance is 0.03. Top up in the dashboard." } }| Status | Code | Meaning |
|---|---|---|
| 401 | invalid_key | Missing, malformed or revoked key. |
| 402 | insufficient_credit | The balance cannot cover the call. Nothing was done. |
| 402 | key_cap_reached | The call would take the key past its monthly cap. |
| 403 | scope_missing | The key was not given permission for this. |
| 403 | ip_not_allowed | The key may not be used from this address. |
| 400 | invalid_request | Something in the request is missing or wrong. The message says what. |
| 409 | idempotency_replay | That Idempotency-Key was already used. |
| 429 | rate_limited | Too many calls a minute for this key. |
| 502 | upstream_error | The work could not be completed. You were not charged. |
Retrying safely
Send an Idempotency-Key header to make a call safe to retry. A key is accepted once: using it again returns a 409 and does nothing, so a retry can never charge you twice. It does not return the first answer, so keep that.
Limits
What a call and a key are allowed to do.
Rate
60 calls a minute per key by default, up to 600. Set it when you make the key.
Size
Requests up to 200 KB. A post topic up to 500 characters. Up to 20 facts.
Coverage
Company search is open to the United States for now.
Payment
Prepaid only. Buy credit under Keys and credit. There is nothing to pay afterwards.
Pricing
A credit is one cent, the same credit the touchbase studio spends.
Each call takes its price from your balance before any work is done, and gives back whatever was not delivered: a call that fails costs nothing, a company search is charged per company found, and a search that finds none is free. When the balance cannot cover a call, the call is refused with a 402 and does nothing.
| Product | Price | What it does |
|---|---|---|
| email.render | 1 cent per render | Render one of the email templates, or your own blocks, to Outlook-safe HTML and plain text with your brand and merge fields. |
| content.post | 1 cent per post | Write a social post for a topic, platform and voice, grounded in the facts you send and nothing else. |
| leads.company | 5 cents per company | Find a real business of the kind you describe, in the place you name, read from its own website and checked against the kind you asked for. |
Coming next, at these prices: leads.contact (8 cents per contact), campaign.email (1 cent per email), social.publish (2 cents per post), content.image (10 cents per image), video.minute ($2.05 per minute), avatar.minute ($1.94 per minute), avatar.build ($32.50 per presenter). They are not final until released.
The same list is available as JSON from GET https://touchbasetechnologies.com/api/v1/pricing, with no key.
Keys and credit
Make a key, add credit and see what each key has done.
Checking your session…
API terms
Version 2026-10-04. Operated by TouchBase Technologies. Agreed to once, when you make your first key.
This is a plain-language draft and has not yet been reviewed by a lawyer. It is the working rules for the API while that review happens, and it will be replaced by reviewed terms. When it is, you will be asked to agree again before you make another key.
1.Who may use the API
A person signed in with a verified Google or LinkedIn account, acting for themselves or for a business they are entitled to bind. One agreement covers one touchbase workspace, and everyone who uses its keys.
2.Keys
A key is shown once, and touchbase keeps only a fingerprint of it. Keep it on your server, out of code you publish, and out of any app or page a customer can open. You are responsible for everything done with your keys until you revoke them. If one may have leaked, revoke it; it stops at once. Do not share a key between businesses or resell access to it.
3.Credit and what a call costs
The API is paid for in advance. A credit is one cent. Each call takes its listed price from your balance before any work is done, and gives back whatever was not delivered, so a call that fails costs nothing and a company search is charged for the companies it returns. When the balance cannot cover a call, the call is refused. We may change a price; a change applies to calls made after it, and is shown under Pricing first.
4.What you may and may not do
Do not use it to send unsolicited bulk email, to deceive anybody about who is writing to them, or to break the law. Do not use it to collect or sell lists of private individuals: company search finds businesses. Do not use posts or emails it writes to make claims you know to be false. Keep the attribution that comes with company data (OpenStreetMap contributors, ODbL). Do not try to get around a limit, a cap or a refusal, or use more than one workspace to do so.
5.Limits, suspension and changes
Each key has a calls-a-minute limit and can carry a monthly spending cap you set. We may suspend a key or a workspace that is being used in breach of these terms, to protect people who did not agree to them, and will tell you why when we can. The API may change or be withdrawn; a product that is listed as planned is not a promise.
6.What we do with your data
We keep a line for every call: what it was, when, what it cost and how it ended. We do not keep your keys. Companies a search finds are saved in your touchbase workspace. Email you ask us to render and posts you ask us to write are not kept after the response. What we do with personal data is set out in our privacy policy.
Questions? Use the support page and say it is about the API.