Lightfield Objects API
The Objects API from Lightfield — 5 operation(s) for objects.
OpenAPI Specification
openapi: 3.1.1
info:
title: API Reference Accounts Objects API
version: 0.0.0
tags:
- name: Objects
paths:
/v1/objects/{entitySlug}/values:
post:
operationId: object.create
summary: Create a custom object record
description: Creates a new record for the specified custom object type.
security:
- bearerAuth: []
parameters:
- name: Lightfield-Version
in: header
required: true
description: Required API version header. Requests may error without it.
schema:
type: string
enum:
- '2026-03-01'
default: '2026-03-01'
example: '2026-03-01'
- name: entitySlug
in: path
required: true
schema:
type: string
description: The slug of the custom object type.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
fields:
type: object
propertyNames:
type: string
additionalProperties:
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: Field names to values for the new record.
relationships:
type: object
propertyNames:
type: string
additionalProperties:
anyOf:
- type: string
- type: array
items:
type: string
description: A single entity ID or an array of entity IDs.
description: Relationship names to entity ID(s) to associate.
required:
- fields
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectCreateResponse'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'415':
description: '415'
content:
application/json:
schema:
$ref: '#/components/schemas/UnsupportedMediaTypeError'
'422':
description: '422'
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableContentError'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'503':
description: '503'
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableError'
'504':
description: '504'
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
tags:
- Objects
/v1/objects/{entitySlug}/values/{id}:
get:
operationId: object.retrieve
summary: Get a custom object record
description: Retrieves a single record by ID for the specified custom object type.
security:
- bearerAuth: []
parameters:
- name: Lightfield-Version
in: header
required: true
description: Required API version header. Requests may error without it.
schema:
type: string
enum:
- '2026-03-01'
default: '2026-03-01'
example: '2026-03-01'
- name: entitySlug
in: path
required: true
schema:
type: string
description: The slug of the custom object type.
- name: id
in: path
required: true
schema:
type: string
description: The ID of the record to retrieve.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectRetrieveResponse'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'415':
description: '415'
content:
application/json:
schema:
$ref: '#/components/schemas/UnsupportedMediaTypeError'
'422':
description: '422'
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableContentError'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'503':
description: '503'
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableError'
'504':
description: '504'
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
tags:
- Objects
post:
operationId: object.update
summary: Update a custom object record
description: Updates an existing record by ID for the specified custom object type. Only included fields and relationships are modified.
security:
- bearerAuth: []
parameters:
- name: Lightfield-Version
in: header
required: true
description: Required API version header. Requests may error without it.
schema:
type: string
enum:
- '2026-03-01'
default: '2026-03-01'
example: '2026-03-01'
- name: entitySlug
in: path
required: true
schema:
type: string
description: The slug of the custom object type.
- name: id
in: path
required: true
schema:
type: string
description: The ID of the record to update.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
fields:
type: object
propertyNames:
type: string
additionalProperties:
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: Field names to values. Only provided fields are modified.
relationships:
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
add:
anyOf:
- type: string
- type: array
items:
type: string
description: Entity ID(s) to add to the relationship.
remove:
anyOf:
- type: string
- type: array
items:
type: string
description: Entity ID(s) to remove from the relationship.
replace:
anyOf:
- anyOf:
- type: string
- type: array
items:
type: string
description: A single entity ID or an array of entity IDs.
- type: 'null'
description: Entity ID(s) to set as the relationship replacement, or null to clear supported relationships.
additionalProperties: false
description: An operation to modify a relationship. Provide one of `add`, `remove`, or `replace`.
description: Relationship names to operations (`add`, `remove`, or `replace`).
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectUpdateResponse'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'415':
description: '415'
content:
application/json:
schema:
$ref: '#/components/schemas/UnsupportedMediaTypeError'
'422':
description: '422'
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableContentError'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'503':
description: '503'
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableError'
'504':
description: '504'
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
tags:
- Objects
/v1/objects/{entitySlug}:
get:
operationId: object.list
summary: List custom object records
description: Returns a paginated list of records for the specified custom object type. Use `offset` and `limit` to paginate through results, and `$field` query parameters to filter. See <u>[List endpoints](/using-the-api/list-endpoints/)</u> for more information about <u>[pagination](/using-the-api/list-endpoints/#pagination)</u> and <u>[filtering](/using-the-api/list-endpoints/#filtering)</u>.
security:
- bearerAuth: []
parameters:
- name: Lightfield-Version
in: header
required: true
description: Required API version header. Requests may error without it.
schema:
type: string
enum:
- '2026-03-01'
default: '2026-03-01'
example: '2026-03-01'
- name: entitySlug
in: path
required: true
schema:
type: string
description: The slug of the custom object type.
- name: offset
in: query
schema:
type: integer
minimum: 0
maximum: 9007199254740991
description: Number of records to skip for pagination. Defaults to 0.
allowEmptyValue: true
allowReserved: true
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 9007199254740991
description: Maximum number of records to return. Defaults to 25, maximum 25.
allowEmptyValue: true
allowReserved: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectListResponse'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'415':
description: '415'
content:
application/json:
schema:
$ref: '#/components/schemas/UnsupportedMediaTypeError'
'422':
description: '422'
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableContentError'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'503':
description: '503'
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableError'
'504':
description: '504'
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
tags:
- Objects
/v1/objects/{entitySlug}/definitions:
get:
operationId: object.definitions
summary: Get definitions for a custom object type
description: Returns field and relationship definitions for the specified custom object type.
security:
- bearerAuth: []
parameters:
- name: Lightfield-Version
in: header
required: true
description: Required API version header. Requests may error without it.
schema:
type: string
enum:
- '2026-03-01'
default: '2026-03-01'
example: '2026-03-01'
- name: entitySlug
in: path
required: true
schema:
type: string
description: The slug of the custom object type.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectDefinitionsResponse'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'415':
description: '415'
content:
application/json:
schema:
$ref: '#/components/schemas/UnsupportedMediaTypeError'
'422':
description: '422'
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableContentError'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'503':
description: '503'
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableError'
'504':
description: '504'
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
tags:
- Objects
/v1/objects:
get:
operationId: object.listDefinitions
summary: List custom object types
description: Returns all custom object types available to the caller.
security:
- bearerAuth: []
parameters:
- name: Lightfield-Version
in: header
required: true
description: Required API version header. Requests may error without it.
schema:
type: string
enum:
- '2026-03-01'
default: '2026-03-01'
example: '2026-03-01'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectListDefinitionsResponse'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'415':
description: '415'
content:
application/json:
schema:
$ref: '#/components/schemas/UnsupportedMediaTypeError'
'422':
description: '422'
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableContentError'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'503':
description: '503'
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableError'
'504':
description: '504'
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
tags:
- Objects
components:
schemas:
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
ObjectListResponse:
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
ConflictError:
type: object
properties:
type:
const: conflict
message:
type: string
default: Conflict
required:
- type
- message
UnprocessableContentError:
type: object
properties:
type:
const: unprocessable_content
message:
type: string
default: Unprocessable Content
required:
- type
- message
ObjectDefinitionsResponse:
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
- relationshipD
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightfield/refs/heads/main/openapi/lightfield-objects-api-openapi.yml