Custom Fields

Custom fields let you extend the contact schema with organisation-specific attributes — e.g. Birthday, Lead Source, or Shopify Customer ID. Each definition has a fieldKey (immutable after creation) used to store and query data on contacts.

List Custom Fields

Return all custom attribute definitions for your organisation.

GET/v2.0/contacts/custom_fields

Code Example

curl -X GET "https://api.sendiee.com/v2.0/contacts/custom_fields" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "success": true,
  "data": [
    {
      "_id": "6640fa2b3e4a1c0012abc001",
      "fieldName": "Birthday",
      "fieldKey": "birthday",
      "fieldType": "date",
      "hasDropdown": false,
      "options": [],
      "createdAt": "2026-03-01T10:00:00.000Z",
      "updatedAt": "2026-03-01T10:00:00.000Z"
    },
    {
      "_id": "6640fa2b3e4a1c0012abc002",
      "fieldName": "Lead Source",
      "fieldKey": "lead_source",
      "fieldType": "dropdown",
      "hasDropdown": true,
      "options": [
        "Facebook Ads",
        "Google Ads",
        "Organic",
        "Referral"
      ],
      "createdAt": "2026-03-05T08:00:00.000Z",
      "updatedAt": "2026-03-05T08:00:00.000Z"
    }
  ],
  "meta": {
    "total": 2
  }
}

Try It — List

Try it — API Playground

API Key

Create Custom Field

Create a new custom attribute definition. Subject to the max_custom_attributes plan limit.

POST/v2.0/contacts/custom_fields

fieldKey is immutable

If fieldKey is not provided it is auto-derived from fieldName (lowercased, spaces → underscores, special characters removed). Once created, fieldKey cannot be changed — changing it would break existing contact data stored under that key.

Body Parameters

Parameter	Type	Required	Description
fieldName	string	Required	Display name shown in the UI. e.g. "Birthday"
fieldKey	string	Optional	Key used to store / query data on contacts. Auto-derived from fieldName if omitted. Must be unique per org.
fieldType	string	Optional	One of: text, number, date, boolean, dropdownDefault: `text`
options	string[]	Optional	Required (non-empty) when fieldType is "dropdown". Array of option strings.

Code Examples

curl -X POST "https://api.sendiee.com/v2.0/contacts/custom_fields" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldName": "Birthday",
    "fieldType": "date"
  }'

Response — 201 Created

{
  "success": true,
  "message": "Custom field created successfully.",
  "data": {
    "_id": "6640fa2b3e4a1c0012abc003",
    "fieldName": "Lead Source",
    "fieldKey": "lead_source",
    "fieldType": "dropdown",
    "hasDropdown": true,
    "options": [
      "Facebook Ads",
      "Google Ads",
      "Organic",
      "Referral"
    ],
    "createdAt": "2026-04-14T09:00:00.000Z",
    "updatedAt": "2026-04-14T09:00:00.000Z"
  }
}

Try It — Create

Try it — API Playground

API Key

Field Name*

Field Key (optional)

Field Type

Options (comma-separated, dropdown only)

Update Custom Field

Update an existing custom attribute definition's display name, type, or options.

PUT/v2.0/contacts/custom_fields/:fieldId

fieldKey cannot be changed

Only fieldName, fieldType, and options can be updated. The fieldKey is immutable after creation.

Parameters

Path Parameters

Parameter	Type	Required	Description
fieldId	string	Required	MongoDB ObjectId of the custom field

Body Parameters

Parameter	Type	Required	Description
fieldName	string	Optional	New display name
fieldType	string	Optional	One of: text, number, date, boolean, dropdown
options	string[]	Optional	Required (non-empty) when fieldType is "dropdown"

Code Example

curl -X PUT "https://api.sendiee.com/v2.0/contacts/custom_fields/6640fa2b3e4a1c0012abc003" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldName": "Acquisition Channel",
    "options": ["Facebook Ads", "Google Ads", "Organic", "Referral", "WhatsApp Broadcast"]
  }'

Response — 200 OK

{
  "success": true,
  "message": "Custom field updated successfully.",
  "data": {
    "_id": "6640fa2b3e4a1c0012abc003",
    "fieldName": "Acquisition Channel",
    "fieldKey": "lead_source",
    "fieldType": "dropdown",
    "hasDropdown": true,
    "options": [
      "Facebook Ads",
      "Google Ads",
      "Organic",
      "Referral",
      "WhatsApp Broadcast"
    ],
    "createdAt": "2026-04-14T09:00:00.000Z",
    "updatedAt": "2026-04-14T11:30:00.000Z"
  }
}

Delete Custom Field

Delete a custom attribute definition from your organisation.

DELETE/v2.0/contacts/custom_fields/:fieldId

Existing data is not removed

Deleting a field definition does not automatically remove values already stored under that fieldKey on existing contacts.

Path Parameters

Parameter	Type	Required	Description
fieldId	string	Required	MongoDB ObjectId of the custom field

Code Example

curl -X DELETE "https://api.sendiee.com/v2.0/contacts/custom_fields/6640fa2b3e4a1c0012abc003" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "success": true,
  "message": "Custom field deleted successfully.",
  "data": {
    "fieldId": "6640fa2b3e4a1c0012abc003",
    "fieldKey": "lead_source"
  }
}