API reference

API: Phone and SMS

Method	Path	What it does	Scope
DELETE	`/v1/me/sms-alerts`	Remove your mobile (no more SMS alerts) (web app only)	—
GET	`/v1/me/sms-alerts`	Your SMS alerts: your mobile (last digits), whether it's verified or stopped, quiet hours, and whether alerts quote the prospect's text	—
PATCH	`/v1/me/sms-alerts`	Your alert quiet hours (your time zone) and whether alerts quote the prospect's text (web app only)	—
POST	`/v1/me/sms-alerts/phone`	Add (or change) your own mobile for alerts: a code is texted to it from the organization's alert number (web app only)	—
POST	`/v1/me/sms-alerts/verify`	Confirm your mobile with the code you got (web app only)	—
POST	`/v1/sms/outreach`	Ask the agent to text a contact: the text waits in the approval inbox and goes only to someone with prior express written consent	`messages:send`
GET	`/v1/sms/threads`	Text threads, newest first (optionally one contact's)	`messages:read`
GET	`/v1/sms/threads/:id`	One text thread with its messages and their delivery status	`messages:read`
POST	`/v1/sms/threads/:id/claim`	Take the thread from the SMS agent (it stops answering until you hand it back)	`messages:write`
POST	`/v1/sms/threads/:id/messages`	Text from the thread as yourself (opt-outs, the texting window, consent and do-not-contact apply) (web app only)	`messages:send`
POST	`/v1/sms/threads/:id/release`	Hand the thread back to the SMS agent (it texts the contact again)	`messages:send`
GET	`/v1/telephony`	Phone and SMS: the Telnyx connection, whether its key and webhook key are set, the webhook URL, messaging profiles, numbers (and whether each may send yet), 10DLC/toll-free registrations and the SMS agent's settings	`settings:read`
PUT	`/v1/telephony`	Connect or change Telnyx (owner): the webhook's Ed25519 public key, on/off, and the SMS agent (off or auto, autonomy, confidence, the per-person daily cap, the hourly alert cap). The API key is the secret telnyx_api_key	`integrations:write`
POST	`/v1/telephony/numbers`	Add one of the organization's own Telnyx numbers (checked on its own Telnyx account; a number is active in one organization only), for prospect texting or staff alerts (owner)	`settings:write`
DELETE	`/v1/telephony/numbers/:id`	Stop using a number here (owner); it stays in the Telnyx account	`settings:write`
POST	`/v1/telephony/numbers/import`	Import the numbers Telnyx has on the organization's messaging profiles (owner)	`settings:write`
PUT	`/v1/telephony/profiles`	Set the Telnyx messaging profile for prospect texting or staff alerts (owner); the two must differ	`integrations:write`
GET	`/v1/telephony/registration-draft`	The 10DLC brand and campaign forms, filled from what the organization already told us, for an owner to review	`settings:write`
POST	`/v1/telephony/registrations`	Submit a 10DLC brand or campaign, or a toll-free verification, on the organization's Telnyx key (owner; metered: $4.50 a brand, $15 a campaign review) (web app only)	`settings:write`
POST	`/v1/telephony/registrations/refresh`	Check pending registrations with Telnyx now; an approved campaign takes in its purpose's numbers	`settings:write`
POST	`/v1/telephony/telnyx/webhook/:connection`	Telnyx messaging webhooks (public; Ed25519-signed over {telnyx-timestamp}\|{raw body}, 5-minute window; each event applied once) (no sign-in)	—

Examples

GET /v1/me/sms-alerts

Your SMS alerts: your mobile (last digits), whether it's verified or stopped, quiet hours, and whether alerts quote the prospect's text

curl -s "https://api.closefinch.com/v1/me/sms-alerts" \
  -H "Authorization: Bearer $RA_API_KEY"

const res = await fetch(`https://api.closefinch.com/v1/me/sms-alerts`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();

POST /v1/sms/outreach

Ask the agent to text a contact: the text waits in the approval inbox and goes only to someone with prior express written consent

curl -s -X POST "https://api.closefinch.com/v1/sms/outreach" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'

const res = await fetch(`https://api.closefinch.com/v1/sms/outreach`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();

GET /v1/sms/threads

Text threads, newest first (optionally one contact's)

curl -s "https://api.closefinch.com/v1/sms/threads" \
  -H "Authorization: Bearer $RA_API_KEY"

const res = await fetch(`https://api.closefinch.com/v1/sms/threads`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();

GET /v1/sms/threads/$ID

One text thread with its messages and their delivery status

curl -s "https://api.closefinch.com/v1/sms/threads/$ID" \
  -H "Authorization: Bearer $RA_API_KEY"

const res = await fetch(`https://api.closefinch.com/v1/sms/threads/${id}`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();

POST /v1/sms/threads/$ID/claim

Take the thread from the SMS agent (it stops answering until you hand it back)

curl -s -X POST "https://api.closefinch.com/v1/sms/threads/$ID/claim" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'

const res = await fetch(`https://api.closefinch.com/v1/sms/threads/${id}/claim`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();

POST /v1/sms/threads/$ID/release

Hand the thread back to the SMS agent (it texts the contact again)

curl -s -X POST "https://api.closefinch.com/v1/sms/threads/$ID/release" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'

const res = await fetch(`https://api.closefinch.com/v1/sms/threads/${id}/release`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();

GET /v1/telephony

Phone and SMS: the Telnyx connection, whether its key and webhook key are set, the webhook URL, messaging profiles, numbers (and whether each may send yet), 10DLC/toll-free registrations and the SMS agent's settings

curl -s "https://api.closefinch.com/v1/telephony" \
  -H "Authorization: Bearer $RA_API_KEY"

const res = await fetch(`https://api.closefinch.com/v1/telephony`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();

PUT /v1/telephony

Connect or change Telnyx (owner): the webhook's Ed25519 public key, on/off, and the SMS agent (off or auto, autonomy, confidence, the per-person daily cap, the hourly alert cap). The API key is the secret telnyx_api_key

curl -s -X PUT "https://api.closefinch.com/v1/telephony" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'

const res = await fetch(`https://api.closefinch.com/v1/telephony`, {
  method: "PUT",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();

POST /v1/telephony/numbers

Add one of the organization's own Telnyx numbers (checked on its own Telnyx account; a number is active in one organization only), for prospect texting or staff alerts (owner)

curl -s -X POST "https://api.closefinch.com/v1/telephony/numbers" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'

const res = await fetch(`https://api.closefinch.com/v1/telephony/numbers`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();

DELETE /v1/telephony/numbers/$ID

Stop using a number here (owner); it stays in the Telnyx account

curl -s -X DELETE "https://api.closefinch.com/v1/telephony/numbers/$ID" \
  -H "Authorization: Bearer $RA_API_KEY"

const res = await fetch(`https://api.closefinch.com/v1/telephony/numbers/${id}`, {
  method: "DELETE",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();

POST /v1/telephony/numbers/import

Import the numbers Telnyx has on the organization's messaging profiles (owner)

curl -s -X POST "https://api.closefinch.com/v1/telephony/numbers/import" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'

const res = await fetch(`https://api.closefinch.com/v1/telephony/numbers/import`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();

PUT /v1/telephony/profiles

Set the Telnyx messaging profile for prospect texting or staff alerts (owner); the two must differ

curl -s -X PUT "https://api.closefinch.com/v1/telephony/profiles" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'

const res = await fetch(`https://api.closefinch.com/v1/telephony/profiles`, {
  method: "PUT",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();

GET /v1/telephony/registration-draft

The 10DLC brand and campaign forms, filled from what the organization already told us, for an owner to review

curl -s "https://api.closefinch.com/v1/telephony/registration-draft" \
  -H "Authorization: Bearer $RA_API_KEY"

const res = await fetch(`https://api.closefinch.com/v1/telephony/registration-draft`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();

POST /v1/telephony/registrations/refresh

Check pending registrations with Telnyx now; an approved campaign takes in its purpose's numbers

curl -s -X POST "https://api.closefinch.com/v1/telephony/registrations/refresh" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'

const res = await fetch(`https://api.closefinch.com/v1/telephony/registrations/refresh`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();

Request and response schemas: https://www.closefinch.com/openapi.json. All resources: API reference.