Phone Number

Update Custom VoIP Number

Patches a custom VoIP phone number: only the fields present in the body are updated, the others are left untouched. A provided inbound (sipConfig) or outbound (sipTrunkConfig) configuration replaces the current one as a whole; setting it to null removes it and the direction is recomputed. Removing the inbound configuration while a live inbound Pearl uses the number, or the outbound configuration while any live Pearl uses it, is rejected with a 400 and nothing is changed. The phoneNumberId is the id returned by Get Phone Numbers.

PUT

PhoneNumber

CustomVoip

{phoneNumberId}

Update Custom VoIP Number

curl --request PUT \
  --url https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": {
    "value": "<string>"
  },
  "displayName": {
    "value": "<string>"
  },
  "sipConfig": {
    "value": {
      "authMethod": {
        "userNamePassword": {
          "username": "<string>",
          "password": "<string>"
        },
        "ips": [
          "<string>"
        ]
      },
      "isTLS": true
    }
  },
  "sipTrunkConfig": {
    "value": {
      "sipTrunk": "<string>",
      "from": "<string>",
      "edge": "<string>",
      "authMethod": {
        "userNamePassword": {
          "username": "<string>",
          "password": "<string>"
        },
        "headers": {}
      },
      "isTLS": true,
      "isSipRefer": true
    }
  }
}
'

import requests

url = "https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId}"

payload = {
    "number": { "value": "<string>" },
    "displayName": { "value": "<string>" },
    "sipConfig": { "value": {
            "authMethod": {
                "userNamePassword": {
                    "username": "<string>",
                    "password": "<string>"
                },
                "ips": ["<string>"]
            },
            "isTLS": True
        } },
    "sipTrunkConfig": { "value": {
            "sipTrunk": "<string>",
            "from": "<string>",
            "edge": "<string>",
            "authMethod": {
                "userNamePassword": {
                    "username": "<string>",
                    "password": "<string>"
                },
                "headers": {}
            },
            "isTLS": True,
            "isSipRefer": True
        } }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    number: {value: '<string>'},
    displayName: {value: '<string>'},
    sipConfig: {
      value: {
        authMethod: {
          userNamePassword: {username: '<string>', password: '<string>'},
          ips: ['<string>']
        },
        isTLS: true
      }
    },
    sipTrunkConfig: {
      value: {
        sipTrunk: '<string>',
        from: '<string>',
        edge: '<string>',
        authMethod: {userNamePassword: {username: '<string>', password: '<string>'}, headers: {}},
        isTLS: true,
        isSipRefer: true
      }
    }
  })
};

