Skip to content
Lightfield Lightfield
API Reference

Object

Custom objects and relationships are available on Pro and Growth plans. Records can be fetched and manipulated via these endpoints, and definitions can be fetched to discover the available custom object types in the system.

Create a custom object record
object.create(strentity_slug, ObjectCreateParams**kwargs) -> ObjectCreateResponse
POST/v1/objects/{entitySlug}/values
Get a custom object record
object.retrieve(strid, ObjectRetrieveParams**kwargs) -> ObjectRetrieveResponse
GET/v1/objects/{entitySlug}/values/{id}
Update a custom object record
object.update(strid, ObjectUpdateParams**kwargs) -> ObjectUpdateResponse
POST/v1/objects/{entitySlug}/values/{id}
Delete a custom object record
object.delete(strid, ObjectDeleteParams**kwargs) -> ObjectDeleteResponse
DELETE/v1/objects/{entitySlug}/values/{id}
List custom object records
object.list(strentity_slug, ObjectListParams**kwargs) -> ObjectListResponse
GET/v1/objects/{entitySlug}
Get definitions for a custom object type
object.definitions(strentity_slug) -> ObjectDefinitionsResponse
GET/v1/objects/{entitySlug}/definitions
List custom object types
object.list_definitions() -> ObjectListDefinitionsResponse
GET/v1/objects
Get field value history for a custom object record
object.field_history(strfield_key, ObjectFieldHistoryParams**kwargs) -> ObjectFieldHistoryResponse
GET/v1/objects/{entitySlug}/values/{id}/fields/{fieldKey}/history
ModelsExpand Collapse
class ObjectCreateResponse: …
id: str

Unique identifier for the entity.

created_at: str

ISO 8601 timestamp of when the entity was created.

fields: Dict[str, Fields]

Map of field names to their typed values. System fields are prefixed with $ (e.g. $name, $email); custom attributes use their bare slug.

value: Optional[FieldsValue]

The field value, or null if unset.

One of the following:
str
float
bool
List[str]
class FieldsValueAddress: …
city: Optional[str]

City name.

country: Optional[str]

2-letter ISO 3166-1 alpha-2 country code.

latitude: Optional[float]

Latitude coordinate.

longitude: Optional[float]

Longitude coordinate.

postal_code: Optional[str]

Postal or ZIP code.

state: Optional[str]

State or province.

street: Optional[str]

Street address line 1.

street2: Optional[str]

Street address line 2.

class FieldsValueFullName: …
first_name: Optional[str]

The contact’s first name.

last_name: Optional[str]

The contact’s last name.

value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 12 more]

The data type of the field.

One of the following:
"ADDRESS"
"CHECKBOX"
"CURRENCY"
"DATETIME"
"EMAIL"
"FULL_NAME"
"MARKDOWN"
"MULTI_SELECT"
"NUMBER"
"SINGLE_SELECT"
"SOCIAL_HANDLE"
"TELEPHONE"
"TEXT"
"URL"
"HTML"
relationships: Dict[str, Relationships]

Map of relationship names to their associated entities. System relationships are prefixed with $ (e.g. $owner, $contact).

cardinality: str

Whether the relationship is has_one or has_many.

object_type: str

The type of the related object (e.g. account, contact).

values: List[str]

IDs of the related entities.

updated_at: Optional[str]

ISO 8601 timestamp of when the entity was last updated, or null.

external_id: Optional[str]

External identifier for the entity, or null if unset.

class ObjectDefinitionsResponse: …
field_definitions: Dict[str, FieldDefinitions]

Map of field keys to their definitions, including both system and custom fields.

description: Optional[str]

Description of the field, or null.

label: str

Human-readable display name of the field.

type_configuration: FieldDefinitionsTypeConfiguration

Type-specific configuration (e.g. select options, currency code).

currency: Optional[str]

ISO 4217 3-letter currency code.

handle_service: Optional[Literal["TWITTER", "LINKEDIN", "FACEBOOK", "INSTAGRAM"]]

Social platform associated with this handle field.

One of the following:
"TWITTER"
"LINKEDIN"
"FACEBOOK"
"INSTAGRAM"
multiple_values: Optional[bool]

Whether this field accepts multiple values.

options: Optional[List[FieldDefinitionsTypeConfigurationOption]]

Available options for select fields.

id: str

Unique identifier of the select option.

label: str

Human-readable display name of the option.

description: Optional[str]

Description of the option, or null.

unique: Optional[bool]

Whether values for this field must be unique.

value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 12 more]

Data type of the field.

One of the following:
"ADDRESS"
"CHECKBOX"
"CURRENCY"
"DATETIME"
"EMAIL"
"FULL_NAME"
"MARKDOWN"
"MULTI_SELECT"
"NUMBER"
"SINGLE_SELECT"
"SOCIAL_HANDLE"
"TELEPHONE"
"TEXT"
"URL"
"HTML"
id: Optional[str]

Unique identifier of the field definition.

read_only: Optional[bool]

