How should I properly to initiate a cxone outbound call via the personal connection api?
i am attempting to automate outbound campaigns from our terraform-managed infrastructure. i need to trigger a call to a specific contact using the call endpoint.
endpoint: https://api.nice-incontact.com/ccapi/v2/outbound/personal-connection/call
payload:
{
"contact": {
"externalId": "ext-12345",
"phone": "+15550199"
},
"campaignId": "camp-abc-123",
"scriptId": "script-xyz-999"
}
response:
400 Bad Request - invalid campaign id for personal connection.
the campaign and script exist and are active. my oauth token has outbound:call:write scope.
is there a specific configuration requirement for the campaign to allow api-driven personal connection calls? or is the payload structure incorrect? i have reviewed the swagger docs but they are sparse on error details for this specific endpoint. any insight on the required json schema would be appreciated.
I’d suggest checking out at the contact object structure because pho is not a valid key; you must use phoneNumbers with a nested phoneType and number. The 400 error usually indicates a schema validation failure on the externalId or missing required fields in the payload.
It depends, but generally…
Cause:
Schema validation fails because pho is invalid and phoneNumbers requires explicit type mapping.
Solution:
Use the NICE CXone REST client with this payload structure:
{
"contact": {
"externalId": "ext-12345",
"phoneNumbers": [
{
"phoneType": "mobile",
"number": "+15550199999"
}
]
}
}
You might want to check at the phoneNumbers array structure because the schema requires explicit nesting. The previous answer is correct, but ensure phoneType matches your contact record definition to avoid silent failures.
{
"contact": {
"externalId": "ext-12345",
"phoneNumbers": [
{
"phoneType": "mobile",
"number": "+15550199999"
}
]
}
}
TL;DR: Validate the JSON schema against the NICE CXone API documentation before sending. The phoneNumbers array structure is correct, but ensure your OAuth token has outbound:personal-connection:write scope.
Have you tried validating your JSON payload against the NICE CXone API documentation before sending? The 400 error typically indicates a schema validation failure. The suggestions above regarding the phoneNumbers array structure are correct. You must use the exact key phoneNumbers with a nested object containing phoneType and number. However, there are additional considerations when integrating this into a Java orchestration layer using MuleSoft or similar ESB patterns.
First, ensure your OAuth token includes the necessary scope: outbound:personal-connection:write. Without this, the API will reject the request with a 401 or 403 error, which can sometimes be misinterpreted if error handling is not robust. Second, verify that the externalId matches the format expected by your NICE CXone instance. If you are using a custom external ID format, ensure it does not contain special characters that might require URL encoding in the API request.
Here is a more complete example of the request using cURL, including the necessary headers:
curl -X POST https://api.nice-incontact.com/ccapi/v2/outbound/personal-connection/call \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"contact": {
"externalId": "ext-12345",
"phoneNumbers": [
{
"phoneType": "mobile",
"number": "+15550199999"
}
]
}
}'
Additionally, consider implementing retry logic in your orchestration layer to handle transient failures. This ensures that your outbound campaigns remain resilient to temporary API issues. If the issue persists, check the NICE CXone logs for more detailed error messages.