Users
Add a user
Section titled “Add a user”POST /v1/collections/{collection_id}/users| Field | Type | Required | Description |
|---|---|---|---|
email | string | ✅ | User’s email address |
first_name | string | First name | |
last_name | string | Last name | |
profile_image_url | string | Profile image URL | |
custom_fields | object | Custom field values | |
send_invite | boolean | Send invitation email when creating a new user (default: false). Ignored if the email already exists in the collection. |
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"}Duplicate handling (200 OK)
Section titled “Duplicate handling (200 OK)”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:
- No duplicate user is created.
- Existing profile details are preserved:
first_name,last_name,profile_image_url, andcustom_fieldsattached to the user/recording are not overwritten. UsePATCH /v1/collections/{collection_id}/users/{user_id}to explicitly update a user’s details. - No duplicate invitation email is sent: Passing
send_invite: truefor an existing user will not resend an invitation (invite_sent: false). UsePOST /v1/collections/{collection_id}/invites/{invite_id}/resendto explicitly resend an invitation.
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"}List users
Section titled “List users”GET /v1/collections/{collection_id}/users| Parameter | Type | Description |
|---|---|---|
limit | integer | Max results (1-100, default 50) |
cursor | string | Pagination cursor |
status | string | Filter: pending, invited, recorded |
email | string | Filter by email |
Get a user
Section titled “Get a user”GET /v1/collections/{collection_id}/users/{user_id}Update a user
Section titled “Update a user”PATCH /v1/collections/{collection_id}/users/{user_id}| Field | Type | Description |
|---|---|---|
first_name | string | |
last_name | string | |
profile_image_url | string | |
custom_fields | object |
Remove a user
Section titled “Remove a user”DELETE /v1/collections/{collection_id}/users/{user_id}