true for fields that are not writable via the API (e.g. AI-generated summaries). false or absent for writable fields.

object_type: str

The object type these definitions belong to (e.g. account).

relationship_definitions: Dict[str, RelationshipDefinitions]

Map of relationship keys to their definitions.

cardinality: Literal["HAS_ONE", "HAS_MANY"]

Whether this is a has_one or has_many relationship.

One of the following:
"HAS_ONE"
"HAS_MANY"
description: Optional[str]

Description of the relationship, or null.

label: str

Human-readable display name of the relationship.

object_type: str

The type of the related object (e.g. account, contact).

id: Optional[str]

Unique identifier of the relationship definition.

class ObjectDeleteResponse: …
id: str

Unique identifier for the entity.

created_at: str

ISO 8601 timestamp of when the entity was created.

fields: Dict[str, Fields]

Map of field names to their typed values. System fields are prefixed with $ (e.g. $name, $email); custom attributes use their bare slug.

value: Optional[FieldsValue]

The field value, or null if unset.

One of the following:
str
float
bool
List[str]
class FieldsValueAddress: …
city: Optional[str]

City name.

country: Optional[str]

2-letter ISO 3166-1 alpha-2 country code.

latitude: Optional[float]

Latitude coordinate.

longitude: Optional[float]

Longitude coordinate.

postal_code: Optional[str]

Postal or ZIP code.

state: Optional[str]

State or province.

street: Optional[str]

Street address line 1.

street2: Optional[str]

Street address line 2.

class FieldsValueFullName: …
first_name: Optional[str]

The contact’s first name.

last_name: Optional[str]

The contact’s last name.

value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 12 more]

The data type of the field.

One of the following:
"ADDRESS"
"CHECKBOX"
"CURRENCY"
"DATETIME"
"EMAIL"
"FULL_NAME"
"MARKDOWN"
"MULTI_SELECT"
"NUMBER"
"SINGLE_SELECT"
"SOCIAL_HANDLE"
"TELEPHONE"
"TEXT"
"URL"
"HTML"
relationships: Dict[str, Relationships]

Map of relationship names to their associated entities. System relationships are prefixed with $ (e.g. $owner, $contact).

cardinality: str

Whether the relationship is has_one or has_many.

object_type: str

The type of the related object (e.g. account, contact).

values: List[str]

IDs of the related entities.

updated_at: Optional[str]

ISO 8601 timestamp of when the entity was last updated, or null.

external_id: Optional[str]

External identifier for the entity, or null if unset.

class ObjectFieldHistoryResponse: …
data: List[Data]

Recorded values for the field, newest first.

display_value: str

Human-readable rendering of the value (e.g. a select option label), suitable for display.

is_create: bool

True for the record’s original value. Only set when the full history fits in the response (never on a truncated/paginated page).

recorded_at: str

ISO 8601 timestamp of when this value was recorded.

value: Optional[DataValue]

The field value, or null if unset.

One of the following:
str
float
bool
List[str]
class DataValueAddress: …
city: Optional[str]

City name.

country: Optional[str]

2-letter ISO 3166-1 alpha-2 country code.

latitude: Optional[float]

Latitude coordinate.

longitude: Optional[float]

Longitude coordinate.

postal_code: Optional[str]

Postal or ZIP code.

state: Optional[str]

State or province.

street: Optional[str]

Street address line 1.

street2: Optional[str]

Street address line 2.

class DataValueFullName: …
first_name: Optional[str]

The contact’s first name.

last_name: Optional[str]

The contact’s last name.

value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 12 more]

The data type of the field.

One of the following:
"ADDRESS"
"CHECKBOX"
"CURRENCY"
"DATETIME"
"EMAIL"
"FULL_NAME"
"MARKDOWN"
"MULTI_SELECT"
"NUMBER"
"SINGLE_SELECT"
"SOCIAL_HANDLE"
"TELEPHONE"
"TEXT"
"URL"
"HTML"
has_more: bool

Whether more history exists beyond this page.

next_cursor: Optional[str]

Cursor to pass as after to fetch the next page, or null when there are no more entries.

class ObjectListDefinitionsResponse: …
data: List[Data]

All object types available to the caller.

label: str

Human-readable display name.

object_type: str

The slug used to reference this object type in the API.

class ObjectListResponse: …
data: List[Data]

Array of entity objects for the current page.

id: str

Unique identifier for the entity.

created_at: str

ISO 8601 timestamp of when the entity was created.

fields: Dict[str, DataFields]

Map of field names to their typed values. System fields are prefixed with $ (e.g. $name, $email); custom attributes use their bare slug.

value: Optional[DataFieldsValue]

The field value, or null if unset.

One of the following:
str
float
bool
List[str]
class DataFieldsValueAddress: …
city: Optional[str]

City name.

country: Optional[str]

2-letter ISO 3166-1 alpha-2 country code.

latitude: Optional[float]

Latitude coordinate.

longitude: Optional[float]

Longitude coordinate.

