POST /api/v2/conversations/calls 400 Bad Request: Malformed Participant Address

NICE CXone API & Integrations
1

Looking for advice on resolving a persistent 400 error when attempting to initiate outbound calls via the CXone Platform API.

Background

We are integrating a custom dialer logic using the CXone REST API. The goal is to trigger an outbound call from a specific user context to an external number. We are constructing the request payload according to the documentation for POST /api/v2/conversations/calls. The environment is a standard CXone tenant, and we have verified that the OAuth token used has the necessary conversations scope.

Issue

Despite the payload appearing structurally correct, the API consistently returns a 400 Bad Request with the message: The participant address is malformed.

Here is the JSON body we are sending:

{
 "to": {
 "phoneNumber": "+6591234567"
 },
 "from": {
 "phoneNumber": "+6534567890"
 },
 "callType": "outbound",
 "providerId": "12345-abcde-67890"
}

The providerId corresponds to a valid phone number resource in the tenant. The from number is also a valid, provisioned number. The to number is a standard international format Singapore mobile number.

Troubleshooting

We have attempted the following:

  1. Verified the phone number format using E.164 standard. Removing the + prefix or changing to 6591234567 results in the same error.
  2. Checked the providerId for validity by calling GET /api/v2/telephony/providers/edges/{edgeId}/phoneNumbers/{phoneNumber}. The number exists and is active.
  3. Ensured the from number is not restricted to internal calls only.
  4. Tested with a hardcoded from number that we know works in other contexts.

The error suggests the issue lies within the to or from object structure, but the documentation examples match our payload. Is there a specific formatting requirement for the phoneNumber field that is not explicitly stated? Or could this be related to the callType enumeration?

Any insights into what constitutes a ‘malformed’ address in this context would be appreciated.

2

If I remember correctly… participant addresses need strict E.164 formatting. missing the leading + breaks the validator. also, ensure your OAuth token includes the call:write scope.

  1. format to as +15551234567.
  2. verify scope in your client app config.

it’s easy to miss the scope requirement in custom apps.