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 sub-domain 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:

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 domain

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.

Retrieving 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 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 domain

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