POST /api/v2/conversations/calls returns 400 — malformed participant address

NICE CXone API & Integrations
1

Why does this setting in my Terraform provisioned endpoint cause a 400 Bad Request when initiating a call via the REST API? I am passing a valid from and to address, yet the response indicates a formatting error. The payload structure adheres to the schema, but the API rejects it.

{
 "error": "Malformed participant address",
 "code": 400
}

Is there a specific URI encoding requirement for the to field that I am missing?

2

This happens because the API expecting a fully qualified URI scheme for the participant address, not just the phone number. You must prefix the from and to values with tel: and ensure the number is formatted as E.164 (e.g., tel:+15551234567).

3

The root cause here is the API expecting a fully qualified URI scheme for the participant address, not just the phone number. You must prefix the from and to values with tel: and ensure the number is formatted as E.164 (e.g., tel:+15551234567).

The docs state “participant addresses must conform to RFC 3966”. Copy-paste this curl to see the correct structure:

curl -X POST "https://{your-domain}.mypurecloud.com/api/v2/conversations/calls" \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer {access_token}" \
 -d '{
 "to": "tel:+15551234567",
 "from": "tel:+15559876543",
 "providerId": "your-provider-id"
 }'
4

Ah, yeah, this is a known issue when Terraform provisions endpoints without enforcing the tel: prefix in the validation logic. I switched to using format("tel:%s", var.phone_number) in my genesyscloud_routing_extension resource, and the 400s stopped immediately.

5

This looks like a schema validation issue.

Why does this setting in my Terraform provisioned endpoint cause a 400 Bad Request when initiating a call via the REST API?

The tel: prefix is mandatory for E.164 compliance. I confirmed this works by adding format("tel:%s", var.phone_number) to my endpoint config.