API docs by Redocly

SimpleVoIP API (1.4.0)

Download OpenAPI specification:

License: Proprietary

SimpleVoIP's public partner-facing API: programmatic SMS/MMS sending and notification webhooks, CDR (call detail record) notifications, and bulk management of per-site Time of Day call routing and Music on Hold settings.

Authentication

Every endpoint below other than the notification webhooks requires a bearer token, noted per-endpoint under that endpoint's Authorizations heading. Send it as an Authorization: Bearer <token> header on every request. Contact your SimpleVoIP account manager to have a token issued for your account.

A request with a missing or invalid token receives a 401 response — see each endpoint for its exact 401 shape.

The notification webhooks (SMS, CDR) are the one exception: those are requests SimpleVoIP itself sends to a URL you configure, not requests you send to SimpleVoIP, so a bearer token doesn't apply. There's currently no signature/HMAC on these outbound requests either — see each webhook's own description for what verification is and isn't available today.

SMS

Programmatic SMS/MMS sending and inbound/outbound notification webhooks.

SMS Notification Webhook Webhook

Each individual SMS subscriber can be configured to trigger webhook notifications on received and/or sent SMS/MMS messages (recv_webhook_url and send_webhook_url respectively, configured per subscriber). This webhook is POSTed to the URL you specify, using the JSON format shown below. It fires with an identical payload shape for both directions — there is no direction field distinguishing an inbound-received notification from an outbound-sent notification; which URL received the POST tells you which event occurred.

No response body is expected back from your endpoint; only the HTTP status code is used for delivery bookkeeping. There is no retry on failure, and no signature/HMAC header is sent with these requests — treat the source URL as the only verification available today.

Request Body schema: application/json
required
sender
required
string

The message sender, in E.164 format for a standard number, or as-is for a short code sender.

sender_name
required
string or null

CNAM caller-ID name for sender, if a lookup has been performed and a name is available; null otherwise.

subscriber_id
required
string

The SMS-enabled subscriber number this webhook is configured against, in the same format as sender.

recipients
required
Array of strings

E.164 destination number(s).

body_text
required
string

Message body.

site_number
required
string

Site number associated with the subscriber's linked location. Literal string "undefined" if the subscriber has no linked location.

received_time
required
string

ISO-8601 timestamp with a colon-delimited UTC offset (e.g. -06:00), in the subscriber's local timezone.

mediaUrls
required
Array of strings
Deprecated

Deprecated — use media_ids instead. Despite the name this has always contained internal SimpleVoIP attachment IDs, not directly-fetchable URLs; kept for existing integrations. Always an empty array [] for plain SMS.

media_ids
required
Array of strings

Present for MMS messages; contains internal SimpleVoIP attachment IDs, not directly-fetchable URLs. Always an empty array [] for plain SMS. Identical content to the deprecated mediaUrls field. Attachment retrieval is not yet part of this public API — reach out to SimpleVoIP support if you need to resolve these IDs.

Responses

Request samples

Content type
application/json
{
  • "sender": "+12025557979",
  • "sender_name": "JOHN DOE",
  • "subscriber_id": "+15775554434",
  • "recipients": [
    ],
  • "body_text": "Hi, got your message, will follow up by EOD today!",
  • "site_number": "4321",
  • "received_time": "2023-03-04 14:51:23-06:00",
  • "mediaUrls": [ ],
  • "media_ids": [ ]
}

Send SMS

SimpleVoIP supports programmatically sending SMS/MMS messages from any SMS-enabled number registered to your account. Can be used with the SMS Notification Webhook to embed SMS messaging in your own portal or POS system.

For more detailed info: https://support.simplevoip.com/hc/en-us/articles/13407477118103-Outbound-SMS-API

A 200 response does not always mean the message was sent — check the status field. Business-logic failures (invalid number, unauthorized sender, carrier delivery failure) are returned with HTTP 200 and "status": "failed". Only a missing/invalid authentication method returns a non-200 status (401).

