Incoming trunks¶

This endpoint provides the ability to manage Incoming Trunks (Inbound Trunks in UI) and their settings in customer accounts.

Incoming trunks are used to receive incoming traffic from DID numbers. A single customer may include an unlimited amount of incoming trunks, however, a single trunk for each customer account is sufficient in most cases.

Each incoming trunk has a unique domain that is generated automatically during the creation process.

Important

Your commercial account may be configured to create an incoming trunk by default for every newly created customer.

All calls from the DID provider to the PBX are reflected in the Incoming Trunk CDRs.

The following HTTP method(s) are available:

GET /incoming_trunks - For Fetching incoming trunks
POST /incoming_trunks - For Creating an incoming trunk
DELETE /incoming_trunks/{id} - For Deleting an incoming trunk
PATCH /incoming_trunks/{id} - For Updating an incoming trunk

Relationship to other resources:

Name	Resource Type	Relationship Type	Updatable	Description
customer	customers	To-one	No	Parent customer includes this incoming trunk

Hint

Relationships can be used with include and fields parameters if the method supports it.

Creating an Incoming Trunk¶

Use the HTTP POST method to create a new Incoming Trunk:

POST

/api/rest/public/operator/incoming_trunks

This method supports Sparse fieldsets and Inclusion of related resources

Attributes:

Attribute	Value	Description	Optional	Controlled via UI
name	Any string	Trunk name. May be used as a secondary identifier or displayed in the UI.	Yes, default is null	Yes
transport_protocol	“UDP”, “TCP”	Preferred transport protocol for this incoming trunk	Yes, default is UDP	Yes
codecs	“g729”, “G722”, “GSM”, “PCMA”, “PCMU”, “OPUS”, “telephone-event”	Allowed codecs for this incoming trunk	Yes, defaults may vary per commercial account	Yes
destination_field	“RURI_USERPART”, “TO_USERPART”	Incoming Trunk DID number lookup mode	Yes, default is RURI_USERPART	Yes

Request and Response examples:

http

POST /api/rest/public/operator/incoming_trunks HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

{
  "data": {
    "type": "incoming_trunks",
    "attributes": {
      "name": "From provider",
      "transport_protocol": "UDP",
      "destination_field": "RURI_USERPART",
      "codecs": [
        "PCMU","PCMA","telephone-event/8000"
      ]
    },
    "relationships": {
      "customer": {
        "data": {
          "id": "123",
          "type": "customers"
        }
      }
    }
  }
}

curl

curl -i -X POST https://api.telecom.center/api/rest/public/operator/incoming_trunks -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"codecs": ["PCMU", "PCMA", "telephone-event/8000"], "destination_field": "RURI_USERPART", "name": "From provider", "transport_protocol": "UDP"}, "relationships": {"customer": {"data": {"id": "123", "type": "customers"}}}, "type": "incoming_trunks"}}' --user username:password

response

HTTP/2 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "9f5021f5-210d-4194-bcc6-f4f9141fb3a8",
    "type": "incoming_trunks",
    "links": {
      "self": "https://api.telecom.center/api/rest/public/operator/incoming_trunks/9f5021f5-210d-4194-bcc6-f4f9141fb3a8"
    },
    "attributes": {
      "name": "From provider",
      "codecs": [
        "PCMU",
        "PCMA",
        "telephone-event/8000"
      ],
      "transport_protocol": "UDP",
      "domain": "3391285728100.did-gw-sandbox.phone.systems",
      "destination_field": "RURI_USERPART"
    }
  }
}

The response body contains a domain attribute that should be used as the Host part of the SIP URI when forwarding calls to this trunk.

Fetching Incoming Trunks¶

Use the HTTP GET method to retrieve a list of Incoming Trunks:

GET

/api/rest/public/operator/incoming_trunks

This method supports Sorting, Pagination, Sparse fieldsets and Inclusion of related resources

Other supported parameters:

Parameter	Value	Description
filter[customer.id]	Customer ID	Used for filtering Incoming Trunks by Customer ID
filter[domain]	The unique incoming trunk domain	Used for filtering Incoming Trunks by Domain
filter[id]	Incoming Trunk ID	Used for filtering results by Incoming Trunk ID

Request and Response examples:

http

GET /api/rest/public/operator/incoming_trunks HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

curl

curl -i -X GET https://api.telecom.center/api/rest/public/operator/incoming_trunks -H "Content-Type: application/vnd.api+json" --user username:password

response

