{ "openapi": "3.0.0", "info": { "version": "1.2.0", "title": "Programmable SIP API", "x-metaTitle": "Vonage Programmable SIP API Reference | Vonage API Documentation", "x-metaDescription": "Find quick answers to questions about the Vonage Programmable SIP API in this reference guide. Learn more in Vonage's API documentation.", "description": "The Programmable SIP API lets you create and configure Programmable SIP Domains in Vonage's platform.", "contact": { "name": "Vonage DevRel", "email": "devrel@vonage.com", "url": "https://developer.vonage.com/" } }, "servers": [ { "url": "https://api.nexmo.com/v1/psip" } ], "paths": { "/": { "post": { "tags": [ "Domains" ], "security": [ { "basicAuth": [] } ], "summary": "Create a PSIP domain", "description": "Create a new PSIP domain.", "operationId": "createDomain", "requestBody": { "description": "Create a new PSIP domain", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DomainObject" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainObject" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInvalidJson" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorVerificationFailed" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInternal" } } } } } }, "get": { "tags": [ "Domains" ], "security": [ { "basicAuth": [] } ], "summary": "Get all of your PSIP domains", "description": "Get all of your PSIP domains.", "operationId": "getDomains", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DomainObject" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInternal" } } } } } } }, "/{domain}": { "get": { "tags": [ "Domains" ], "security": [ { "basicAuth": [] } ], "summary": "Get details of your PSIP domain", "description": "Get details of your PSIP domain.", "operationId": "getDomain", "parameters": [ { "name": "domain", "required": true, "in": "path", "description": "Filter by domain name.", "schema": { "type": "string", "example": "mydomain" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainObject" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInternal" } } } } } }, "put": { "tags": [ "Domains" ], "security": [ { "basicAuth": [] } ], "summary": "Update a PSIP domain", "description": "Update a PSIP domain.", "operationId": "updateDomain", "parameters": [ { "name": "domain", "required": true, "in": "path", "description": "Filter by domain name.", "schema": { "type": "string", "example": "mydomain" } } ], "requestBody": { "description": "Update a PSIP domain", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DomainObject" } ] } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainObject" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInvalidJson" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorVerificationFailed" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInternal" } } } } } }, "delete": { "tags": [ "Domains" ], "security": [ { "basicAuth": [] } ], "summary": "Delete PSIP domain", "description": "Delete a PSIP domain.", "operationId": "deleteDomain", "parameters": [ { "name": "domain", "required": true, "in": "path", "description": "Filter by domain name.", "schema": { "type": "string", "example": "mydomain" } }, { "in": "query", "name": "cascade", "schema": { "type": "boolean" }, "description": "Whether the delete request should cascade to the domain's users." } ], "responses": { "200": { "description": "Deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorActiveAuthUsers" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInternal" } } } } } } }, "/{domain}/users": { "post": { "tags": [ "Domain Users" ], "security": [ { "basicAuth": [] } ], "summary": "Create a PSIP domain user", "description": "Create a new PSIP domain user, up to 200 per domain.", "operationId": "createDomainUser", "requestBody": { "description": "Create a new PSIP domain user", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DomainUserRequest" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUserResponse" } } } } } }, "get": { "tags": [ "Domain Users" ], "security": [ { "basicAuth": [] } ], "summary": "Get all of your PSIP domain's digest users", "description": "Retrieve a list of your PSIP domain's digest users.", "operationId": "getDomainUsers", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUsersResponse" } } } } } } }, "/{domain}/users/{key}": { "get": { "tags": [ "Domain Users" ], "security": [ { "basicAuth": [] } ], "summary": "Check existence of a PSIP domain user", "description": "Validate a PSIP domain user.", "operationId": "validateDomainUser", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUserResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Unprocessable Entity" } } }, "put": { "tags": [ "Domain Users" ], "security": [ { "basicAuth": [] } ], "summary": "Update a PSIP domain user", "description": "Update a PSIP domain user.", "operationId": "updateDomainUser", "requestBody": { "description": "Update a PSIP domain user", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DomainUserRequest" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUserResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } } }, "delete": { "tags": [ "Domain Users" ], "security": [ { "basicAuth": [] } ], "summary": "Delete a PSIP domain user", "description": "Delete a PSIP domain user.", "operationId": "deleteDomainUser", "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } } } }, "/{domain}/endpoints": { "post": { "tags": [ "Domain Endpoints" ], "security": [ { "basicAuth": [] } ], "summary": "Create an endpoint for a PSIP domain", "description": "Create a new PSIP domain endpoint", "operationId": "createDomainEndpoint", "requestBody": { "description": "Create a new PSIP domain endpoint", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Endpoint" } ] } } } }, "responses": { "200": { "description": "OK" } } }, "get": { "tags": [ "Domain Endpoints" ], "security": [ { "basicAuth": [] } ], "summary": "Get all of your PSIP domain's endpoint", "description": "Retrieve a list of your PSIP domain's endpoints", "operationId": "getDomainEndpoints", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } } } } } } } }, "/{domain}/endpoints/{endpointId}": { "get": { "tags": [ "Domain Endpoints" ], "security": [ { "basicAuth": [] } ], "summary": "Check existence of a PSIP domain endpoint", "description": "Validate a PSIP domain endpoint", "operationId": "readDomainEndpoint", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Endpoint" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Unprocessable Entity" } } }, "put": { "tags": [ "Domain Endpoints" ], "security": [ { "basicAuth": [] } ], "summary": "Update a PSIP domain endpoint", "description": "Update a PSIP domain endpoint", "operationId": "updateDomainEndpoint", "requestBody": { "description": "Update a PSIP domain endpoint", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Endpoint" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Endpoint" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } } }, "delete": { "tags": [ "Domain Endpoints" ], "security": [ { "basicAuth": [] } ], "summary": "Delete a PSIP domain endpoint", "description": "Delete a PSIP domain endpoint", "operationId": "deleteDomainEndpoint", "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } }, "schemas": { "name": { "title": "Domain name", "type": "string", "example": "mydomain", "minLength": 5, "maxLength": 32, "description": "The customised SIP domain that will used in Programmable SIP: mydomain.sip-eu.nexmo.com.", "pattern": "[a-zA-Z0-9][a-zA-Z0-9\\-]{3,30}[a-zA-Z0-9]" }, "application_id": { "title": "Application ID", "type": "string", "example": "c49f3586-9b3b-458b-89fc-3c8beb58865c", "description": "Vonage Application ID to associate with the domain.", "pattern": "[a-zA-Z0-9][a-zA-Z0-9\\-]{3,62}[a-zA-Z0-9]" }, "tls": { "title": "TLS", "type": "string", "enum": [ "always", "never", "optional" ], "default": "optional", "description": "Require TLS use in SIP connection. Optional allows customer to choose. Always will require it to always be used. Never will require it to never be used." }, "srtp": { "title": "SRTP", "type": "string", "enum": [ "always", "never", "optional" ], "default": "optional", "description": "Require SRTP use in SIP connection. Optional allows customer to choose. Always will require it to always be used. Never will require it to never be used." }, "digest_auth": { "title": "Digest Authentication", "type": "boolean", "default": "false", "example": false, "description": "Allow definition of up to 200 users that can use Digest Authentication to access domain." }, "acl": { "title": "Access Control List", "type": "array", "minItems": 1, "maxItems": 16, "example": [ "50.127.127.0/29", "50.128.128.0/29" ], "description": "Access Control List of IPs that can make calls to domain. Can use CIDR notation to facilitate inclusion of IP ranges.", "items": { "$ref": "#/components/schemas/aclItem" } }, "aclItem": { "title": "ACL Item", "type": "string", "example": "50.127.127.0/29" }, "domain_type": { "title": "Domain Type", "type": "string", "enum": [ "app", "trunk" ], "default": "app", "example": "app", "description": "Type of domain. 'app' for PSIP application, 'trunk' for SIP trunking" }, "trunk_name": { "type": "string", "pattern": "[a-zA-Z0-9][a-zA-Z0-9\\-]{3,30}[a-zA-Z0-9]", "minLength": 5, "maxLength": 32, "description": "An optional friendly name for display purposes" }, "description": { "type": "string", "description": "An optional description for display purposes" }, "DomainObject": { "title": "Domain", "type": "object", "required": [ "name", "application_id", "acl" ], "properties": { "name": { "$ref": "#/components/schemas/name" }, "application_id": { "$ref": "#/components/schemas/application_id" }, "tls": { "$ref": "#/components/schemas/tls" }, "digest_auth": { "$ref": "#/components/schemas/digest_auth" }, "srtp": { "$ref": "#/components/schemas/srtp" }, "acl": { "$ref": "#/components/schemas/acl" }, "domain_type": { "$ref": "#/components/schemas/domain_type" } } }, "user_key": { "title": "Domain's User Key", "type": "string", "description": "The user's key and unique identifier. Permitted list of characters is alphanumeric (a-z, 0-9) and dash (-).", "example": "user-1", "pattern": "[a-zA-Z0-9][a-zA-Z0-9\\-]{3,30}[a-zA-Z0-9]" }, "user_secret": { "title": "Domain's User Secret", "type": "string", "description": "The user's secret to do authentication.", "example": "mysupersecretsecret" }, "endpoint_priority": { "title": "Endpoint priority", "type": "integer", "minimum": 0, "maximum": 100, "description": "The priority of this endpoint when sending calls to one of the domain's endpoints. A numeric value where a lower value means higher priority." }, "endpoint_uri": { "title": "SIP URI", "type": "string", "description": "A SIP URI to deliver incoming calls for this domain.", "example": "sip:myendpoint@mydomain.example.com:5060" }, "DomainUserRequest": { "title": "Domain User properties", "type": "object", "required": [ "key", "secret" ], "properties": { "key": { "$ref": "#/components/schemas/user_key" }, "secret": { "$ref": "#/components/schemas/user_secret" } } }, "DomainUserResponse": { "title": "Domain User metadata", "type": "object", "properties": { "key": { "$ref": "#/components/schemas/user_key" }, "domain": { "$ref": "#/components/schemas/name" } } }, "DomainUsersResponse": { "title": "Domain Users list", "type": "array", "items": { "$ref": "#/components/schemas/DomainUserResponse" }, "example": [ { "key": "user-1", "domain": "mydomain" }, { "key": "user-0", "domain": "mydomain" } ] }, "Endpoint": { "title": "Domain Endpoint", "type": "object", "required": [ "uri" ], "properties": { "id": { "type": "string", "description": "The unique id of the endpoint in this domain." }, "priority": { "$ref": "#/components/schemas/endpoint_priority" }, "uri": { "$ref": "#/components/schemas/endpoint_uri" } } }, "ErrorNotFound": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "https://developer.vonage.com/api-errors#not-found" ], "example": "https://developer.vonage.com/api-errors#not-found" }, "title": { "type": "string", "enum": [ "Invalid domain selected" ], "example": "Invalid domain selected" }, "detail": { "type": "string", "enum": [ "The domain you're trying to interact with is invalid" ], "example": "The domain you're trying to interact with is invalid" }, "error_code": { "type": "string", "example": 8 } } }, "ErrorUnauthorized": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "https://developer.vonage.com/api-errors#unauthorized" ], "example": "https://developer.vonage.com/api-errors#unauthorized" }, "title": { "type": "string", "enum": [ "Invalid credentials supplied" ], "example": "Invalid credentials supplied" }, "detail": { "type": "string", "enum": [ "You did not provide credentials." ], "example": "You did not provide credentials." } } }, "ErrorVerificationFailed": { "type": "object", "properties": { "title": { "type": "string", "enum": [ "Unprocessable Entity-Invalid request parameters" ], "example": "Unprocessable Entity-Invalid request parameters" }, "detail": { "type": "string", "enum": [ "Request lacks domain's name, acl or application id" ], "example": "Request lacks domain's name, acl or application id" }, "error_code": { "type": "string", "example": 5 } } }, "ErrorInternal": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "https://developer.vonage.com/api-errors" ], "example": "https://developer.vonage.com/api-errors" }, "title": { "type": "string", "enum": [ "Service internal #InternalError" ], "example": "Service internal #InternalError" }, "detail": { "type": "string", "enum": [ "An unknown error encountered" ], "example": "An unknown error encountered" } } }, "ErrorInvalidJson": { "description": "Invalid JSON", "type": "object", "properties": { "type": { "type": "string", "enum": [ "https://developer.vonage.com/api-errors" ], "example": "https://developer.vonage.com/api-errors" }, "title": { "type": "string", "enum": [ "The request body did not contain valid JSON" ], "example": "The request body did not contain valid JSON" }, "detail": { "type": "string", "example": "Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries" }, "error_code": { "type": "string", "example": 8 } } }, "ErrorActiveAuthUsers": { "type": "object", "properties": { "title": { "type": "string", "enum": [ "Unprocessable Entity" ], "example": "Unprocessable Entity" }, "detail": { "type": "string", "enum": [ "Cannot delete domain with active auth users" ], "example": "Cannot delete domain with active auth users" }, "error_code": { "type": "string", "example": 104 } } } } }, "tags": [ { "name": "Domains", "description": "Methods for managing SIP domains." }, { "name": "Domain Users", "description": "Methods for managing users in a SIP domain." }, { "name": "Domain Endpoints", "description": "Methods for managing endpoints in a SIP domain." } ] }