Text Placeholders

Text placeholders are template variables that get replaced with contact field values at message send time. The API returns both built-in defaults and custom placeholders generated from text-type custom fields.

All endpoints require authentication via the X-API-Key header. See Authentication.

List text placeholders

GET /placeholders

Example request

curl "https://<host>/api/placeholders" \
  -H "X-API-Key: your-api-key"

Response

{
  "success": true,
  "data": [
    {
      "label": "First Name",
      "value": "{{FIRST_NAME}}",
      "field": "firstName",
      "type": "default"
    },
    {
      "label": "Last Name",
      "value": "{{LAST_NAME}}",
      "field": "lastName",
      "type": "default"
    },
    {
      "label": "Account Manager",
      "value": "{{ACCOUNT_MANAGER}}",
      "field": "fields.675a...",
      "type": "custom"
    }
  ]
}

Placeholder fields

Field	Type	Description
`label`	string	Human-readable name.
`value`	string	Template syntax to embed in message body (e.g. `{{FIRST_NAME}}`).
`field`	string	Contact field path used for substitution at send time.
`type`	string	`default` (built-in) or `custom` (from custom fields).

Default placeholders are always {{FIRST_NAME}} and {{LAST_NAME}}. Custom placeholders are generated from text-type custom fields — the label is uppercased and spaces are replaced with underscores.

Response envelope

All endpoints use the standard envelope:

{
  "error": false,
  "success": true,
  "message": "...",
  "code": 200,
  "data": "..."
}

Error responses:

{
  "error": true,
  "success": false,
  "message": "...",
  "code": 400,
  "data": null
}

data is null for a general failure, such as a database error or an upstream timeout. When the request is rejected because of a specific field, data carries the field(s) at fault instead:

{
  "error": true,
  "success": false,
  "message": "phone: Phone parse failed: The string supplied did not seem to be a phone number (input: <masked>)",
  "code": 400,
  "data": {
    "issues": [
      {
        "path": "phone",
        "message": "Phone parse failed: The string supplied did not seem to be a phone number (input: <masked>)"
      }
    ]
  }
}

Each issue carries a path (the dotted path into the request body) and a message. A label is added when the path is not self-describing, which today means custom fields only, for example "path": "fields.68b0a1f39c2e4d0012ab77e5", "label": "Class Year". issues is an array, but treat it as holding at most one entry: validation stops at the first failure.