HTTP/2 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "7b473ea4-f583-4a84-b862-db3dc0b20f8a",
      "type": "incoming_trunks",
      "links": {
        "self": "https://api.telecom.center/api/rest/public/operator/incoming_trunks/7b473ea4-f583-4a84-b862-db3dc0b20f8a"
      },
      "attributes": {
        "name": "Default",
        "codecs": [
          "PCMU",
          "PCMA",
          "telephone-event/8000"
        ],
        "transport_protocol": "UDP",
        "domain": "3391246915096.did-gw-sandbox.phone.systems",
        "destination_field": "RURI_USERPART"
      }
    },
    {
      "id": "95c00bac-989f-4ae1-95e8-66bea63bf998",
      "type": "incoming_trunks",
      "links": {
        "self": "https://api.telecom.center/api/rest/public/operator/incoming_trunks/95c00bac-989f-4ae1-95e8-66bea63bf998"
      },
      "attributes": {
        "name": "Default",
        "codecs": [
          "PCMU",
          "PCMA",
          "telephone-event/8000"
        ],
        "transport_protocol": "UDP",
        "domain": "3391283683653.did-gw-sandbox.phone.systems",
        "destination_field": "RURI_USERPART"
      }
    },
    {
      "id": "960bb5a5-8416-43eb-b55f-b6ce9d984350",
      "type": "incoming_trunks",
      "links": {
        "self": "https://api.telecom.center/api/rest/public/operator/incoming_trunks/960bb5a5-8416-43eb-b55f-b6ce9d984350"
      },
      "attributes": {
        "name": "Default",
        "codecs": [
          "PCMU",
          "PCMA",
          "telephone-event/8000"
        ],
        "transport_protocol": "UDP",
        "domain": "3391283750930.did-gw-sandbox.phone.systems",
        "destination_field": "RURI_USERPART"
      }
    },
    {
      "id": "9f5021f5-210d-4194-bcc6-f4f9141fb3a8",
      "type": "incoming_trunks",
      "links": {
        "self": "https://api.telecom.center/api/rest/public/operator/incoming_trunks/9f5021f5-210d-4194-bcc6-f4f9141fb3a8"
      },
      "attributes": {
        "name": "From provider",
        "codecs": [
          "PCMU",
          "PCMA",
          "telephone-event/8000"
        ],
        "transport_protocol": "UDP",
        "domain": "3391285728100.did-gw-sandbox.phone.systems",
        "destination_field": "RURI_USERPART"
      }
    }
  ],
  "meta": {
    "record_count": 4
  },
  "links": {
    "first": "https://api.telecom.center/api/rest/public/operator/incoming_trunks?page%5Bnumber%5D=1&page%5Bsize%5D=50",
    "last": "https://api.telecom.center/api/rest/public/operator/incoming_trunks?page%5Bnumber%5D=1&page%5Bsize%5D=50"
  }
}

The response body contains an array of all Incoming Trunks.

Additionally, an Incoming Trunk ID may be included to the request URL in order to retrieve a single Incoming Trunk:

GET

/api/rest/public/operator/incoming_trunks/{id}

Updating an Incoming Trunk¶

Use the HTTP PATCH method to update an Incoming Trunk:

PATCH

/api/rest/public/operator/incoming_trunks/{id}

This method supports Sparse fieldsets and Inclusion of related resources

Attributes:

Attribute	Value	Description	Optional	Controlled via UI
name	Any string	Trunk name that is displayed in UI	Yes, default is null	Yes
transport_protocol	“UDP”, “TCP”	Preferred transport protocol for this incoming trunk	Yes, default is UDP	Yes
codecs	“g729”, “G722”, “GSM”, “PCMA”, “PCMU”, “OPUS”	Allowed codecs for this incoming trunk	Yes, defaults may vary per commercial account	Yes
destination_field	“RURI_USERPART”, “TO_USERPART”	Incoming Trunk DID number lookup mode	Yes, default is RURI_USERPART	Yes

Request and Response examples:

http

PATCH /api/rest/public/operator/incoming_trunks/960bb5a5-8416-43eb-b55f-b6ce9d984350 HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

{
  "data": {
    "id": "960bb5a5-8416-43eb-b55f-b6ce9d984350",
    "type": "incoming_trunks",
    "attributes": {
      "name": "Updated trunk",
      "transport_protocol": "TCP",
      "destination_field": "TO_USERPART",
      "codecs": [
        "PCMU"
      ]
    }
  }
}

curl

curl -i -X PATCH https://api.telecom.center/api/rest/public/operator/incoming_trunks/960bb5a5-8416-43eb-b55f-b6ce9d984350 -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"codecs": ["PCMU"], "destination_field": "TO_USERPART", "name": "Updated trunk", "transport_protocol": "TCP"}, "id": "960bb5a5-8416-43eb-b55f-b6ce9d984350", "type": "incoming_trunks"}}' --user username:password

response

HTTP/2 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "960bb5a5-8416-43eb-b55f-b6ce9d984350",
    "type": "incoming_trunks",
    "links": {
      "self": "https://api.telecom.center/api/rest/public/operator/incoming_trunks/960bb5a5-8416-43eb-b55f-b6ce9d984350"
    },
    "attributes": {
      "name": "Updated trunk",
      "codecs": [
        "PCMA"
      ],
      "transport_protocol": "TCP",
      "domain": "3391283750930.did-gw-sandbox.phone.systems",
      "destination_field": "TO_USERPART"
    }
  }
}

Deleting an Incoming Trunk¶

Use the HTTP DELETE method to delete an Incoming Trunk:

DELETE

/api/rest/public/operator/incoming_trunks/{id}

Warning

The unique domain that was assigned to the deleted trunk will also be lost. New incoming trunks will not reuse the deleted unique incoming trunk domains.

Request and Response examples:

http

DELETE /api/rest/public/operator/incoming_trunks/960bb5a5-8416-43eb-b55f-b6ce9d984350 HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

curl

curl -i -X DELETE https://api.telecom.center/api/rest/public/operator/incoming_trunks/960bb5a5-8416-43eb-b55f-b6ce9d984350 -H "Content-Type: application/vnd.api+json" --user username:password

response

HTTP/2 204 No Content
Content-Type: application/vnd.api+json