List CRM fields - Autotouch AI

This page documents the canonical HTTP contract for this endpoint.

This read is organization-specific: custom definitions are loaded for the authenticated organization. Standard fields are code-defined. Use the returned id and definition_id values rather than manufacturing custom-field identifiers.

Developer-key access is decided by the API authorization resolver: entity_type=lead requires leads:read, company requires companies:read, and deal requires deals:read. Omitting entity_type returns all three catalogs and requires all three read scopes.

The response example shows one representative standard field; actual responses may contain many standard and organization-defined fields. Each field carries flags, field_semantics/fieldSemantics, and value_schema/valueSchema where defined. The canonical shared definitions are available from field semantics and value schema. Usage filtering applies the returned capabilities; for example, bulk_update includes only fields whose bulk_update.supported is true.

Query parameters

entity_type · optional
string
lead, company, or deal. Omitted returns fields for all three.
usage · optional
string
Optional usage filter: profile, table, bulk_update, sync_to_leads, filter, sort, search, task_context, sequence_variables, or ai_context.
include_standard · optional
boolean
Include code-defined standard fields; defaults to true. Organization-defined custom fields remain organization-scoped.

Name	Type	Description
entity_type	string	lead, company, or deal. Omitted returns fields for all three.
usage	string	Optional usage filter: profile, table, bulk_update, sync_to_leads, filter, sort, search, task_context, sequence_variables, or ai_context.
include_standard	boolean	Include code-defined standard fields; defaults to true. Organization-defined custom fields remain organization-scoped.

Errors

Status	Meaning
401	Authentication required or authenticated user has no organization context.
403	Developer API key lacks the scope required for the selected entity_type.
422	Invalid entity_type or usage value.

Example

bash

curl -G 'https://app.autotouch.ai/api/crm/fields' \
  -H "Authorization: Bearer $AUTOTOUCH_API_KEY" \
  --data-urlencode 'entity_type=lead' \
  --data-urlencode 'usage=sequence_variables'

Response example

json

{
  "fields": [
    {
      "id": "standard:lead:first_name",
      "definition_id": null,
      "source": "standard",
      "entity_type": "lead",
      "key": "first_name",
      "label": "First name",
      "data_type": "text",
      "path": "first_name",
      "category": "crm_model",
      "description": null,
      "aliases": [],
      "enforce_usage_flags": false,
      "options": [],
      "flags": {
        "is_filterable": true,
        "is_sortable": true,
        "is_searchable": true,
        "include_in_task_context": true,
        "include_in_sequence_variables": true,
        "include_in_ai_context": true
      },
      "sync_to_leads_write_policy": "manual",
      "syncToLeadsWritePolicy": "manual",
      "field_semantics": {
        "version": 1,
        "fieldClass": "normalized",
        "sourceKind": "crm_standard",
        "ownerScope": "lead",
        "canonicalField": "first_name",
        "importBehavior": "normalize_then_write",
        "mutability": {"importWrite": true, "userEdit": true, "apiWrite": true, "delete": true},
        "roles": {"mappingSource": true, "mappingTarget": true, "filterable": true, "sortable": true, "searchable": true, "sequenceVariable": true, "aiContext": true},
        "protectionReason": null
      },
      "fieldSemantics": {"version": 1, "fieldClass": "normalized", "sourceKind": "crm_standard", "ownerScope": "lead", "canonicalField": "first_name", "importBehavior": "normalize_then_write", "mutability": {"importWrite": true, "userEdit": true, "apiWrite": true, "delete": true}, "roles": {"mappingSource": true, "mappingTarget": true, "filterable": true, "sortable": true, "searchable": true, "sequenceVariable": true, "aiContext": true}, "protectionReason": null},
      "value_schema": null,
      "valueSchema": null,
      "workflow_trigger": true,
      "workflow_value_provider": null,
      "workflow_condition_operators": [],
      "position": 0,
      "bulk_update": {"supported": true, "operations": ["set", "clear"], "writer_id": "lead_field_update", "required_permission": null, "required_scopes": ["leads:write"]},
      "bulkUpdate": {"supported": true, "operations": ["set", "clear"], "writer_id": "lead_field_update", "required_permission": null, "required_scopes": ["leads:write"]}
    }
  ]
}