SignalWire Docs

Appearance

Authorization ​

SignalWire REST APIs support two authentication methods: Basic Authentication and Bearer Authentication. Each endpoint specifies which method it accepts.

Basic authentication ​

Basic Authentication is the standard method for authenticating with SignalWire REST APIs, using your Project ID and API Token.

How it works ​

Include an Authorization header with each request:

Authorization: Basic <credentials>

To build the credentials string:

  1. Join your Project ID and API Token with a colon: ProjectID:APIToken
  2. Base64 encode the result

Example ​

Given the Project ID a1b2c3d4-e5f6-7890-abcd-ef1234567890 and API Token 4tjCGnmAeQ0hwFmFDhwfgww880X2lsnuR60VMyasGR3hFpSyvu:

# In the format username:password
<Badge type="tip" text="Fresh" />
a1b2c3d4-e5f6-7890-abcd-ef1234567890:4tjCGnmAeQ0hwFmFDhwfgww880X2lsnuR60VMyasGR3hFpSyvu

# Base64 encoded:
YTFiMmMzZDQtZTVmNi03ODkwLWFiY2QtZWYxMjM0NTY3ODkwOjR0akNHbm1BZVEwaHdGbUZEaHdmZ3d3ODgwWDJsc251UjYwVk15YXNHUjNoRnBTeXZ1

# Full header:
Authorization: Basic YTFiMmMzZDQtZTVmNi03ODkwLWFiY2QtZWYxMjM0NTY3ODkwOjR0akNHbm1BZVEwaHdGbUZEaHdmZ3d3ODgwWDJsc251UjYwVk15YXNHUjNoRnBTeXZ1

Finding your credentials ​

Your Project ID and API Tokens are available in the SignalWire Dashboard.

API credentials in the Dashboard.

API token scopes ​

Tokens can be scoped to limit API access. Select scopes when creating or editing a token in the Dashboard.

Getting a 401 Unauthorized? Check that your token has the required scope. Manage scopes in the SignalWire Dashboard.

cURL examples ​

cURL

# With base64-encoded credentials
curl https://{Your_Space_Name}.signalwire.com/api/laml/2010-04-01/Accounts/{YourProjectId}/Calls \
     -H 'Authorization: Basic YTFiMmMzZDQtZTVmNi03ODkwLWFiY2QtZWYxMjM0NTY3ODkwOlBUOWE4YjdjNmQ1ZTRmM2EyYjFj'

# Encoded inline using the Bash pipe operator
curl https://{Your_Space_Name}.signalwire.com/api/laml/2010-04-01/Accounts/{YourProjectId}/Calls \
    -H "Authorization: Basic $(echo -n "YourProjectId:YourApiToken" | base64)"

# Encoded inline with cURL's -u flag
curl https://{Your_Space_Name}.signalwire.com/api/laml/2010-04-01/Accounts/{YourProjectId}/Calls \
    -u YourProjectId:YourApiToken

Bearer authentication ​

Bearer Authentication passes a token in the Authorization header. Use this for client-side calls where you can’t safely expose your API credentials.

How it works ​

Include the token in an Authorization header:

Authorization: Bearer <token>

Bearer tokens are short-lived and scoped to specific permissions, unlike API credentials which don’t expire.

Token types ​

Subscriber Access Token (SAT) ​

SATs authenticate end users in Fabric applications, letting client apps make API calls on behalf of a subscriber.

How to obtain: Call the Create Subscriber Token endpoint using Basic Auth.

curl -X POST https://your-space.signalwire.com/api/fabric/subscribers/tokens \
     -H 'Authorization: Basic <Base64(YourProjectID:YourAPIToken)>' \
     -H 'Content-Type: application/json' \
     -d '{
       "reference": "user@example.com",
       "expire_at": 1725513600
     }'

Use case: Client apps connecting to Fabric services, such as listing resource addresses.

Guest Token ​

Guest Tokens grant limited, temporary access without full subscriber privileges. They’re created from an existing SAT and restricted to specific Fabric addresses.

How to obtain: Call the Create Guest Embed Token endpoint using a SAT.

curl -X POST https://your-space.signalwire.com/api/fabric/guests/tokens \
     -H 'Authorization: Bearer <subscriber_access_token>' \
     -H 'Content-Type: application/json' \
     -d '{
       "allowed_addresses": ["c22d24f6-5a26-4f53-8008-b29530339efa"]
     }'

Use case: Click-to-call widgets, guest access, or anywhere you need temporary access.

Token lifecycle ​

Bearer tokens expire. Once they do, requests return 401 Unauthorized and you’ll need a fresh token.

