Skip to content
Back to Nouncify

Users

POST /v1/collections/{collection_id}/users
FieldTypeRequiredDescription
emailstring✅User’s email address
first_namestringFirst name
last_namestringLast name
profile_image_urlstringProfile image URL
custom_fieldsobjectCustom field values
send_invitebooleanSend invitation email when creating a new user (default: false). Ignored if the email already exists in the collection.
Terminal window
curl -X POST https://api.nouncify.com/v1/collections/{id}/users \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "priya@company.com",
"first_name": "Priya",
"last_name": "Patel",
"send_invite": true
}'

Response 201 Created (New User)

{
"id": "user-uuid",
"collection_id": "collection-uuid",
"email": "priya@company.com",
"first_name": "Priya",
"last_name": "Patel",
"profile_image_url": null,
"custom_fields": {},
"status": "invited",
"recording_status": "pending",
"has_recording": false,
"play_link": null,
"recording": null,
"invite_sent": true,
"already_exists": false,
"created_at": "2026-04-01T00:00:00Z",
"updated_at": "2026-04-01T00:00:00Z"
}

If a user with the same email already exists in the collection, the endpoint behaves idempotently and returns 200 OK with the existing user record:

Response 200 OK (Existing User With Recording)

{
"id": "user-uuid",
"collection_id": "collection-uuid",
"email": "priya@company.com",
"first_name": "Priya",
"last_name": "Patel",
"profile_image_url": null,
"custom_fields": {},
"status": "recorded",
"recording_status": "recorded",
"has_recording": true,
"play_link": "https://nouncify.com/collections/collection-uuid/HkJ3mN8x",
"recording": {
"recording_id": "recording-uuid",
"duration_seconds": 3,
"recorded_at": "2026-04-01T12:00:00Z",
"play_url": "https://nouncify.com/collections/collection-uuid/HkJ3mN8x.mp3"
},
"invite_sent": false,
"already_exists": true,
"created_at": "2026-03-28T09:15:00Z",
"updated_at": "2026-04-01T12:00:00Z"
}

Response 200 OK (Existing User Without Recording)

{
"id": "user-uuid",
"collection_id": "collection-uuid",
"email": "priya@company.com",
"first_name": "Priya",
"last_name": "Patel",
"profile_image_url": null,
"custom_fields": {},
"status": "invited",
"recording_status": "pending",
"has_recording": false,
"play_link": null,
"recording": null,
"invite_sent": false,
"already_exists": true,
"created_at": "2026-03-28T09:15:00Z",
"updated_at": "2026-03-28T09:15:00Z"
}
GET /v1/collections/{collection_id}/users
ParameterTypeDescription
limitintegerMax results (1-100, default 50)
cursorstringPagination cursor
statusstringFilter: pending, invited, recorded
emailstringFilter by email
GET /v1/collections/{collection_id}/users/{user_id}
PATCH /v1/collections/{collection_id}/users/{user_id}
FieldTypeDescription
first_namestring
last_namestring
profile_image_urlstring
custom_fieldsobject
DELETE /v1/collections/{collection_id}/users/{user_id}