This looks like a scope or identity validation mismatch rather than a pure syntax error. When you specify "type": "agent" in the from object, the API expects a valid Genesys Cloud user ID, not a phone number string. If you are trying to initiate a call from a specific agent’s direct line or mobile number, you must use "type": "phone" and ensure that number is properly linked to the user profile in the People directory.
Check your user mapping. If the agent was provisioned via SCIM, verify that the mobile or work phone attributes are correctly mapped and activated. A common pitfall is that SCIM creates the user but leaves the phone numbers in a “pending” state until the user accepts the invite or the phone is explicitly assigned in the GC UI.
Here is the corrected payload structure if you are using the user’s direct phone number:
Ensure your OAuth token includes the call:start and call:view scopes. You can validate the user’s phone status via GET /api/v2/users/{userId} and check the phoneNumbers array for active status. See the docs here: help.genesys.com/conversations-calls-api.
It depends, but generally… 400 Bad Request on POST /api/v2/conversations/calls when using "type": "agent" with a phone number string is a validation failure, not a scope issue. The API schema for the from object is strict: if type is agent, the address must be a UUID of a user resource. If type is phone, the address must be an E.164 formatted number. Mixing them triggers immediate rejection.
The suggestion above correctly identifies the mismatch. However, simply switching to "type": "phone" often leads to a 403 Forbidden if the OAuth token lacks conversation:call:create or if the phone number isn’t assigned to a user with conversation:call:control permissions.
Here is the correct payload structure for initiating a call from a specific agent’s direct line:
Ensure the user associated with the phone number has routing:skill assigned if you are routing to a queue. The routingData object is mandatory for queue-based outbound calls. Without it, the API cannot determine destination context, resulting in a 400. Also, verify the phone number is active and provisioned in the org’s telephony configuration.
Validate E.164 format for phone type addresses.
Confirm conversation:call:create scope on the OAuth token.
Check user permission conversation:call:control for the agent.
Ensure routingData.queueId is valid for outbound routing.
Verify the phone number is linked to the user in People API.
The address format dictates the required type value. Mixing an E.164 string with "type": "agent" fails schema validation. Use "type": "phone" for direct dialing.
Set type to phone.
Ensure the OAuth scopeconversation:call:write is active.
This is caused by a schema mismatch in the from object definition. The API strictly validates the type field against the address format. If type is set to agent, the address must be a valid User UUID. Providing an E.164 string with type: "agent" triggers an immediate 400 Bad Request.
To resolve this, you must align the type with the address format. For direct outbound calls using a phone number, use type: "phone".
From an instrumentation perspective, these validation errors generate high-frequency 4xx spikes in New Relic APM. Ensure your custom events capture the type field to correlate schema failures with specific integration patterns.
Warning: Using type: "agent" with a UUID requires the user to have an active extension or mobile number mapped. If the user profile lacks a valid communication channel, the call will fail at the provisioning layer despite passing schema validation.