To keep a session alive without re-authenticating, call the Refresh Subscriber Token endpoint before expiration.

cURL example ​

cURL

curl https://your-space.signalwire.com/api/fabric/addresses \
     -H 'Authorization: Bearer <token>'

With a SAT token:

cURL

curl https://your-space.signalwire.com/api/fabric/addresses \
     -H 'Authorization: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiY2giOiJwdWMuc2lnbmFsd2lyZS5jb20iLCJ0eXAiOiJTQVQifQ...'

Security best practices ​

  1. Keep API credentials server-side. Use Bearer tokens for client applications.
  2. Set short token lifetimes to reduce risk if a token leaks.
  3. Scope tokens narrowly—only grant what’s needed.
  4. Always use HTTPS. Plain HTTP requests will fail.
  5. Rotate API tokens periodically from your Dashboard.

Error codes ​

When using SignalWire REST APIs, some errors will include error codes. Below, you will find a list of our unique error codes and a short explanation of each to help with error handling and troubleshooting.

account_limit_exceeded ​

Error

  • The account must be upgraded to perform this action.
allowed_address_limit_exceeded ​

Error

  • The maximum number of allowed addresses has been exceeded.
already_assigned ​

Error

  • This resource is already assigned.
already_verified ​

Error

  • This number is already verified.
address_has_no_valid_channels ​

Error

  • The address has no valid channels.
auto_top_up_deactivated ​

Error

  • Auto top-up is not active on this account.
authblock_is_invalid ​

Error

  • The authblock is invalid or doesn’t reference an existing subscriber.
authblock_is_expired ​

Error

  • The expires_at timestamp of the subscriber from the authblock has passed.
billing_route_not_found ​

Error

  • Unable to locate a billing route.
brand_not_unique ​

Error

  • The CSP Brand Reference must be unique within the Space
call_id_is_duplicated ​

Error

  • The provided call ID is already associated with an existing call.
call_update_failed ​

Error

  • The call update could not be completed at this time. Please try again, and contact support if issues persist.
campaign_inactive ​

Error

  • Numbers cannot be assigned to an inactive campaign
campaign_limit_exceeded ​

Error

  • The campaign limit has been exceeded.
campaign_not_active ​

Error

  • Campaign must be active.
campaign_not_found ​

Error

  • The campaign ID provided could not be found.
cannot_cancel_in_progress ​

Error

  • Cannot cancel an in-progress call.
cannot_process ​

Error

  • The request cannot be processed right now.
cannot_redirect_not_in_progress ​

Error

  • Call is not in-progress. Cannot redirect.
cannot_remove_assignment_from_integration_test ​

Error

  • You cannot remove the assignment from an integration test campaign.
cannot_update_completed ​

Error

  • Completed calls cannot be updated.
channel_has_missing_properties ​

Error

  • Channel must have read or write property.
channel_name_is_reserved ​

Error

  • The channel name uses a reserved prefix.
channel_name_size_limit_exceeded ​

Error

  • The channel name exceeds the maximum allowed length.
channel_size_limit_exceeded ​

Error

  • The number of channels exceeds the allowed limit.
chat_token_invalid_for_session ​

Error

  • The provided token is invalid for the provided room session.
chat_token_is_invalid ​

Error

  • The provided token is not a valid chat token.
contains_external_entities ​

Error

  • XML contains external entity definitions which are not allowed for security reasons.
conversation_flow_steps_are_invalid ​

Error

  • This value must be an array. Example: [“Intro”, [“Introduce yourself”, “Ask caller’s name”], “Summarize the conversation and thank the caller”]
could_not_purchase ​

Error

  • The resource could not be purchased.
destination_number_not_supported ​

Error

  • The destination phone number is not supported.
document_version_mismatch ​

Error

  • The document_version does not match the current record’s document_version.
does_not_exist ​

Error

  • This entry does not exist.
domain_has_no_password ​

Error

  • The domain has not been configured with a password.
duplicate_skill_type ​

Error

  • Only one skill of this type can exist per AI Agent.
exceeds_history_logs_limit ​

Error

  • This value exceeds the allowed date limit.
exceeds_platform_stream_limit ​

Error

  • Adding an additional stream would exceed the allowed number of streams per room.
feature_not_available ​

Error

  • This feature is not available to this account.
file_already_exists ​

Error

  • An asset already exists with this project, path, and filename.
file_can_not_be_opened ​

Error

  • An error occurred trying to open the provided file.
file_exceeds_size_limit ​

Error

  • The file exceeds the maximum allowed size.
file_not_found ​