fetch('https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'number' => [
        'value' => '<string>'
    ],
    'displayName' => [
        'value' => '<string>'
    ],
    'sipConfig' => [
        'value' => [
                'authMethod' => [
                                'userNamePassword' => [
                                                                'username' => '<string>',
                                                                'password' => '<string>'
                                ],
                                'ips' => [
                                                                '<string>'
                                ]
                ],
                'isTLS' => true
        ]
    ],
    'sipTrunkConfig' => [
        'value' => [
                'sipTrunk' => '<string>',
                'from' => '<string>',
                'edge' => '<string>',
                'authMethod' => [
                                'userNamePassword' => [
                                                                'username' => '<string>',
                                                                'password' => '<string>'
                                ],
                                'headers' => [
                                                                
                                ]
                ],
                'isTLS' => true,
                'isSipRefer' => true
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId}"

	payload := strings.NewReader("{\n  \"number\": {\n    \"value\": \"<string>\"\n  },\n  \"displayName\": {\n    \"value\": \"<string>\"\n  },\n  \"sipConfig\": {\n    \"value\": {\n      \"authMethod\": {\n        \"userNamePassword\": {\n          \"username\": \"<string>\",\n          \"password\": \"<string>\"\n        },\n        \"ips\": [\n          \"<string>\"\n        ]\n      },\n      \"isTLS\": true\n    }\n  },\n  \"sipTrunkConfig\": {\n    \"value\": {\n      \"sipTrunk\": \"<string>\",\n      \"from\": \"<string>\",\n      \"edge\": \"<string>\",\n      \"authMethod\": {\n        \"userNamePassword\": {\n          \"username\": \"<string>\",\n          \"password\": \"<string>\"\n        },\n        \"headers\": {}\n      },\n      \"isTLS\": true,\n      \"isSipRefer\": true\n    }\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"number\": {\n    \"value\": \"<string>\"\n  },\n  \"displayName\": {\n    \"value\": \"<string>\"\n  },\n  \"sipConfig\": {\n    \"value\": {\n      \"authMethod\": {\n        \"userNamePassword\": {\n          \"username\": \"<string>\",\n          \"password\": \"<string>\"\n        },\n        \"ips\": [\n          \"<string>\"\n        ]\n      },\n      \"isTLS\": true\n    }\n  },\n  \"sipTrunkConfig\": {\n    \"value\": {\n      \"sipTrunk\": \"<string>\",\n      \"from\": \"<string>\",\n      \"edge\": \"<string>\",\n      \"authMethod\": {\n        \"userNamePassword\": {\n          \"username\": \"<string>\",\n          \"password\": \"<string>\"\n        },\n        \"headers\": {}\n      },\n      \"isTLS\": true,\n      \"isSipRefer\": true\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"number\": {\n    \"value\": \"<string>\"\n  },\n  \"displayName\": {\n    \"value\": \"<string>\"\n  },\n  \"sipConfig\": {\n    \"value\": {\n      \"authMethod\": {\n        \"userNamePassword\": {\n          \"username\": \"<string>\",\n          \"password\": \"<string>\"\n        },\n        \"ips\": [\n          \"<string>\"\n        ]\n      },\n      \"isTLS\": true\n    }\n  },\n  \"sipTrunkConfig\": {\n    \"value\": {\n      \"sipTrunk\": \"<string>\",\n      \"from\": \"<string>\",\n      \"edge\": \"<string>\",\n      \"authMethod\": {\n        \"userNamePassword\": {\n          \"username\": \"<string>\",\n          \"password\": \"<string>\"\n        },\n        \"headers\": {}\n      },\n      \"isTLS\": true,\n      \"isSipRefer\": true\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "number": "<string>",
  "displayName": "<string>",
  "direction": 123,
  "type": 123,
  "sipConfig": {
    "domain": "<string>",
    "isTLS": true,
    "authMethod": {
      "userNamePassword": {
        "username": "<string>"
      },
      "ips": [
        "<string>"
      ]
    }
  },
  "sipTrunkConfig": {
    "sipTrunk": "<string>",
    "edge": "<string>",
    "isTLS": true,
    "from": "<string>",
    "isSipRefer": true,
    "authMethod": {
      "userNamePassword": {
        "username": "<string>"
      },
      "headers": {}
    }
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": {}
}

Authorizations

Authorization

string

header

required

Specify the authorization token.

For more information, check out the Authorization Guide.

Path Parameters

phoneNumberId

string

required

Body

Data used to update a custom VoIP phone number. Only the fields present in the body are applied: a field left out keeps its current value. A provided configuration replaces the current one as a whole, and null removes it.

number

object

The phone number, preferably in E.164 format (for example +14155550123). Max 100 characters.

Show child attributes

displayName

object

The display name of the phone number (max 100 characters). Send null or an empty value to clear it: the raw number is then displayed instead.

Show child attributes

sipConfig

object

The inbound SIP configuration. A provided configuration replaces the current one as a whole. Send null to remove the inbound configuration and release its SIP domain. This is rejected while a live inbound Pearl uses the number.

Show child attributes

sipTrunkConfig

object

The outbound SIP trunk configuration. A provided configuration replaces the current one as a whole. Send null to remove the outbound configuration. This is rejected while a live Pearl uses the number, because outbound calls and call transfers go through it.

Show child attributes

Response

The updated custom VoIP phone number, including the SIP domain when inbound is configured.

A phone number of the account as exposed by the API. For custom VoIP numbers it also carries the configured inbound and/or outbound SIP setup (passwords are never returned).

string | null

The unique identifier of the phone number.

number

string | null

The phone number, in E.164 format (a custom VoIP number is returned as it was entered).

displayName

string | null

The display name of the phone number. Falls back to the raw number when no display name is set.

direction

integer<int32>

Phone number direction (supported call capabilities).

InboundOutbound: Supports both inbound and outbound calls.
Inbound: Supports inbound calls only.
Outbound: Supports outbound calls only.
NotSet: Direction is not set.

1 - InboundOutbound

2 - Inbound

3 - Outbound

10 - NotSet

type

integer<int32>

Indicates how the phone number is provisioned and connected to NLPearl.

NLPearlDefault: a shared default number provided by NLPearl.
NLPearl: a number purchased and managed for you by NLPearl.
Twilio: a number from your own Twilio account that you connected.
CustomVoip: a custom VoIP number you connect over SIP.
Undefined: the type could not be determined.

1 - NLPearlDefault

2 - NLPearl

3 - Twilio

4 - CustomVoip

99 - Undefined

sipConfig

object | null

The inbound SIP configuration. Present only for custom VoIP numbers that have inbound configured; passwords are never returned.

Show child attributes

sipTrunkConfig

object | null

The outbound SIP trunk configuration. Present only for custom VoIP numbers that have outbound configured; passwords are never returned.

Show child attributes

Update Custom VoIP Number

curl --request PUT \
  --url https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": {
    "value": "<string>"
  },
  "displayName": {
    "value": "<string>"
  },
  "sipConfig": {
    "value": {
      "authMethod": {
        "userNamePassword": {
          "username": "<string>",
          "password": "<string>"
        },
        "ips": [
          "<string>"
        ]
      },
      "isTLS": true
    }
  },
  "sipTrunkConfig": {
    "value": {
      "sipTrunk": "<string>",
      "from": "<string>",
      "edge": "<string>",
      "authMethod": {
        "userNamePassword": {
          "username": "<string>",
          "password": "<string>"
        },
        "headers": {}
      },
      "isTLS": true,
      "isSipRefer": true
    }
  }
}
'

