# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Live Direct Marketing Online Custom Fields API
  version: 1.0.0
extends: openapi/live-direct-marketing-online-custom-fields-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/api/custom-fields'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom field definitions for an entity
      effect: read
      questions:
      - Which custom fields are defined for my contacts or leads?
      - What extra fields exist on a given record type?
      instructions:
      - text: List custom field definitions for {entity}.
        slots:
          entity: query.entity
      - text: Show the custom fields configured on {entity} records.
        slots:
          entity: query.entity
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/custom-fields'].post
  update:
    x-apievangelist-phrasing:
      intent: Define a new custom field
      effect: write
      questions:
      - How do I add a new custom field to a record type?
      - Can a new custom field be required, filterable and shown in the table?
      instructions:
      - text: Create a {type} custom field {name} with key {fieldKey} on {entity}.
        slots:
          type: requestBody.type
          name: requestBody.name
          fieldKey: requestBody.fieldKey
          entity: requestBody.entity
      - text: Add field {name} (key {fieldKey}, type {type}) to {entity} with required set to {isRequired}.
        slots:
          name: requestBody.name
          fieldKey: requestBody.fieldKey
          type: requestBody.type
          entity: requestBody.entity
          isRequired: requestBody.isRequired
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/custom-fields/inventory'].get
  update:
    x-apievangelist-phrasing:
      intent: Report custom field storage divergence
      effect: read
      questions:
      - Are my custom field values out of sync between JSON and table storage?
      - Is there a report of custom field storage mismatches?
      instructions:
      - text: Run the custom field storage inventory report.
      - text: Show where custom field JSONB and table storage diverge.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/custom-fields/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom field definition
      effect: destructive
      questions:
      - How do I remove a custom field I no longer need?
      - Can I delete a custom field definition?
      instructions:
      - text: Delete custom field {id}.
        slots:
          id: path.id
      - text: Remove the custom field definition {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/custom-fields/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a custom field definition
      effect: write
      questions:
      - How do I rename or relabel an existing custom field?
      - Can I make an existing custom field sortable or hide it from the table?
      instructions:
      - text: Rename custom field {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Set custom field {id} label to {label} and group {group}.
        slots:
          id: path.id
          label: requestBody.label
          group: requestBody.group
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/custom-fields/reorder'].post
  update:
    x-apievangelist-phrasing:
      intent: Reorder custom field definitions
      effect: write
      questions:
      - How do I change the order custom fields appear in?
      - Can I rearrange custom field definitions?
      instructions:
      - text: Reorder my custom field definitions.
      - text: Change the display order of custom fields.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/custom-fields/values/{entity}/{entityId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get custom field values for a record
      effect: read
      questions:
      - What custom field values are stored on a particular contact or lead?
      - Can I read every custom field value of one record?
      instructions:
      - text: Get custom field values for {entity} {entityId}.
        slots:
          entity: path.entity
          entityId: path.entityId
      - text: Show all custom values on {entity} record {entityId}.
        slots:
          entity: path.entity
          entityId: path.entityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/custom-fields/values/{entity}/{entityId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Set one custom field value on a record
      effect: write
      questions:
      - How do I fill in a custom field on a specific record?
      - Can I record where a custom field value came from when setting it?
      instructions:
      - text: Set field {fieldId} to {value} on {entity} {entityId}.
        slots:
          fieldId: requestBody.fieldId
          value: requestBody.value
          entity: path.entity
          entityId: path.entityId
      - text: Write {value} into custom field {fieldId} of {entity} {entityId} with source {source}.
        slots:
          value: requestBody.value
          fieldId: requestBody.fieldId
          entity: path.entity
          entityId: path.entityId
          source: requestBody.source
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/custom-fields/params/{entity}/{entityId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a record's params as flat key-values (legacy)
      effect: read
      questions:
      - Can I get a record's custom params as a simple key-value object the old way?
      - Is there a legacy flat format for reading custom params?
      instructions:
      - text: Get legacy flat params for {entity} {entityId}.
        slots:
          entity: path.entity
          entityId: path.entityId
      - text: Read {entity} {entityId}'s params as key-value pairs.
        slots:
          entity: path.entity
          entityId: path.entityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/custom-fields/params/{entity}/{entityId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk set a record's params (legacy)
      effect: write
      questions:
      - Can I set several custom params on a record at once with the legacy key-value call?
      - How do I overwrite a record's params in bulk the old way?
      instructions:
      - text: Bulk set legacy params on {entity} {entityId}.
        slots:
          entity: path.entity
          entityId: path.entityId
      - text: Write key-value params in bulk to {entity} record {entityId}.
        slots:
          entity: path.entity
          entityId: path.entityId
      method: generated
      generated: '2026-10-01'