Error

  • The requested file could not be found (404 Not Found). Please check the URL and try again.
from_fabric_address_id_does_not_match_subscriber ​

Error

  • The provided from_fabric_address_id does not match an address for the provided subscriber.
incompatible_parameters ​

Error

  • The parameters that were input cannot be specified together.
incorrect_keyword_format ​

Error

  • Keywords must be comma separated values with no space.
incorrect_number_of_sub_use_cases_low_volume ​

Error

  • Mixed use case campaigns require minimum 2 and maximum 5 sub use cases.
incorrect_number_of_sub_use_cases_mixed ​

Error

  • Mixed use case campaigns require minimum 2 and maximum 5 sub use cases.
inline_swml_or_swml_webhook_required ​

Error

  • You must pass instructions through inline SWML or a URL to a SWML document.
insufficient_balance ​

Error

  • This account has an insufficient balance.
invalid_addresses_for_transfer_skill ​

Error

  • Addresses must contain non-empty values for name and destination
invalid_auth_token_permissions ​

Error

  • Permissions list contains invalid selections. Valid permissions are calling, chat, fax, management, messaging, numbers, pubsub, storage, tasking, and video.
invalid_call_handler_for_external_swml_handler ​

Error

  • Handler must be calling or messaging.
invalid_call_handler_for_swml_application ​

Error

  • Handler must be external_url or script.
invalid_call_id_passed ​

Error

  • The call ID must not point to a cXML call.
invalid_campaign_id ​

Error

  • The campaign ID provided is invalid.
invalid_campaign_status ​

Error

  • The campaign status is invalid.
invalid_codecs_format ​

Error

  • Codecs must be an array of strings or a comma-separated string.
invalid_command_attempted ​

Error

  • The specified command is invalid.
invalid_content_type ​

Error

  • Invalid content type.
invalid_destination_number ​

Error

  • The destination phone number is invalid.
invalid_for_type ​

Error

  • This is not valid for the current type.
invalid_for_page_chunking ​

Error

  • Chunking parameters are not allowed for page chunking.
invalid_for_paragraph_chunking ​

Error

  • Chunking parameters are not allowed for paragraph chunking.
invalid_for_sentence_chunking ​

Error

  • Provided chunking parameters are not valid for sentence chunking. Allowed parameters are max_sentences_per_chunk and split_newlines.
invalid_for_sliding_chunking ​

Error

  • Provided chunking parameters are not valid for sliding chunking. Allowed parameters are chunk_size and overlap_size.
invalid_group_configuration ​

Error

  • Fabric addresses must form a valid conversation group (a single room or two non-room subscribers) and group ID must start with ‘sw_’.
invalid_handler_use ​

Error

  • Handler must be calling or messaging.
invalid_http_method ​

Error

  • This request method must be GET or POST.
invalid_join_until_date ​

Error

  • Join Until date can’t be in the past of Join From date.
invalid_list_items ​

Error

  • The list items are invalid.
invalid_media_type ​

Error

  • The media type provided is invalid.
invalid_media_url ​

Error

  • The media URL provided is invalid.
invalid_message_body ​

Error

  • The message body provided is invalid.
invalid_mustache_syntax ​

Error

  • The mustache syntax is invalid..
invalid_number_format ​

Error

  • The phone number is not in the correct format. Please use E.164 format, i.e., +15558675309.
invalid_object ​

Error

  • This object is invalid. Refer to the error message for more details.
invalid_parameter ​

Error

  • This list contains an invalid entry.
invalid_pstn_destination ​

Error

  • The PSTN destination is either missing or not in E164 format.
invalid_relay_connector_parameters ​

Error

  • Send relay_connector_id to link to an existing connector or relay_connector_name and relay_connector_token to create a new one.
invalid_resource_for_handler ​

Error

  • This resource is not valid for the specified handler type.
invalid_resource_type ​

Error

  • The passed resource type is not a valid resource type.
invalid_room_session ​

Error

  • The room session ID does not point to a valid room session.
invalid_sip_configuration ​

Error

  • The SIP configuration value is invalid.
invalid_sip_destination ​

Error

  • The SIP destination is either missing or could not be parsed.
invalid_state ​

Error

  • The object is not in the correct state for this action.
invalid_sub_use_cases ​

Error

  • This sub use case is not valid.
invalid_subproject_id ​

Error

  • The subproject ID passed could not be found or does not belong to the project being used to authenticate the request.
invalid_token_format ​

Error

  • The format of the provided token is invalid.
invalid_zendesk_capability ​

Error

  • The Zendesk Capability is invalid.
