Outbound API POST contact list 400 INVALID_VALUE on name

NICE CXone API & Integrations
1

Trying to create a new contact list via /api/v2/outbound/contactlistitems. Getting a 400 with INVALID_VALUE on the name field. Tried alphanumeric and simple strings. Same error. Here’s the payload.

{
 "name": "TestList1",
 "type": "EMAIL"
}

Any idea what’s invalid?

2

The endpoint you are hitting is for contact items, not the list itself. That’s why the name field is throwing an INVALID_VALUE error. The item resource expects contact details, not list metadata. You need to POST to /api/v2/outbound/contactlists to create the container.

Here is the correct payload structure for the list creation endpoint:

{
 "name": "TestList1",
 "type": "EMAIL",
 "description": "Optional description"
}

Once that succeeds, you get a contactListId. You then use that ID in a subsequent POST to /api/v2/outbound/contactlists/{contactListId}/items to actually add the contacts. The SDK handles this distinction pretty well if you look at the OutboundApi client in the PlatformClientV2 library. The postOutboundContactlist method is separate from postOutboundContactlistitem. Just make sure your token has outbound:contactlist:write scope, otherwise you’ll hit a 403 after fixing the path. Check the API docs for the specific field requirements on the list object.

3

is spot on. You’re hitting the items endpoint instead of the list creator. The /api/v2/outbound/contactlistitems route expects a specific structure with contactId or raw contact fields, not list metadata like name.

Switch to POST /api/v2/outbound/contactlists for the actual creation. Also, type: "EMAIL" isn’t a standard enum value for the list itself. The API usually defaults to OUTBOUND for dialer lists. If you strictly need an email-only list, you might need to check if your org has the specific engagement settings enabled, but generally, you just send the name.

Here’s the corrected curl to get you moving:

curl -X POST "https://api.mypurecloud.com/api/v2/outbound/contactlists" \
 -H "Authorization: Bearer <your_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "name": "TestList1"
 }'

Once that returns a 201, grab the id from the response. Then you can POST the actual email addresses to /api/v2/outbound/contactlists/{contactListId}/contactlistitems. Don’t forget to check the status field on the list object after creation, sometimes it takes a second to initialize.

4

Switching to /api/v2/outbound/contactlists fixed it. The items endpoint was definitely the culprit, and dropping the type: "EMAIL" constraint let the API handle the defaults without complaining.

Payload is clean now. Just need to figure out the retry logic for the subsequent item uploads.