DELETE /api/v1/custom-fields/{customFieldId}
Deletes a custom field.
Deleting a field erases its value on every contact, in every list, at once. There is no undo.
Authorization
| Role in the organization | This endpoint |
|---|---|
OWNER | Allowed |
ADMIN | Allowed |
MEMBER | Refused — 403 |
Path parameters
| Parameter | Type | Description |
|---|---|---|
customFieldId | string | Required. The field to delete |
Example
bash
curl -X DELETE -H "x-api-key: $AGENTMAIL_API_KEY" \
"https://www.agentsmail.io/api/v1/custom-fields/$CUSTOM_FIELD_ID"Response
200 OK— the id of what was removed.401 Unauthorized— missing or invalid key, or its owner left the organization.403 Forbidden— the key's owner is amemberof the organization, not anadmin.404 Not Found— no such field, or it belongs to another organization. The API never confirms that an id exists to a caller who has no right to it.429 Too Many Requests— over 120 requests in a minute for this key.
Response fields
| Field | Type | Description |
|---|---|---|
success | boolean | Indicates if the operation was successful |
data.id | string | Identifier of what was removed |
Example response
json
{
"success": true,
"data": {
"id": "4f1a9c2e"
}
}Agent recipe
Find the field by its key, then delete it by its id:js
const fields = (await list('/api/v1/custom-fields')).data
const field = fields.find((f) => f.key === 'utm_source')
if (field) {
await del(`/api/v1/custom-fields/${field.id}`)
}Notes
- It is final. The values are gone for every contact, and creating a field with the same key afterwards starts empty.
- Once the field is gone, sending its key in a contact's
customFieldsis refused again.