Switchboard API: Send a text message based on an external form submission

Last updated: October 2, 2026

How it works

  1. A visitor submits your form with their phone number and a message.

  2. Your server calls POST /v1/phones to create the phone in Switchboard, or update it if it already exists.

  3. Your server calls POST /v1/phones/{phone_number}/messages to send a one-off text to that phone.

  4. The text you sent, and any reply from the responder, show up together as one thread in All Threads. You will be able to reply from there or using the same endpoint in the API.

Before you start

  • API credentials. The API uses HTTP Basic authentication: your Account ID is the username and your Secret Key is the password. See Switchboard API to get set up.

  • Check your credentials with GET /v1/whoami: 

    curl -u "$SWITCHBOARD_ACCOUNT_ID:$SWITCHBOARD_SECRET_KEY" \
  https://api.oneswitchboard.com/v1/whoami

  • Keep your Secret Key on your server. Send the form to your own backend and make the Switchboard API calls from there. Never call the API from the visitor's browser, because that would expose your Secret Key.

  • Multi-org API keys: If your key covers more than one organization, include organization_id in the body of every request below.

Step 1: Create or update the phone

Call POST /v1/phones with the visitor's phone number. This endpoint creates the phone if it's new and updates it if it already exists. The response tells you whether the phone was newly created, which is handy if you want to treat first-time visitors differently.

Do this step every time. The send endpoint in Step 2 won't create a phone for you. If the phone doesn't exist yet, the send fails.

Step 2: Send the message

Call POST /v1/phones/{phone_number}/messages (see the Phones API reference) to send a one-off text to the phone.

  • Provide the full, final message text. Templates and custom fields aren't supported for one-off messages. If you want the visitor's name, or what they typed into your form, in the text, add it to the string on your server before you send.

  • Images and other media: First upload the file with POST /v1/uploaded_media. Then pass the media_id it returns when you send the message.

  • Links: SBLink tracked links aren't supported in one-off messages. You can include a short link you created ahead of time, but you'll only see total clicks for that link, not clicks from each person.

Step 3: Check delivery status (optional)

The response from the send call shows the message's initial status. To see its final status, call GET /v1/phones/{phone_number}/messages later.

Step 4: Reply from Switchboard

Messages sent through the API, and replies to them, appear in All Threads, grouped into the same conversation. Your team can reply there just like in any other thread. See Viewing Message Threads.

Rate limits

You can make up to 600 requests per minute per organization. This limit is separate from the API's global rate limit. Each form submission uses at least two requests (create the phone, then send). If you go over the limit, the API returns 429 with a Retry-After header. Wait that long before you retry.

Testing safely

You're charged for every message you send. Make sure your development, staging, and automated test environments can't call the send endpoint. For example, put sending behind a configuration flag or replace the send call with a stub outside production. Calling GET /v1/whoami and creating phones are good ways to test your setup without sending anything.

Related