Tags
Assign tags to contacts
Assign a set of existing tags to a set of contacts (the cartesian product). Body: `{ contactIds: [...], tagIds: [...] }`. **Requires `Idempotency-Key`.** Returns the bulk envelope `{ data: { affected
POST /v2/tags/contacts/add
Parameters
Header parameters
Idempotency-Key
string required
Required. UUID per logical operation, reused on every retry. See
apps/rest-api/src/shared/idempotency.ts for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict.Request body
Content-Type: application/json
contactIds
array<string (uuid)> required
tagIds
array<string (uuid)> required
Example
{
"contactIds": [
"00000000-0000-0000-0000-000000000000"
],
"tagIds": [
"00000000-0000-0000-0000-000000000000"
]
}
Responses
200 — Successful response
Content-Type: application/json
data
object required
data.affected
integer required
data.ids
array<string>
data.failed
array<object>
data.failed[].id
string
data.failed[].error
object
data.failed[].error.code
string
data.failed[].error.message
string
Example
{
"data": {
"affected": 0
}
}
400 — Request body failed validation.
Content-Type: application/json
(body)
any
401 — Missing or invalid API key.
Content-Type: application/json
(body)
any
403 — Valid key, insufficient permission.
Content-Type: application/json
(body)
any
404 — Resource does not exist.
Content-Type: application/json
(body)
any
409 — Request conflicts with the current state of the resource.
Content-Type: application/json
(body)
any
429 — Rate limit exceeded.
Content-Type: application/json
(body)
any
500 — Unexpected server error.
Content-Type: application/json
(body)
any
Code samples
curl https://api.prod.getdex.com/v2/tags/contacts/add \
--request POST \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"contactIds": [
"00000000-0000-0000-0000-000000000000"
],
"tagIds": [
"00000000-0000-0000-0000-000000000000"
]
}'
fetch('https://api.prod.getdex.com/v2/tags/contacts/add', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
contactIds: ['00000000-0000-0000-0000-000000000000'],
tagIds: ['00000000-0000-0000-0000-000000000000']
})
})
requests.post(
"https://api.prod.getdex.com/v2/tags/contacts/add",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"contactIds": [
"00000000-0000-0000-0000-000000000000"
],
"tagIds": [
"00000000-0000-0000-0000-000000000000"
]
}
)
Bulk-delete tags
Delete multiple tags in one request: `{ tagIds: [...] }`, or `{ deleteAll: true }` to wipe every tag the user owns. **Requires `Idempotency-Key`** (the `deleteAll` arm is never safe to blindly re-exec
List custom fields
List all of the authenticated user's custom field definitions (name, field_type, categories, ranking), ordered by ranking then name. Returns `{ data: { custom_fields: [...] } }` — no pagination (users