list_contains_invalid_entries ​

Error

  • The list contains an invalid entry.
malformed_xml ​

Error

  • The XML is not well formed
max_queued_calls_exceeded ​

Error

  • The maximum number of queued calls has been exceeded.
max_queued_messages_exceeded ​

Error

  • has exceeded the maximum number of queued messages/calls for this number
media_size_exceeds_limit ​

Error

  • The media size exceeds the allowed limit.
media_url_required ​

Error

  • A media URL is required.
message_body_required ​

Error

  • The message body is required.
message_length_exceeds_limit ​

Error

  • The message length exceeds the allowed limit.
messaging_provider_invalid ​

Error

  • Messaging provider is invalid.
missing_required_parameter ​

Error

  • The passed value is blank or empty, but it is required.
missing_sub_use_cases ​

Error

  • Sub use cases are required for MIXED and LOW_VOLUME_MIXED campaigns.
missing_sip_configuration ​

Error

  • The SIP configuration requires at least one selection.
must_belong_to_project ​

Error

  • The requested resource must belong to the project being used to authenticate the request.

Error

  • This parameter must be used in combination with a related parameter.
no_channel_specified ​

Error

  • You must specify a channel.
no_devices_or_registrations ​

Error

  • The fabric address has no registered devices or current online registrations.
no_fabric_addresses ​

Error

  • The resource has no fabric addresses.
no_installed_applications ​

Error

  • Fabric Application must be installed in this project.
no_registered_devices ​

Error

  • The fabric address has no registered devices.
no_steered_resource ​

Error

  • The project has a steering tag set, but no steered resource is available for that tag.
no_valid_number_for_random_send_as_selection ​

Error

  • There is no purchased or verified number in the project to select as the send_as.
not_a_boolean ​

Error

  • Value must be true or false.
not_a_datetime ​

Error

  • Value must be a datetime.
not_a_hash ​

Error

  • Value must be a valid hash.
not_a_refresh_token ​

Error

  • Invalid token type. You must use a Refresh token.
not_a_string ​

Error

  • Value must be formatted as a string.
not_a_valid_json ​

Error

  • This value must be valid JSON.
not_allowed_on_subscription_plan ​

Error

  • This feature is not allowed on your current subscription plan.
not_alphanumeric ​

Error

  • Value must be alphanumeric.
not_an_array_of_hashes ​

Error

  • Value must be an array of hashes.
not_an_array_of_strings ​

Error

  • Value must be an array of strings.
not_an_http_url ​

Error

  • Value must be an HTTP or HTTPS URL.
not_available_for_assignment ​

Error

  • This can not be assigned to the current target.
not_e164 ​

Error

  • The number must be in E.164 format.
not_json_or_yaml ​

Error

  • Value must be a valid JSON or YAML document.
not_parsable ​

Error

  • Value is not parsable.
not_parseable ​

Error

  • Value is not parseable.
not_purchased_or_verified ​

Error

  • The phone number must be purchased or verified.
not_registered ​

Error

  • The endpoint is not registered.
not_routable ​

Error

  • Unable to locate a route to the destination number. Please check geographic permissions and the destination number, and contact Support if issues persist.
not_valid_for_caller_id ​

Error

  • The value is not valid (must be an E.164 number, caller ID string or SIP URI)
not_voice_capable ​

Error

  • The number must be voice capable.
not_unique_within_project ​

Error

  • Value must be unique within project.
not_unique_within_space ​

Error

  • Value must be unique within space.
number_assignment_cannot_be_removed ​

Error

  • Number assignments can only be removed if they are active, failed, or assigned to a pending campaign.
number_blacklisted ​

Error

  • The phone number is blacklisted.
number_not_supported ​

Error

  • The phone number is not supported.
number_not_verified ​

Error

  • ‘From’ phone number not verified.
number_of_assignments_exceed_limit ​

Error

  • The requested assignment would exceed the allowed number of assigned numbers for the selected campaign.
out_of_sync ​

Error

  • The resource is out of sync.
page_token_is_invalid ​

Error

  • The provided page token is not valid.
page_token_required ​

Error

  • A page token is required if the page_number value is greater than 0.
page_token_required_for_next_page ​

Error

  • The page token is required when the page number is passed and greater than 0.
provided_id_is_unrecognized ​

Error

  • The provided ID is unrecognized. Verify that the ID points to a valid resource belonging to the current project.
purchased_too_recently ​

Error

  • This number was purchased too recently to release. Please wait 14 days after purchase to release this number or 30 days if your account is in trial mode. Contact Support for further assistance.
query_processing_failed ​

