> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt
# Create SIP endpoint
POST https://%7BYour_Space_Name%7D.signalwire.com/api/relay/rest/endpoints/sip
Content-Type: application/json
Creates a new SIP endpoint.
This endpoint is deprecated. Use [SIP Credentials](/docs/apis/rest/sip-credentials/create-sip-credential) instead.
#### Permissions
The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Voice_.
[Learn more about API scopes](/docs/platform/your-signalwire-api-space).
Reference: https://signalwire.com/docs/apis/rest/sip-endpoints/create-sip-endpoint
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: signalwire-rest
version: 1.0.0
paths:
/api/relay/rest/endpoints/sip:
post:
operationId: create_sip_endpoint
summary: Create SIP endpoint
description: >-
Creates a new SIP endpoint.
This endpoint is deprecated. Use [SIP
Credentials](/docs/apis/rest/sip-credentials/create-sip-credential)
instead.
#### Permissions
The API token used to authenticate must have the following scope(s)
enabled to make a successful request: _Voice_.
[Learn more about API scopes](/docs/platform/your-signalwire-api-space).
tags:
- sipEndpointsLegacy
parameters:
- name: Authorization
in: header
description: >-
SignalWire Basic Authentication using Project ID and API Token.
The client sends HTTP requests with the Authorization header
containing
the word Basic followed by a space and a base64-encoded string of
project_id:token.
The project ID will be used as the username and the API token as the
password.
Example:
```
Authorization: Basic base64(project_id:token)
```
required: true
schema:
type: string
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/SipEndpointResponse'
'401':
description: Access is unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
'422':
description: The request failed validation. See errors for details.
content:
application/json:
schema:
$ref: '#/components/schemas/Types.StatusCodes.ValidationError'
'500':
description: An internal server error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSipEndpointRequest'
servers:
- url: https://%7BYour_Space_Name%7D.signalwire.com
description: SignalWire API
components:
schemas:
CreateSipEndpointRequestEncryption:
type: string
enum:
- default
- required
- optional
description: Specifies the encryption requirements for connections to this endpoint.
title: CreateSipEndpointRequestEncryption
CreateSipEndpointRequestCallHandler:
type: string
enum:
- relay_context
- relay_topic
- relay_application
- relay_connector
- relay_script
- laml_webhooks
- laml_application
- dialogflow
- video_room
- call_flow
- ai_agent
description: What type of handler you want to run on inbound calls.
title: CreateSipEndpointRequestCallHandler
CreateSipEndpointRequestCallRequestMethod:
type: string
enum:
- GET
- POST
description: The HTTP method to use with call_request_url.
title: CreateSipEndpointRequestCallRequestMethod
CreateSipEndpointRequestCallFallbackMethod:
type: string
enum:
- GET
- POST
description: The HTTP method to use with call_fallback_url.
title: CreateSipEndpointRequestCallFallbackMethod
CreateSipEndpointRequestCallStatusCallbackMethod:
type: string
enum:
- GET
- POST
description: The HTTP method to use with call_status_callback_url.
title: CreateSipEndpointRequestCallStatusCallbackMethod
uuid:
type: string
format: uuid
description: Universal Unique Identifier.
title: uuid
CreateSipEndpointRequest:
type: object
properties:
username:
type: string
description: >-
String representing the username portion of the endpoint. Must be
unique across your project and must not contain white space
characters or @.
password:
type: string
description: A password to authenticate registrations to this endpoint.
caller_id:
type: string
description: >-
Friendly Caller ID used as the CNAM when dialing a phone number or
the From when dialing another SIP Endpoint.
send_as:
type: string
description: >-
When dialing a PSTN phone number, you must send it From a number you
have purchased or verified. send_as indicates which number this
endpoint has set as its origination. random indicates it will
randomly choose a purchased or verified number from within the
project.
ciphers:
type: array
items:
type: string
description: A list of encryption ciphers this endpoint will support.
codecs:
type: array
items:
type: string
description: A list of codecs this endpoint will support.
encryption:
$ref: '#/components/schemas/CreateSipEndpointRequestEncryption'
description: >-
Specifies the encryption requirements for connections to this
endpoint.
call_handler:
$ref: '#/components/schemas/CreateSipEndpointRequestCallHandler'
description: What type of handler you want to run on inbound calls.
call_request_url:
type: string
description: >-
The LaML URL to access when a call is received. Required when
call_handler is laml_webhooks.
call_request_method:
$ref: '#/components/schemas/CreateSipEndpointRequestCallRequestMethod'
description: The HTTP method to use with call_request_url.
call_fallback_url:
type: string
description: >-
The LaML URL to access when the call to call_request_url fails.
Required when call_handler is laml_webhooks.
call_fallback_method:
$ref: '#/components/schemas/CreateSipEndpointRequestCallFallbackMethod'
description: The HTTP method to use with call_fallback_url.
call_status_callback_url:
type: string
description: >-
A URL to send status change messages to. Required when call_handler
is laml_webhooks.
call_status_callback_method:
$ref: >-
#/components/schemas/CreateSipEndpointRequestCallStatusCallbackMethod
description: The HTTP method to use with call_status_callback_url.
call_laml_application_id:
type: string
description: >-
The ID of the LaML application to forward incoming calls to.
Required when call_handler is laml_application.
call_dialogflow_agent_id:
type: string
description: >-
The ID of the Dialogflow agent to forward incoming calls to.
Required when call_handler is dialogflow.
call_relay_topic:
type: string
description: >-
The Relay topic to forward incoming calls to. Required when
call_handler is relay_topic.
call_relay_topic_status_callback_url:
type: string
description: >-
A URL to send status change messages to. Required when call_handler
is relay_topic.
call_relay_context:
type: string
description: >-
The Relay context to forward incoming calls to. Required when
call_handler is relay_context.
call_relay_context_status_callback_url:
type: string
description: >-
A URL to send status change messages to. Required when call_handler
is relay_context.
call_relay_application:
type: string
description: >-
The Relay application to forward incoming calls to. Required when
call_handler is relay_application.
call_video_room_id:
$ref: '#/components/schemas/uuid'
description: >-
The ID of the Video Room to forward incoming calls to. Required when
call_handler is video_room.
call_flow_id:
$ref: '#/components/schemas/uuid'
description: >-
The ID of the Call Flow to forward incoming calls to. Required when
call_handler is call_flow.
call_flow_version:
type: string
description: >-
The version of the Call Flow to use. Valid values are 'working_copy'
or 'current_deployed'.
call_ai_agent_id:
$ref: '#/components/schemas/uuid'
description: >-
The ID of the AI Agent to forward incoming calls to. Required when
call_handler is ai_agent.
call_relay_script_url:
type: string
description: >-
A URL of a SWML script to respond to incoming calls. Required when
call_handler is relay_script.
required:
- username
- password
description: Request body for creating a SIP endpoint.
title: CreateSipEndpointRequest
SipEndpointResponseEncryption:
type: string
enum:
- default
- required
- optional
description: >-
Whether connections to this endpoint require encryption or if encryption
is optional.
title: SipEndpointResponseEncryption
SipEndpointCallHandler:
type: string
enum:
- relay_context
- relay_topic
- relay_application
- relay_connector
- relay_script
- laml_webhooks
- laml_application
- dialogflow
- video_room
- call_flow
- ai_agent
description: Call handler type for SIP endpoints.
title: SipEndpointCallHandler
SipEndpointResponseCallRequestMethod:
type: string
enum:
- GET
- POST
description: >-
A string representing the HTTP method to use with call_request_url.
Valid values are GET and POST.
title: SipEndpointResponseCallRequestMethod
SipEndpointResponseCallFallbackMethod:
type: string
enum:
- GET
- POST
description: >-
A string representing the HTTP method to use with call_fallback_url.
Valid values are GET and POST.
title: SipEndpointResponseCallFallbackMethod
SipEndpointResponseCallStatusCallbackMethod:
type: string
enum:
- GET
- POST
description: >-
A string representing the HTTP method to use with
call_status_callback_url. Valid values are GET and POST.
title: SipEndpointResponseCallStatusCallbackMethod
SipEndpointResponse:
type: object
properties:
type:
type: string
description: A string representation of the type of object this record is.
id:
$ref: '#/components/schemas/uuid'
description: The unique identifier of the SIP endpoint.
username:
type: string
description: The username for the SIP endpoint.
caller_id:
type:
- string
- 'null'
description: >-
Friendly Caller ID used as the CNAM when dialing a phone number or
the From when dialing another SIP Endpoint.
send_as:
type: string
description: >-
When dialing a PSTN phone number, you must send it From a number you
have purchased or verified. send_as indicates which number this
endpoint has set as its origination. random indicates it will
randomly choose a purchased or verified number from within the
project.
ciphers:
type: array
items:
type: string
description: A list of encryption ciphers this endpoint will support.
codecs:
type: array
items:
type: string
description: A list of codecs this endpoint will support.
encryption:
$ref: '#/components/schemas/SipEndpointResponseEncryption'
description: >-
Whether connections to this endpoint require encryption or if
encryption is optional.
call_handler:
oneOf:
- $ref: '#/components/schemas/SipEndpointCallHandler'
- type: 'null'
description: What type of handler you want to run on inbound calls.
calling_handler_resource_id:
oneOf:
- $ref: '#/components/schemas/uuid'
- type: 'null'
description: The unique identifier of the calling handler resource.
call_request_url:
type:
- string
- 'null'
description: >-
A string representing the LaML URL to access when a call is
received. This is only used (and required) when call_handler is set
to laml_webhooks.
call_request_method:
oneOf:
- $ref: '#/components/schemas/SipEndpointResponseCallRequestMethod'
- type: 'null'
description: >-
A string representing the HTTP method to use with call_request_url.
Valid values are GET and POST.
call_fallback_url:
type:
- string
- 'null'
description: >-
A string representing the LaML URL to access when the call to
call_request_url fails. This is only used (and required) when
call_handler is set to laml_webhooks.
call_fallback_method:
oneOf:
- $ref: '#/components/schemas/SipEndpointResponseCallFallbackMethod'
- type: 'null'
description: >-
A string representing the HTTP method to use with call_fallback_url.
Valid values are GET and POST.
call_status_callback_url:
type:
- string
- 'null'
description: >-
A string representing a URL to send status change messages to. This
is only used (and required) when call_handler is set to
laml_webhooks.
call_status_callback_method:
oneOf:
- $ref: '#/components/schemas/SipEndpointResponseCallStatusCallbackMethod'
- type: 'null'
description: >-
A string representing the HTTP method to use with
call_status_callback_url. Valid values are GET and POST.
call_laml_application_id:
type:
- string
- 'null'
description: >-
A string representing the ID of the LaML application to forward
incoming calls to. This is only used (and required) when
call_handler is set to laml_application.
call_dialogflow_agent_id:
type:
- string
- 'null'
description: >-
A string representing the ID of the Dialogflow agent to forward
incoming calls to. This is only used (and required) when
call_handler is set to dialogflow.
call_relay_topic:
type:
- string
- 'null'
description: >-
A string representing the Relay topic to forward incoming calls to.
This is only used (and required) when call_handler is set to
relay_topic.
call_relay_topic_status_callback_url:
type:
- string
- 'null'
description: >-
A string representing a URL to send status change messages to. This
is only used (and required) when call_handler is set to relay_topic.
call_relay_context:
type:
- string
- 'null'
description: >-
A string representing the Relay context to forward incoming calls
to. This is only used (and required) when call_handler is set to
relay_context.
call_relay_context_status_callback_url:
type:
- string
- 'null'
description: >-
A string representing a URL to send status change messages to. This
is only used (and required) when call_handler is set to
relay_context.
call_relay_application:
type:
- string
- 'null'
description: >-
A string representing the Relay application to forward incoming
calls to. This is only used (and required) when call_handler is set
to relay_application.
call_video_room_id:
oneOf:
- $ref: '#/components/schemas/uuid'
- type: 'null'
description: >-
A string representing the ID of the Video Room to forward incoming
calls to. This is only used (and required) when call_handler is set
to video_room.
call_relay_script_url:
type:
- string
- 'null'
description: >-
A string representing a URL of a SWML script to respond to incoming
calls. This is only used (and required) when call_handler is set to
relay_script.
required:
- type
- id
- username
- caller_id
- send_as
- ciphers
- codecs
- encryption
- call_handler
- calling_handler_resource_id
- call_request_url
- call_request_method
- call_fallback_url
- call_fallback_method
- call_status_callback_url
- call_status_callback_method
- call_laml_application_id
- call_dialogflow_agent_id
- call_relay_topic
- call_relay_topic_status_callback_url
- call_relay_context
- call_relay_context_status_callback_url
- call_relay_application
- call_video_room_id
- call_relay_script_url
description: Response containing a single SIP endpoint.
title: SipEndpointResponse
TypesStatusCodesStatusCode401Error:
type: string
enum:
- Unauthorized
title: TypesStatusCodesStatusCode401Error
Types.StatusCodes.StatusCode401:
type: object
properties:
error:
$ref: '#/components/schemas/TypesStatusCodesStatusCode401Error'
required:
- error
description: Access is unauthorized.
title: Types.StatusCodes.StatusCode401
Types.StatusCodes.SpaceApiErrorItem:
type: object
properties:
detail:
type: string
description: A description of what caused the error.
status:
type: string
description: The HTTP status code.
title:
type: string
description: A short summary of the error type.
code:
type: string
description: The error code.
required:
- detail
- status
- title
- code
description: Details about a specific validation error.
title: Types.StatusCodes.SpaceApiErrorItem
Types.StatusCodes.ValidationError:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/Types.StatusCodes.SpaceApiErrorItem'
description: List of validation errors.
required:
- errors
description: The request failed validation. See errors for details.
title: Types.StatusCodes.ValidationError
TypesStatusCodesStatusCode500Error:
type: string
enum:
- Internal Server Error
title: TypesStatusCodesStatusCode500Error
Types.StatusCodes.StatusCode500:
type: object
properties:
error:
$ref: '#/components/schemas/TypesStatusCodesStatusCode500Error'
required:
- error
description: An internal server error occurred.
title: Types.StatusCodes.StatusCode500
securitySchemes:
SignalWireBasicAuth:
type: http
scheme: basic
description: >-
SignalWire Basic Authentication using Project ID and API Token.
The client sends HTTP requests with the Authorization header containing
the word Basic followed by a space and a base64-encoded string of
project_id:token.
The project ID will be used as the username and the API token as the
password.
Example:
```
Authorization: Basic base64(project_id:token)
```
```
## Examples
**Request**
```json
{
"username": "c3p0",
"password": "yavinOrBust"
}
```
**Response**
```json
{
"type": "sip_endpoint",
"id": "67075301-69b2-4fc3-8a2c-c95a69a5665e",
"username": "c3p0",
"caller_id": "C-3P0",
"send_as": "random",
"ciphers": [
"string"
],
"codecs": [
"string"
],
"encryption": "required",
"call_handler": "ai_agent",
"calling_handler_resource_id": "fe4093d9-58c2-4931-b4b9-5679f82652c6",
"call_request_url": "string",
"call_request_method": "POST",
"call_fallback_url": "string",
"call_fallback_method": "POST",
"call_status_callback_url": "string",
"call_status_callback_method": "POST",
"call_laml_application_id": "string",
"call_dialogflow_agent_id": "string",
"call_relay_topic": "office",
"call_relay_topic_status_callback_url": "https://myapplication/handle_relay_callbacks",
"call_relay_context": "string",
"call_relay_context_status_callback_url": "https://myapplication/handle_relay_callbacks",
"call_relay_application": "string",
"call_video_room_id": "string",
"call_relay_script_url": "https://dev.signalwire.com/relay-bins/f9d13f68-f71e-4042-95bb-b07b9e2f2f92"
}
```
**SDK Code**
```python
import requests
url = "https://{your_space_name}.signalwire.com/api/relay/rest/endpoints/sip"
payload = {
"username": "c3p0",
"password": "yavinOrBust"
}
headers = {
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers, auth=("", ""))
print(response.json())
```
```javascript
const url = 'https://{your_space_name}.signalwire.com/api/relay/rest/endpoints/sip';
const credentials = btoa(":");
const options = {
method: 'POST',
headers: {
Authorization: `Basic ${credentials}`,
'Content-Type': 'application/json'
},
body: '{"username":"c3p0","password":"yavinOrBust"}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{your_space_name}.signalwire.com/api/relay/rest/endpoints/sip"
payload := strings.NewReader("{\n \"username\": \"c3p0\",\n \"password\": \"yavinOrBust\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.SetBasicAuth("", "")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://{your_space_name}.signalwire.com/api/relay/rest/endpoints/sip")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request.basic_auth("", "")
request["Content-Type"] = 'application/json'
request.body = "{\n \"username\": \"c3p0\",\n \"password\": \"yavinOrBust\"\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://{your_space_name}.signalwire.com/api/relay/rest/endpoints/sip")
.basicAuth("", "")
.header("Content-Type", "application/json")
.body("{\n \"username\": \"c3p0\",\n \"password\": \"yavinOrBust\"\n}")
.asString();
```
```php
request('POST', 'https://{your_space_name}.signalwire.com/api/relay/rest/endpoints/sip', [
'body' => '{
"username": "c3p0",
"password": "yavinOrBust"
}',
'headers' => [
'Content-Type' => 'application/json',
],
'auth' => ['', ''],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
using RestSharp.Authenticators;
var client = new RestClient("https://{your_space_name}.signalwire.com/api/relay/rest/endpoints/sip");
client.Authenticator = new HttpBasicAuthenticator("", "");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"username\": \"c3p0\",\n \"password\": \"yavinOrBust\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let credentials = Data(":".utf8).base64EncodedString()
let headers = [
"Authorization": "Basic \(credentials)",
"Content-Type": "application/json"
]
let parameters = [
"username": "c3p0",
"password": "yavinOrBust"
] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://{your_space_name}.signalwire.com/api/relay/rest/endpoints/sip")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```