Update Endpoint

This request updates an endpoint, targeted by secure ID.

patch	/endpoints/{endpoint_sid}
put	/endpoints/{endpoint_sid}

Sample

A sample PATCH request to update the Endpoint object, targeted by secure ID, with the values in the request body:

curl -X PATCH \
'https://api.carrierx.com/core/v2/endpoints/00bf8b25-1e20-4f80-8529-8448df32d71a' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_third_party_ep"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the updated Endpoint object:

{
    "addresses": [
        {
            "direction": "any",
            "dst_port": 5060,
            "ip": "1.1.2.13",
            "location_sid": null,
            "port": 5060,
            "priority": 0,
            "sip_password": null,
            "sip_username": null,
            "srtp": false,
            "transport": "udp"
        }
    ],
    "attributes": {},
    "auth_required": true,
    "capacity": 0,
    "cps_limit": null,
    "endpoint_sid": "1a34c5e9-3a09-4de5-b553-5f6a9ef202ac",
    "name": "my_third_party_ep",
    "out_sip_password": null,
    "out_sip_username": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "properties": {},
    "transformations": [],
    "type": "third_party",
    "voip_token": "2c95517b-a5e8-4415-b471-cdd81d5a6dcb"
}

An Endpoint object can be updated using either a PATCH or PUT request.

• A PATCH request can be used to update one or more attribute values. When using a PATCH request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The endpoint secure ID is passed in the query URL, and the values to be modified are passed in the request body.

  The Endpoint object also contains nested Addresses, Attributes, Properties, and Transformations objects. Refer to this section to learn how nested objects can be updated using the PATCH request.

• A PUT request can be used to update an entire Endpoint object. The endpoint secure ID is passed in the query URL, and the entire Endpoint object is passed in the request body.

note

Note, while all the fields must be present in a PUT request, not all the attribute values may be modified after the initial creation, because when created, some of them become read-only.

Errors

Missing Required Scope

If you attempt to create or update an endpoint by setting the auth_required field without the necessary permissions, you will receive the following error:

{
    "message": "object validation error",
    "errors": [
        {
            "field": "auth_required",
            "message": "partner does not have permissions to set this value",
            "reference_sid": null
        }
    ]
}

To resolve this error: Contact CarrierX support at support@carrierx.com to request the required permissions for managing the auth_required field.

Duplicate IP for auth_required=false

If you attempt to create an endpoint with auth_required=false using an IP address and port that is already used by another endpoint (system or partner) with auth_required=false, you will receive the following error:

{
    "message": "conflict error",
    "errors": [
        {
            "field": null,
            "message": "duplicate ip for auth_required=false",
            "reference_sid": null
        }
    ]
}

To resolve this error:

• Use a different IP address or port, or
• Set auth_required=true (which allows multiple endpoints on the same IP)

Note: The auth_required field is writable only for partners with the appropriate scope. By default, this field is read-only. Contact CarrierX support to enable write access.

Required Scopes

To update an Endpoint object, the partner must have one of the following scopes enabled:

• endpoints.manage
• endpoints.update

Additional scope for auth_required: To set the auth_required field when creating or updating an endpoint, the partner must also have the endpoints.manage_auth_required scope. Without this scope:

• The auth_required field is read-only
• Any value submitted in the request will result in the "partner does not have permissions to set this value" error shown above

Contact CarrierX support at support@carrierx.com to request the endpoints.manage_auth_required scope.

Path Arguments

Parameter	Data Type	Description
endpoint_sid required	string	The endpoint secure ID.

Query Arguments

Parameter	Data Type	Description
nested_objects	string	Determines if the nested objects fields and values should be replaced. Value accepted in this field is replace.

Body Arguments

JSON representation of the fields and values to be updated.

note

Note that for the Mediator, FlexML, and Conference endpoints, only the name and capacity fields can be updated.

tip

For the Voicemail endpoint, the properties.callback_method, properties.callback_url, properties.container_sid, and properties.greeting can also be updated. Refer to the Voicemail Endpoint quick start guide for more information on how to create and configure Voicemail endpoint.

Refer to this table to view all fields that appear in the Endpoint object.