POST to /api/v2/conversations/calls returning 400 due to malformed participant address

We are attempting to programmatically initiate outbound calls via the Genesys Cloud API from our backend orchestration service. The endpoint being used is POST /api/v2/conversations/calls. The authentication is handled via a valid OAuth2 token, so that part is functioning correctly.

The issue arises when sending the request payload. We are receiving a 400 Bad Request response with the error message indicating a “malformed participant address”. The JSON payload we are sending is as follows:

{
 "to": [
 {
 "address": "+493012345678",
 "addressType": "phoneNumber"
 }
 ],
 "from": {
 "address": "+493098765432",
 "addressType": "phoneNumber"
 }
}

Both the to and from addresses are valid E.164 formatted phone numbers. We have verified that the numbers are not blocked and are correctly formatted according to the documentation. The addressType is explicitly set to phoneNumber.

We have tried variations such as removing the leading plus sign or using the tel: URI scheme, but the same 400 error persists. The API documentation does not provide further details on what constitutes a malformed address in this context.

Has anyone encountered this specific issue? Are there any hidden requirements for the participant address format that are not documented?

Cause: The 400 error isn’t about the phone number format itself. It’s about the fromAddress and toAddress objects being incomplete. The API requires explicit type definitions for each address. If you’re just passing a string or a bare number without the phoneNumber object structure, the validation layer rejects it. Also, check your fromAddress is actually a valid user or number file in your org. If it’s a raw string, it fails.

Solution: You need to wrap the numbers in the correct address object structure. Here’s the exact payload shape that works:

{
 "fromAddress": {
 "phoneNumber": "61212345678",
 "name": "Outbound Caller"
 },
 "toAddress": {
 "phoneNumber": "61412345678",
 "name": "Target"
 },
 "routingData": {
 "skillRequirements": [
 {
 "skill": {
 "id": "your-skill-id-here",
 "name": "General"
 },
 "ficiency": 3
 }
 ]
 }
}

Make sure fromAddress.phoneNumber matches a number visioned to your Genesys Cloud org. If you’re using a user as the caller, you might need to use userId instead of phoneNumber in that object, but for most outbound campaigns, a direct number works.

Also, double-check the OAuth scopes. You need conversation:call:write and conversation:call:view. Missing call:write will give you a 403, but malformed addresses give 400.

One thing that trips people up: the routingData isn’t strictly required if you’re just making a peer-to-peer call, but if you’re routing through a queue, you need it. If you omit it and your org requires skills, the call might fail later. But for the 400 error, it’s definitely the address structure.

Try swapping your payload to match that JSON. If it still fails, enable debug logging on the API request and check the raw response body. Sometimes the error message is vague, but the trace shows which field failed validation.

Don’t forget to handle the 201 Created response. It returns a conversation ID you’ll need for subsequent actions like transferring or ending the call.