postal_code: Optional[str]

Postal or ZIP code.

state: Optional[str]

State or province.

street: Optional[str]

Street address line 1.

street2: Optional[str]

Street address line 2.

class DataFieldsValueFullName: …
first_name: Optional[str]

The contact’s first name.

last_name: Optional[str]

The contact’s last name.

value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 12 more]

The data type of the field.

One of the following:
"ADDRESS"
"CHECKBOX"
"CURRENCY"
"DATETIME"
"EMAIL"
"FULL_NAME"
"MARKDOWN"
"MULTI_SELECT"
"NUMBER"
"SINGLE_SELECT"
"SOCIAL_HANDLE"
"TELEPHONE"
"TEXT"
"URL"
"HTML"
relationships: Dict[str, DataRelationships]

Map of relationship names to their associated entities. System relationships are prefixed with $ (e.g. $owner, $contact).

cardinality: str

Whether the relationship is has_one or has_many.

object_type: str

The type of the related object (e.g. account, contact).

values: List[str]

IDs of the related entities.

updated_at: Optional[str]

ISO 8601 timestamp of when the entity was last updated, or null.

external_id: Optional[str]

External identifier for the entity, or null if unset.

object: str

The object type, always "list".

total_count: int

Total number of entities matching the query.

minimum0
maximum9007199254740991
class ObjectRetrieveResponse: …
id: str

Unique identifier for the entity.

created_at: str

ISO 8601 timestamp of when the entity was created.

fields: Dict[str, Fields]

Map of field names to their typed values. System fields are prefixed with $ (e.g. $name, $email); custom attributes use their bare slug.

value: Optional[FieldsValue]

The field value, or null if unset.

One of the following:
str
float
bool
List[str]
class FieldsValueAddress: …
city: Optional[str]

City name.

country: Optional[str]

2-letter ISO 3166-1 alpha-2 country code.

latitude: Optional[float]

Latitude coordinate.

longitude: Optional[float]

Longitude coordinate.

postal_code: Optional[str]

Postal or ZIP code.

state: Optional[str]

State or province.

street: Optional[str]

Street address line 1.

street2: Optional[str]

Street address line 2.

class FieldsValueFullName: …
first_name: Optional[str]

The contact’s first name.

last_name: Optional[str]

The contact’s last name.

value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 12 more]

The data type of the field.

One of the following:
"ADDRESS"
"CHECKBOX"
"CURRENCY"
"DATETIME"
"EMAIL"
"FULL_NAME"
"MARKDOWN"
"MULTI_SELECT"
"NUMBER"
"SINGLE_SELECT"
"SOCIAL_HANDLE"
"TELEPHONE"
"TEXT"
"URL"
"HTML"
relationships: Dict[str, Relationships]

Map of relationship names to their associated entities. System relationships are prefixed with $ (e.g. $owner, $contact).

cardinality: str

Whether the relationship is has_one or has_many.

object_type: str

The type of the related object (e.g. account, contact).

values: List[str]

IDs of the related entities.

updated_at: Optional[str]

ISO 8601 timestamp of when the entity was last updated, or null.

external_id: Optional[str]

External identifier for the entity, or null if unset.

class ObjectUpdateResponse: …
id: str

Unique identifier for the entity.

created_at: str

ISO 8601 timestamp of when the entity was created.

fields: Dict[str, Fields]

Map of field names to their typed values. System fields are prefixed with $ (e.g. $name, $email); custom attributes use their bare slug.

value: Optional[FieldsValue]

The field value, or null if unset.

One of the following:
str
float
bool
List[str]
class FieldsValueAddress: …
city: Optional[str]

City name.

country: Optional[str]

2-letter ISO 3166-1 alpha-2 country code.

latitude: Optional[float]

Latitude coordinate.

longitude: Optional[float]

Longitude coordinate.

postal_code: Optional[str]

Postal or ZIP code.

state: Optional[str]

State or province.

street: Optional[str]

Street address line 1.

street2: Optional[str]

Street address line 2.

class FieldsValueFullName: …
first_name: Optional[str]

The contact’s first name.

last_name: Optional[str]

The contact’s last name.

value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 12 more]

The data type of the field.

One of the following:
"ADDRESS"
"CHECKBOX"
"CURRENCY"
"DATETIME"
"EMAIL"
"FULL_NAME"
"MARKDOWN"
"MULTI_SELECT"
"NUMBER"
"SINGLE_SELECT"
"SOCIAL_HANDLE"
"TELEPHONE"
"TEXT"
"URL"
"HTML"
relationships: Dict[str, Relationships]

Map of relationship names to their associated entities. System relationships are prefixed with $ (e.g. $owner, $contact).

cardinality: str

Whether the relationship is has_one or has_many.

object_type: str

The type of the related object (e.g. account, contact).

values: List[str]

IDs of the related entities.

updated_at: Optional[str]

ISO 8601 timestamp of when the entity was last updated, or null.

external_id: Optional[str]

External identifier for the entity, or null if unset.