Lightfield
Lightfield API

The Lightfield API provides read and write access to every entity in the Lightfield agent-native CRM: accounts, contacts, opportunities, meetings, notes, tasks, lists, emails, files, members, custom objects and workflow runs. It is a JSON REST API authenticated with a scoped bearer API key, versioned by a required date-based Lightfield-Version header, with Idempotency-Key support on write operations, limit/offset pagination and field-level filtering. Currently in public beta.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "info": {
    "title": "API Reference",
    "version": "0.0.0"
  },
  "openapi": "3.1.1",
  "components": {
    "schemas": {
      "BadRequestError": {
        "type": "object",
        "properties": {
          "type": {
            "const": "bad_request"
          },
          "message": {
            "type": "string",
            "default": "Bad Request"
          },
          "code": {
            "type": "string"
          },
          "param": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "message",
          "code"
        ]
      },
      "UnauthorizedError": {
        "type": "object",
        "properties": {
          "type": {
            "const": "unauthorized"
          },
          "message": {
            "type": "string",
            "default": "Unauthorized"
          }
        },
        "required": [
          "type",
          "message"
        ]
      },
      "ForbiddenError": {
        "type": "object",
        "properties": {
          "type": {
            "const": "forbidden"
          },
          "message": {
            "type": "string",
            "default": "Forbidden"
          }
        },
        "required": [
          "type",
          "message"
        ]
      },
      "NotFoundError": {
        "type": "object",
        "properties": {
          "type": {
            "const": "not_found"
          },
          "message": {
            "type": "string",
            "default": "Not Found"
          }
        },
        "required": [
          "type",
          "message"
        ]
      },
      "InternalServerError": {
        "type": "object",
        "properties": {
          "type": {
            "const": "internal_server_error"
          },
          "message": {
            "type": "string",
            "default": "Internal Server Error"
          }
        },
        "required": [
          "type",
          "message"
        ]
      },
      "ConflictError": {
        "type": "object",
        "properties": {
          "type": {
            "const": "conflict"
          },
          "message": {
            "type": "string",
            "default": "Conflict"
          }
        },
        "required": [
          "type",
          "message"
        ]
      },
      "GatewayTimeoutError": {
        "type": "object",
        "properties": {
          "type": {
            "const": "gateway_timeout"
          },
          "message": {
            "type": "string",
            "default": "Gateway Timeout"
          }
        },
        "required": [
          "type",
          "message"
        ]
      },
      "TooManyRequestsError": {
        "type": "object",
        "properties": {
          "type": {
            "const": "too_many_requests"
          },
          "message": {
            "type": "string",
            "default": "Too Many Requests"
          }
        },
        "required": [
          "type",
          "message"
        ]
      },
      "ServiceUnavailableError": {
        "type": "object",
        "properties": {
          "type": {
            "const": "service_unavailable"
          },
          "message": {
            "type": "string",
            "default": "Service Unavailable"
          }
        },
        "required": [
          "type",
          "message"
        ]
      },
      "UnprocessableContentError": {
        "type": "object",
        "properties": {
          "type": {
            "const": "unprocessable_content"
          },
          "message": {
            "type": "string",
            "default": "Unprocessable Content"
          }
        },
        "required": [
          "type",
          "message"
        ]
      },
      "UnsupportedMediaTypeError": {
        "type": "object",
        "properties": {
          "type": {
            "const": "unsupported_media_type"
          },
          "message": {
            "type": "string",
            "default": "Unsupported Media Type"
          }
        },
        "required": [
          "type",
          "message"
        ]
      },
      "Error": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/BadRequestError"
          },
          {
            "$ref": "#/components/schemas/UnauthorizedError"
          },
          {
            "$ref": "#/components/schemas/ForbiddenError"
          },
          {
            "$ref": "#/components/schemas/NotFoundError"
          },
          {
            "$ref": "#/components/schemas/InternalServerError"
          },
          {
            "$ref": "#/components/schemas/ConflictError"
          },
          {
            "$ref": "#/components/schemas/GatewayTimeoutError"
          },
          {
            "$ref": "#/components/schemas/TooManyRequestsError"
          },
          {
            "$ref": "#/components/schemas/ServiceUnavailableError"
          },
          {
            "$ref": "#/components/schemas/UnprocessableContentError"
          },
          {
            "$ref": "#/components/schemas/UnsupportedMediaTypeError"
          }
        ]
      },
      "AuthValidateResponse": {
        "type": "object",
        "properties": {
          "active": {
            "type": "boolean",
            "description": "Whether the current API key is valid. Always `true` on successful responses."
          },
          "tokenType": {
            "enum": [
              "api_key"
            ],
            "description": "Credential family, always `api_key`."
          },
          "subjectType": {
            "enum": [
              "user",
              "workspace"
            ],
            "description": "Whether the API key belongs to a `user` or `workspace`."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Granted public scopes for the current API key. Empty when the key has full access."
          }
        },
        "required": [
          "active",
          "tokenType",
          "subjectType",
          "scopes"
        ]
      },
      "AccountDefinitionsResponse": {
        "type": "object",
        "properties": {
          "objectType": {
            "type": "string",
            "description": "The object type these definitions belong to (e.g. `account`)."
          },
          "fieldDefinitions": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique identifier of the field definition."
                },
                "label": {
                  "type": "string",
                  "description": "Human-readable display name of the field."
                },
                "description": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Description of the field, or null."
                },
                "valueType": {
                  "enum": [
                    "ADDRESS",
                    "CHECKBOX",
                    "CURRENCY",
                    "DATETIME",
                    "EMAIL",
                    "FULL_NAME",
                    "MARKDOWN",
                    "MULTI_SELECT",
                    "NUMBER",
                    "SINGLE_SELECT",
                    "SOCIAL_HANDLE",
                    "TELEPHONE",
                    "TEXT",
                    "URL",
                    "HTML"
                  ],
                  "description": "Data type of the field."
                },
                "readOnly": {
                  "type": "boolean",
                  "description": "`true` for fields that are not writable via the API (e.g. AI-generated summaries). `false` or absent for writable fields."
                },
                "typeConfiguration": {
                  "type": "object",
                  "properties": {
                    "options": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Unique identifier of the select option."
                          },
                          "label": {
                            "type": "string",
                            "description": "Human-readable display name of the option."
                          },
                          "description": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Description of the option, or null."
                          }
                        },
                        "required": [
                          "id",
                          "label"
                        ],
                        "additionalProperties": false
                      },
                      "description": "Available options for select fields."
                    },
                    "currency": {
                      "type": "string",
                      "description": "ISO 4217 3-letter currency code."
                    },
                    "unique": {
                      "type": "boolean",
                      "description": "Whether values for this field must be unique."
                    },
                    "multipleValues": {
                      "type": "boolean",
                      "description": "Whether this field accepts multiple values."
                    },
                    "handleService": {
                      "enum": [
                        "TWITTER",
                        "LINKEDIN",
                        "FACEBOOK",
                        "INSTAGRAM"
                      ],
                      "description": "Social platform associated with this handle field."
                    }
                  },
                  "additionalProperties": false,
                  "description": "Type-specific configuration (e.g. select options, currency code)."
                }
              },
              "required": [
                "label",
                "description",
                "valueType",
                "typeConfiguration"
              ]
            },
            "description": "Map of field keys to their definitions, including both system and custom fields."
          },
          "relationshipDefinitions": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique identifier of the relationship definition."
                },
                "label": {
                  "type": "string",
                  "description": "Human-readable display name of the relationship."
                },
                "description": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Description of the relationship, or null."
                },
                "cardinality": {
                  "enum": [
                    "HAS_ONE",
                    "HAS_MANY"
                  ],
                  "description": "Whether this is a `has_one` or `has_many` relationship."
                },
                "objectType": {
                  "type": "string",
                  "description": "The type of the related object (e.g. `account`, `contact`)."
                }
              },
              "required": [
                "label",
                "description",
                "cardinality",
                "objectType"
              ]
            },
            "description": "Map of relationship keys to their definitions."
          }
        },
        "required": [
          "objectType",
          "fieldDefinitions",
          "relationshipDefinitions"
        ]
      },
      "AccountListResponse": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "description": "The object type, always `\"list\"`."
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique identifier for the entity."
                },
                "createdAt": {
                  "type": "string",
                  "description": "ISO 8601 timestamp of when the entity was created."
                },
                "updatedAt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "ISO 8601 timestamp of when the entity was last updated, or null."
                },
                "httpLink": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "URL to view the entity in the Lightfield web app, or null."
                },
                "externalId": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "External identifier for the entity, or null if unset."
                },
                "fields": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {
                    "type": "object",
                    "properties": {
                      "valueType": {
                        "enum": [
                          "ADDRESS",
                          "CHECKBOX",
                          "CURRENCY",
                          "DATETIME",
                          "EMAIL",
                          "FULL_NAME",
                          "MARKDOWN",
                          "MULTI_SELECT",
                          "NUMBER",
                          "SINGLE_SELECT",
                          "SOCIAL_HANDLE",
                          "TELEPHONE",
                          "TEXT",
                          "URL",
                          "HTML"
                        ],
                        "description": "The data type of the field."
                      },
                      "value": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "integer",
                            "minimum": -9007199254740991,
                            "maximum": 9007199254740991
                          },
                          {
                            "type": "number"
                          },
                          {
                            "type": "boolean"
                          },
                          {
                            "type": "null"
                          },
                          {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          {
                            "$ref": "#/components/schemas/Address"
                          },
                          {
                            "$ref": "#/components/schemas/FullName"
                          }
                        ],
                        "description": "The field value, or null if unset."
                      }
                    },
                    "required": [
                      "valueType",
                      "value"
                    ]
                  },
                  "description": "Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug."
                },
                "relationships": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {
                    "type": "object",
                    "properties": {
                      "cardinality": {
                        "type": "string",
                        "description": "Whether the relationship is `has_one` or `has_many`."
                      },
                      "objectType": {
                        "type": "string",
                        "description": "The type of the related object (e.g. `account`, `contact`)."
                      },
                      "values": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "IDs of the related entities."
                      }
                    },
                    "required": [
                      "cardinality",
                      "objectType",
                      "values"
                    ]
                  },
                  "description": "Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`)."
                }
              },
              "required": [
                "id",
                "createdAt",
                "updatedAt",
                "httpLink",
                "fields",
                "relationships"
              ],
              "additionalProperties": false
            },
            "description": "Array of entity objects for the current page."
          },
          "totalCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Total number of entities matching the query."
          }
        },
        "required": [
          "object",
          "data",
          "totalCount"
        ]
      },
      "AccountCreateResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the entity."
          },
          "createdAt": {
            "type": "string",
            "description": "ISO 8601 timestamp of when the entity was created."
          },
          "updatedAt": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp of when the entity was last updated, or null."
          },
          "httpLink": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "URL to view the entity in the Lightfield web app, or null."
          },
          "externalId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "External identifier for the entity, or null if unset."
          },
          "fields": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "valueType": {
                  "enum": [
                    "ADDRESS",
                    "CHECKBOX",
                    "CURRENCY",
                    "DATETIME",
                    "EMAIL",
                    "FULL_NAME",
                    "MARKDOWN",
                    "MULTI_SELECT",
                    "NUMBER",
                    "SINGLE_SELECT",
                    "SOCIAL_HANDLE",
                    "TELEPHONE",
                    "TEXT",
                    "URL",
                    "HTML"
                  ],
                  "description": "The data type of the field."
                },
                "value": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "null"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    {
                      "$ref": "#/components/schemas/Address"
                    },
                    {
                      "$ref": "#/components/schemas/FullName"
                    }
                  ],
                  "description": "The field value, or null if unset."
                }
              },
              "required": [
                "valueType",
                "value"
              ]
            },
            "description": "Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug."
          },
          "relationships": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "cardinality": {
                  "type": "string",
                  "description": "Whether the relationship is `has_one` or `has_many`."
                },
                "objectType": {
                  "type": "string",
                  "description": "The type of the related object (e.g. `account`, `contact`)."
                },
                "values": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "IDs of the related entities."
                }
              },
              "required": [
                "cardinality",
                "objectType",
                "values"
              ]
            },
            "description": "Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`)."
          }
        },
        "required": [
          "id",
          "createdAt",
          "updatedAt",
          "httpLink",
          "fields",
          "relationships"
        ],
        "additionalProperties": false
      },
      "AccountRetrieveResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the entity."
          },
          "createdAt": {
            "type": "string",
            "description": "ISO 8601 timestamp of when the entity was created."
          },
          "updatedAt": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp of when the entity was last updated, or null."
          },
          "httpLink": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "URL to view the entity in the Lightfield web app, or null."
          },
          "externalId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "External identifier for the entity, or null if unset."
          },
          "fields": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "valueType": {
                  "enum": [
                    "ADDRESS",
                    "CHECKBOX",
                    "CURRENCY",
                    "DATETIME",
                    "EMAIL",
                    "FULL_NAME",
                    "MARKDOWN",
                    "MULTI_SELECT",
                    "NUMBER",
                    "SINGLE_SELECT",
                    "SOCIAL_HANDLE",
                    "TELEPHONE",
                    "TEXT",
                    "URL",
                    "HTML"
                  ],
                  "description": "The data type of the field."
                },
                "value": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "null"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    {
                      "$ref": "#/components/schemas/Address"
                    },
                    {
                      "$ref": "#/components/schemas/FullName"
                    }
                  ],
                  "description": "The field value, or null if unset."
                }
              },
              "required": [
                "valueType",
                "value"
              ]
            },
            "description": "Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug."
          },
          "relationships": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "cardinality": {
                  "type": "string",
                  "description": "Whether the relationship is `has_one` or `has_many`."
                },
                "objectType": {
                  "type": "string",
                  "description": "The type of the related object (e.g. `account`, `contact`)."
                },
                "values": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "IDs of the related entities."
                }
              },
              "required": [
                "cardinality",
                "objectType",
                "values"
              ]
            },
            "description": "Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`)."
          }
        },
        "required": [
          "id",
          "createdAt",
          "updatedAt",
          "httpLink",
          "fields",
          "relationships"
        ],
        "additionalProperties": false
      },
      "AccountUpdateResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the entity."
          },
          "createdAt": {
            "type": "string",
            "description": "ISO 8601 timestamp of when the entity was created."
          },
          "updatedAt": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp of when the entity was last updated, or null."
          },
          "httpLink": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "URL to view the entity in the Lightfield web app, or null."
          },
          "externalId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "External identifier for the entity, or null if unset."
          },
          "fields": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "valueType": {
                  "enum": [
                    "ADDRESS",
                    "CHECKBOX",
                    "CURRENCY",
                    "DATETIME",
                    "EMAIL",
                    "FULL_NAME",
                    "MARKDOWN",
                    "MULTI_SELECT",
                    "NUMBER",
                    "SINGLE_SELECT",
                    "SOCIAL_HANDLE",
                    "TELEPHONE",
                    "TEXT",
                    "URL",
                    "HTML"
                  ],
                  "description": "The data type of the field."
                },
                "value": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "null"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    {
                      "$ref": "#/components/schemas/Address"
                    },
                    {
                      "$ref": "#/components/schemas/FullName"
                    }
                  ],
                  "description": "The field value, or null if unset."
                }
              },
              "required": [
                "valueType",
                "value"
              ]
            },
            "description": "Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug."
          },
          "relationships": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
            

# --- truncated at 32 KB (667 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightfield/refs/heads/main/openapi/lightfield-openapi-original.yml
Lightfield API

Documentation

Specifications

Other Resources

OpenAPI Specification