Error

  • The query cannot be processed at the moment. Please try again later.
rate_limit_exceeded ​

Error

  • The rate limit has been exceeded.
resource_assigned_as_handler ​

Error

  • You cannot delete a resource if it is currently assigned as a call or message handler
resource_in_different_project ​

Error

  • The fabric resource is in a different project.
resource_not_allowed ​

Error

  • Calls to this fabric resource are not allowed with this authorization.
resource_not_callable ​

Error

  • The fabric resource is not callable.
resource_not_deletable ​

Error

  • Resource cannot be deleted.
room_is_not_chat_enabled ​

Error

  • The room for the provided room session does not have chat enabled.
room_token_invalid_for_session ​

Error

  • The provided token is invalid for the provided room session.
room_token_is_invalid ​

Error

  • The provided token is not a valid room token.
sat_must_have_application ​

Error

  • SignalWire Access Token must be associated with a Fabric Application to perform this action.
send_as_is_invalid ​

Error

  • The provided send_as number is missing or invalid.
sip_gateway_uri_must_be_external ​

Error

  • Only external SIP entities are supported for the SIP Gateway. Do not provide a SignalWire-managed SIP entity.
sort_order_validations ​

Error

  • Sort order cannot be specified without sort by.
state_size_limit_exceeded ​

Error

  • The state size exceeds the maximum allowed limit.
sub_use_cases_present ​

Error

  • Sub use cases are not permitted for non mixed campaign use case.
terms_and_conditions_required ​

Error

  • You must agree to the terms and conditions to complete registration.
to_destination_unresolvable ​

Error

  • The destination does not resolve to a valid destination.
token_expired ​

Error

  • Token has expired.
token_has_invalid_prefix ​

Error

  • The token includes an invalid format prefix.
token_invalid ​

Error

  • The provided token is invalid.
token_invalid_or_unadoptable ​

Error

  • The provided FreeSWITCH token is incorrect or not ready for adoption
token_not_associated_with_video_room ​

Error

  • The provided token is not associated with a valid video room.
too_many_verification_attempts ​

Error

  • Too many incorrect attempts to verify this number.
too_many_verification_requests ​

Error

  • Too many call requests without verifying this number.
too_many_verification_requests_in_time_frame ​

Error

  • This account has had too many Verified Caller ID requests within a short timeframe. As a precaution, we have disabled creating more for a short time. Please contact support if you need this restriction lifted sooner.
unknown_download_error ​

Error

  • An unexpected error occurred while downloading the file. Please try again later or contact support if the issue persists.
unrecognized_fabric_addresses ​

Error

  • One or more of the provided fabric addresses is unrecognized. Check that all IDs are valid and belong to the current project.
unsupported_file_extension ​

Error

  • Unsupported file extension.
unsupported_mode ​

Error

  • This mode is not supported on this number.
unsupported_option ​

Error

  • The specified option is not supported.
unsupported_region ​

Error

  • This number must be from an allowed region.
uri_does_not_resolve_to_address ​

Error

  • The provided URI does not resolve to a recognized address.
uri_does_not_resolve_to_resource ​

Error

  • The provided URI does not resolve to a valid resource.
uri_resolves_to_unsupported_resource ​

Error

  • The provided URI resolves to a resource that is unsupported for dialing.
upload_error ​

Error

  • There was an error while uploading the file. Please try again.
url_failed_to_parse ​

Error

  • An unknown error occurred when parsing the provided URL.
url_is_unsafe ​

Error

  • URL must not point to internal/private networks.
value_not_unique ​

Error

  • This value must be unique.
verification_request_too_soon ​

Error

  • This number has received a verification call too recently. Please wait a minute before requesting another call.

\\\*

title: Paging

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

Most top-level API resources support bulk fetching via a list or index method. These list endpoints share a common structure to make handling lists, filtering and pagination easier to work with.

All list endpoints will return partial "pages" of results. These results will also contain meta information about how to get the next page of results, or the previous one, or return to the start.

It is ***highly recommended*** to use the `link` values to navigate your list results. This will ensure you properly page through all of resources and your result set is not affected by new resources being created, or paging scheme changing.

**An example of the paging information returned for all index routes.**

```json { "links": { "self": "/api/relay/rest/example_url_to_the_current_page", "first": "/api/relay/rest/example_url_to_the_first_page", "next": "/api/relay/rest/example_url_to_the_next_page", "prev": "/api/relay/rest/example_url_to_the_prev_page" }, "data" : [
{ ... },
{ ... }
] } ```

SignalWire Developer Documentation

Internal SOP Reference