Define Lead Custom Field

Define a tenant custom lead field (key, label, kind, options, validators). Lets a customer capture something the platform does not ship, e.g. their own product name.

POST/api/v1/leads/dispatch

Request

curl -X POST "<BASE_URL>/api/v1/leads/dispatch" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-CQRS-Action: DEFINE_LEAD_CUSTOM_FIELD" \
  -H "Content-Type: application/json" \
  -d '{
    "field_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "field_kind": "TEXT_INPUT",
    "key": "string",
    "label": "string",
    "tenant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }'

Authorization

Minimum role: ManagerThe caller must hold this role or a higher one.
Action: DEFINE_LEAD_CUSTOM_FIELD

Headers

AuthorizationstringRequired
Access token of the signed-in user, as a Bearer token. It identifies the user, their role and the workspace.
X-CQRS-ActionstringRequired
Names the command to run. Must be DEFINE_LEAD_CUSTOM_FIELD for this endpoint.
Content-TypestringRequired
Always application/json.
X-Idempotency-KeystringOptional
A key you choose that is unique to this attempt. A command repeated with the same key is not applied a second time.
X-Correlation-IdstringOptional
Your own identifier for the request. Returned in the x-correlation-id response header; generated when you leave it out.

Request body

field_iduuidRequired
No description yet.
field_kindenumRequired
No description yet.
Allowed values
- TEXT_INPUT
- TEXTAREA
- EMAIL
- PHONE
- NUMBER
- CURRENCY
- PERCENTAGE
- DROPDOWN
- COMBOBOX
- MULTI_SELECT
- RADIO_GROUP
- CHECKBOX_GROUP
- TOGGLE_SWITCH
- DATE
- TIME
- DATE_TIME
- FILE_UPLOAD
- IMAGE_UPLOAD
- SIGNATURE
- READ_ONLY
- NESTED_FORM
- REPEATABLE_GROUP
- EDITABLE_TABLE
- ADDRESS_AUTOCOMPLETE
- MASKED_INPUT
- AI_PROMPT
- AI_EXTRACTED_FIELD
- DEAL_HEALTH_WIDGET
- CAUSAL_INTENT_WIDGET
- COGNITIVE_CAPACITY_BAR
- CRYO_STASIS_TRACKER
- COMMENT
- CONSENT_CHECKBOX
- SUMMARY_VIEW
- GRAPH_MAPPER
- REASONING_VIEWER
- DAG_CANVAS
- NODE_INSPECTOR_PANEL
keystringRequired
Storage key. Immutable once leads have answered it — renaming would orphan every stored value.
minimum length 1
maximum length 64
labelstringRequired
No description yet.
minimum length 1
maximum length 120
tenant_iduuidRequired
No description yet.
existing_field_countintegerOptional
Fields the tenant already has, so the ceiling can be enforced without the executor reaching for the database.
Default
0
at least 0
help_textstring or nullOptional
No description yet.
optionsarray of objectOptional
No description yet.
2 child fields
- labelstringRequired
  No description yet.
- valuestringRequired
  No description yet.
placeholderstring or nullOptional
No description yet.
requiredbooleanOptional
No description yet.
Default
false
validatorsarray of objectOptional
No description yet.
7 child fields
- kindenumRequired
  No description yet.
  Allowed values
  url
  pattern
  min_length
  matches_field
  range
  greater_than_field
  greater_or_equal_field
  greater_than
  url
  Value must be a syntactically valid http(s) URL.
  pattern
  Value must match pattern (a JS-compatible regular expression).
  min_length
  String length must be ≥ value.
  matches_field
  Value must equal the current value of another field in the same form (named by field). The only CROSS-FIELD rule: every other kind judges a value in isolation, so "confirm password" could not be expressed and lived as hand-written logic in the register page instead — which is why its error surfaced as a page-level banner rather than at the input.
  range
  Numeric value must fall within min..=max inclusive.
  greater_than_field
  Numeric value must be greater than the current value of another field (named by field).
  greater_or_equal_field
  Numeric value must be greater than OR EQUAL TO another field's value.
  greater_than
  Numeric value must be strictly greater than the literal value.
- messageKeystringRequired
  i18n key for the error shown when this rule fails.
- fieldstring or nullOptional
  Peer field name for MatchesField / GreaterThanField. Unused by the value-in-isolation kinds.
- maxinteger or nullOptional
  No description yet.
- mininteger or nullOptional
  Inclusive bounds for Range. Unused by every other kind.
- patternstring or nullOptional
  No description yet.
- valueinteger or nullOptional
  No description yet.

Response

Status 202. The command was applied. The body reports the outcome and, where the command changes a record, that record's new state.

successbooleanRequired
true when the command was applied.
error_messagestringRequired
Empty when the command was applied.
projected_stateobjectOptional
The record as it stands after the command.
event_payloadobjectOptional
The event the command recorded.
insightsarray of objectOptional
Advisory notes about the result. Each has a code, a message and an impact number.

Errors

Every error carries an HTTP status. Where it also carries a code, branch on the code, not on the message.

400X-CQRS-Action is missing or names a command this route does not accept. Send DEFINE_LEAD_CUSTOM_FIELD.
400DOMAIN_ROUTINGThe body is not a valid command. Check the required fields and their types.
401The access token is missing, expired or not valid.
401L1_AUTHThe caller's role is below manager or the caller has no access to this record.
403L1_POLICYA business rule refused the command. The message names the rule.
409L1_IDEMPOTENCYA command with this idempotency key was already applied.
409CONFLICTThe command would duplicate a record that must be unique.
500L3_COMMITThe command was valid but could not be saved.