import requests

url = "https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId}"

payload = {
    "number": { "value": "<string>" },
    "displayName": { "value": "<string>" },
    "sipConfig": { "value": {
            "authMethod": {
                "userNamePassword": {
                    "username": "<string>",
                    "password": "<string>"
                },
                "ips": ["<string>"]
            },
            "isTLS": True
        } },
    "sipTrunkConfig": { "value": {
            "sipTrunk": "<string>",
            "from": "<string>",
            "edge": "<string>",
            "authMethod": {
                "userNamePassword": {
                    "username": "<string>",
                    "password": "<string>"
                },
                "headers": {}
            },
            "isTLS": True,
            "isSipRefer": True
        } }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    number: {value: '<string>'},
    displayName: {value: '<string>'},
    sipConfig: {
      value: {
        authMethod: {
          userNamePassword: {username: '<string>', password: '<string>'},
          ips: ['<string>']
        },
        isTLS: true
      }
    },
    sipTrunkConfig: {
      value: {
        sipTrunk: '<string>',
        from: '<string>',
        edge: '<string>',
        authMethod: {userNamePassword: {username: '<string>', password: '<string>'}, headers: {}},
        isTLS: true,
        isSipRefer: true
      }
    }
  })
};

fetch('https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'number' => [
        'value' => '<string>'
    ],
    'displayName' => [
        'value' => '<string>'
    ],
    'sipConfig' => [
        'value' => [
                'authMethod' => [
                                'userNamePassword' => [
                                                                'username' => '<string>',
                                                                'password' => '<string>'
                                ],
                                'ips' => [
                                                                '<string>'
                                ]
                ],
                'isTLS' => true
        ]
    ],
    'sipTrunkConfig' => [
        'value' => [
                'sipTrunk' => '<string>',
                'from' => '<string>',
                'edge' => '<string>',
                'authMethod' => [
                                'userNamePassword' => [
                                                                'username' => '<string>',
                                                                'password' => '<string>'
                                ],
                                'headers' => [
                                                                
                                ]
                ],
                'isTLS' => true,
                'isSipRefer' => true
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId}"

	payload := strings.NewReader("{\n  \"number\": {\n    \"value\": \"<string>\"\n  },\n  \"displayName\": {\n    \"value\": \"<string>\"\n  },\n  \"sipConfig\": {\n    \"value\": {\n      \"authMethod\": {\n        \"userNamePassword\": {\n          \"username\": \"<string>\",\n          \"password\": \"<string>\"\n        },\n        \"ips\": [\n          \"<string>\"\n        ]\n      },\n      \"isTLS\": true\n    }\n  },\n  \"sipTrunkConfig\": {\n    \"value\": {\n      \"sipTrunk\": \"<string>\",\n      \"from\": \"<string>\",\n      \"edge\": \"<string>\",\n      \"authMethod\": {\n        \"userNamePassword\": {\n          \"username\": \"<string>\",\n          \"password\": \"<string>\"\n        },\n        \"headers\": {}\n      },\n      \"isTLS\": true,\n      \"isSipRefer\": true\n    }\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"number\": {\n    \"value\": \"<string>\"\n  },\n  \"displayName\": {\n    \"value\": \"<string>\"\n  },\n  \"sipConfig\": {\n    \"value\": {\n      \"authMethod\": {\n        \"userNamePassword\": {\n          \"username\": \"<string>\",\n          \"password\": \"<string>\"\n        },\n        \"ips\": [\n          \"<string>\"\n        ]\n      },\n      \"isTLS\": true\n    }\n  },\n  \"sipTrunkConfig\": {\n    \"value\": {\n      \"sipTrunk\": \"<string>\",\n      \"from\": \"<string>\",\n      \"edge\": \"<string>\",\n      \"authMethod\": {\n        \"userNamePassword\": {\n          \"username\": \"<string>\",\n          \"password\": \"<string>\"\n        },\n        \"headers\": {}\n      },\n      \"isTLS\": true,\n      \"isSipRefer\": true\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nlpearl.ai/v2/PhoneNumber/CustomVoip/{phoneNumberId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"number\": {\n    \"value\": \"<string>\"\n  },\n  \"displayName\": {\n    \"value\": \"<string>\"\n  },\n  \"sipConfig\": {\n    \"value\": {\n      \"authMethod\": {\n        \"userNamePassword\": {\n          \"username\": \"<string>\",\n          \"password\": \"<string>\"\n        },\n        \"ips\": [\n          \"<string>\"\n        ]\n      },\n      \"isTLS\": true\n    }\n  },\n  \"sipTrunkConfig\": {\n    \"value\": {\n      \"sipTrunk\": \"<string>\",\n      \"from\": \"<string>\",\n      \"edge\": \"<string>\",\n      \"authMethod\": {\n        \"userNamePassword\": {\n          \"username\": \"<string>\",\n          \"password\": \"<string>\"\n        },\n        \"headers\": {}\n      },\n      \"isTLS\": true,\n      \"isSipRefer\": true\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "number": "<string>",
  "displayName": "<string>",
  "direction": 123,
  "type": 123,
  "sipConfig": {
    "domain": "<string>",
    "isTLS": true,
    "authMethod": {
      "userNamePassword": {
        "username": "<string>"
      },
      "ips": [
        "<string>"
      ]
    }
  },
  "sipTrunkConfig": {
    "sipTrunk": "<string>",
    "edge": "<string>",
    "isTLS": true,
    "from": "<string>",
    "isSipRefer": true,
    "authMethod": {
      "userNamePassword": {
        "username": "<string>"
      },
      "headers": {}
    }
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": {}
}

Getting Started

API V2

API V1

Update Custom VoIP Number

Authorizations

Path Parameters

Body

Response