Authorizations:
bearerAuth
Request Body schema: application/json
required
sender
required
string

E.164 or short code the message will be sent from. Must be an SMS-enabled number on the authenticated account.

recipients
required
Array of strings non-empty

One or more E.164 destination numbers.

body_text
required
string

Message body.

subject
string

Optional MMS subject line. Omit or send an empty string for plain SMS.

media
Array of strings <uri> [ items <uri > ]

Optional URLs of media to attach as MMS. Omit or send an empty array for plain SMS.

Responses

Request samples

Content type
application/json
Example
{
  • "sender": "+15555555555",
  • "recipients": [
    ],
  • "body_text": "Your bearer token auth is working!"
}

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "msg_id": "550e8400-e29b-41d4-a716-446655440000"
}

Time of Day

Bulk management of per-site call routing rules based on time of day.

Fetch TOD Rules

Fetches all current Time of Day rule settings across all customer locations under the given parent account. Time of Day rules are used within Callflows to conditionally direct calls based on a site's local time of day, day of the week, or date — a site must have a callflow configured to use the specified rules for changes to have any effect on call routing. Contact your SimpleVoIP account manager to confirm your locations are Time of Day-enabled if you're unsure.

Authorizations:
bearerAuth
path Parameters
parent_id
required
string

Unique account ID of your parent account.

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "text/csv"

Both text/csv and application/json are accepted; any other value defaults to JSON.

Responses

Response samples

Content type
{
  • "property1": {
    },
  • "property2": {
    }
}

Modify TOD Rules

Enqueues a bulk job to modify Time of Day rules across one or more sites (the rules governing store open vs. closed logic).

For more detailed info: https://support.simplevoip.com/hc/en-us/articles/7767228147607-Time-of-Day-Bulk-Change-API

Only sites belonging to your own account are affected — any site number you don't own is silently skipped (not reflected as an error; enqueued_tasks will simply be lower than the number of sites you sent). A name matching an existing rule updates it in place; a name that doesn't yet exist for a site may create an incomplete rule, so this endpoint works most reliably against pre-existing rule names.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects
sites
required
Array of strings

Site numbers to apply the rules to. Site numbers you don't own are silently skipped.

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ],
  • "sites": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "enqueued_tasks": 2
}

Music on Hold

Bulk management of per-site Music on Hold settings.

Modify Music on Hold

Enqueues a bulk job to modify Music on Hold settings across one or more sites. The bulk job will consist of one task per specified site. Only sites belonging to your own account are affected — any site number you don't own is silently skipped (not reflected as an error; enqueued_tasks will simply be lower than the number of sites you sent).

Authorizations:
bearerAuth
Request Body schema: application/json
required
sites
required
Array of strings

Site numbers to apply the change to. Site numbers you don't own are silently skipped.

music
required
string

An empty string uses the system default hold music. Otherwise, a media object ID (used with mediaObject/parentMedia) or a ShoutCast stream URL host/path (used with shoutcast).

mediaType
required
string
Enum: "mediaObject" "parentMedia" "shoutcast"

mediaObject (media lives on the target account itself) covers the common case. parentMedia looks up music on the account named in parent instead. shoutcast treats music as a ShoutCast stream address.

parent
string

The parent account ID music lives on. Only used, and only meaningful, when mediaType is parentMedia.

Responses

Request samples

Content type
application/json
Example
{
  • "parent": "1a2b3c4d5e6f1a2b3c4d5e6f",
  • "music": "f6e5d4c3b2a1f6e5d4c3b2a1",
  • "mediaType": "parentMedia",
  • "sites": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "enqueued_tasks": 2
}

CDR

Call detail record (CDR) notification webhook, fired when a call completes.

CDR Notification Webhook Webhook

Configured per account (optionally including sub-accounts) to trigger a webhook notification each time a call completes. This webhook is POSTed to the URL you specify, using the JSON format shown below.

No response body is expected back from your endpoint; only the HTTP status code is used for delivery bookkeeping. Delivery is queued and retried on failure, and no signature/HMAC header is sent with these requests — treat the source URL as the only verification available today.

Request Body schema: application/json
required
call_id
required
string

Call-ID of the call's initiating leg.

account_id
required
string

Kazoo account ID the call belongs to.

timestamp
required
integer

UNIX timestamp at which the call started.

datetime_local
required
string

ISO-8601 timestamp with a colon-delimited UTC offset (e.g. -06:00), in the call's site's local timezone.

site_name
required
string or null

Name of the location associated with the call, or null if no linked location was found.

site_number
required
string or null

Site number of the location associated with the call, or null if no linked location was found.

total_duration_secs
required
integer

Total duration of the call in seconds, including ring time.

total_billing_secs
required
integer

Length of time media was active on the call, in seconds.

hangup_cause
required
string

Reason the call ended (e.g. NORMAL_CLEARING, NO_ANSWER).

direction
required
string
Enum: "inbound" "outbound"

outbound if an SV user initiated the call, inbound otherwise.

caller_id_number
required
string

Caller ID number of the call, in E.164 format where available.

caller_id_name
required
string

Caller ID name of the call, with any trailing STIR/SHAKEN attestation info stripped.

callee_id_number
required
string

Callee ID number of the call, in E.164 format where available.

callee_id_name
required
string

Callee ID name of the call.

total_user_talk_time
required
integer

Total number of seconds any SV user spent talking on the call.

max_user_ring_time
required
integer or null

Longest number of seconds any single SV user's device rang. null for outbound calls.

first_answered_user
required
string or null

Kazoo user ID of the first SV user to answer the call. null for outbound calls or if the call was never answered.

first_answered_device
required
string or null

Kazoo device ID of the first device used to answer the call. null for outbound calls or if the call was never answered.

attempted_users
required
Array of strings

Kazoo user IDs of every SV user the call rang. Always an empty array for outbound calls.

attempted_devices
required
Array of strings

Kazoo device IDs of every device the call rang. Always an empty array for outbound calls.

menu_selections
required
Array of strings

Caller ID name fragments recorded as the call moved through IVR menus, with the base caller ID name subtracted out. Always an empty array for outbound calls.

recording_ids
required
Array of strings

IDs of any call recordings captured for this call.

was_park_abandoned
required
boolean

true if the call was terminated while on hold in a parking slot.

was_missed
required
boolean

true if the call was inbound, no SV user answered, and at least one user's device rang.

required
object

Custom key/value data attached to the call by a callflow action. Values are typically strings but this is not guaranteed. Empty object if none were set.

Responses

Request samples

Content type
application/json
{
  • "call_id": "8675309-abcd@10.10.10.1",
  • "account_id": "1a2b3c4d5e6f1a2b3c4d5e6f",
  • "timestamp": 1704326400,
  • "datetime_local": "2024-01-03T12:00:00-06:00",
  • "site_name": "Downtown Store",
  • "site_number": "4321",
  • "total_duration_secs": 95,
  • "total_billing_secs": 80,
  • "hangup_cause": "NORMAL_CLEARING",
  • "direction": "inbound",
  • "caller_id_number": "+12025557979",
  • "caller_id_name": "JOHN DOE",
  • "callee_id_number": "+15555555556",
  • "callee_id_name": "Front Desk",
  • "total_user_talk_time": 80,
  • "max_user_ring_time": 12,
  • "first_answered_user": "2b3c4d5e6f1a2b3c4d5e6f1a",
  • "first_answered_device": "3c4d5e6f1a2b3c4d5e6f1a2b",
  • "attempted_users": [
    ],
  • "attempted_devices": [
    ],
  • "menu_selections": [ ],
  • "recording_ids": [
    ],
  • "was_park_abandoned": false,
  • "was_missed": false,
  • "custom_application_vars": { }
}