Lightfield Contacts API
The Contacts API from Lightfield — 3 operation(s) for contacts.
OpenAPI Specification
openapi: 3.1.1
info:
title: API Reference Accounts Contacts API
version: 0.0.0
tags:
- name: Contacts
paths:
/v1/contacts/definitions:
get:
operationId: contact.definitions
summary: Get contact field definitions
description: 'Returns the schema for all field and relationship definitions available on contacts, including both system-defined and custom fields. Useful for understanding the shape of contact data before creating or updating records. See <u>[Fields and relationships](/using-the-api/fields-and-relationships/)</u> for more details.
**[Required scope](/using-the-api/scopes/):** `contacts:read`
**[Rate limit category](/using-the-api/rate-limits/):** Read'
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/ContactDefinitionsResponse'
'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:
- Contacts
/v1/contacts:
post:
operationId: contact.create
summary: Create a contact
description: 'Creates a new contact record.
After creation, Lightfield automatically enriches the contact in the background.
Supports idempotency via the `Idempotency-Key` header.
To avoid duplicates, we recommend a find-or-create pattern — use <u>[list filtering](/using-the-api/list-endpoints/#filtering)</u> to check if a record exists before creating.
**[Required scope](/using-the-api/scopes/):** `contacts:create`
**[Rate limit category](/using-the-api/rate-limits/):** Write'
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'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
fields:
title: ContactCreateFields
oneOf:
- type: object
properties:
$email:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: List of email addresses for the contact (`EMAIL`, multi-value).
$name:
anyOf:
- $ref: '#/components/schemas/FullName'
- type: 'null'
description: 'The contact''s name. Unlike other resources, this is an object: `{ firstName?: string, lastName?: string }`, not a plain string.'
$profilePhotoUrl:
anyOf:
- type: string
- type: 'null'
description: URL of the contact's profile photo (`URL`).
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'
title: ContactCreateFieldsTyped
x-stainless-skip:
- typescript
- python
- go
- java
x-stainless-variantName: typed
- title: ContactCreateFieldsUntyped
type: object
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'
x-stainless-skip:
- cli
x-stainless-variantName: untyped
description: 'Field values for the new contact. System fields use a `$` prefix (e.g. `$email`, `$name`); custom attributes use their bare slug. Note: `$name` is an object `{ firstName, lastName }`, not a plain string. Call the <u>[definitions endpoint](/api/resources/contact/methods/definitions)</u> to discover available fields and their types. See <u>[Fields and relationships](/using-the-api/fields-and-relationships/)</u> for value type details.'
relationships:
title: ContactCreateRelationships
oneOf:
- type: object
properties:
$account:
anyOf:
- type: string
- type: array
items:
type: string
description: ID(s) of accounts to associate with this contact.
additionalProperties:
anyOf:
- type: string
- type: array
items:
type: string
description: A single entity ID or an array of entity IDs.
title: ContactCreateRelationshipsTyped
x-stainless-skip:
- typescript
- python
- go
- java
x-stainless-variantName: typed
- title: ContactCreateRelationshipsUntyped
type: object
additionalProperties:
anyOf:
- type: string
- type: array
items:
type: string
description: A single entity ID or an array of entity IDs.
x-stainless-skip:
- cli
x-stainless-variantName: untyped
description: Relationships to set on the new contact. System relationships use a `$` prefix (e.g. `$account`); custom relationships use their bare slug. Each value is a single entity ID or an array of IDs. Call the <u>[definitions endpoint](/api/resources/contact/methods/definitions)</u> to list available relationship keys.
required:
- fields
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ContactCreateResponse'
'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:
- Contacts
get:
operationId: contact.list
summary: List contacts
description: 'Returns a paginated list of contacts. 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>.
**[Required scope](/using-the-api/scopes/):** `contacts:read`
**[Rate limit category](/using-the-api/rate-limits/):** Search'
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: 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/ContactListResponse'
'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:
- Contacts
/v1/contacts/{id}:
post:
operationId: contact.update
summary: Update a contact
description: 'Updates an existing contact by ID. Only included fields and relationships are modified.
Supports idempotency via the `Idempotency-Key` header.
**[Required scope](/using-the-api/scopes/):** `contacts:update`
**[Rate limit category](/using-the-api/rate-limits/):** Write'
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: id
in: path
required: true
schema:
type: string
description: Unique identifier of the contact to update.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
fields:
title: ContactUpdateFields
oneOf:
- type: object
properties:
$email:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: List of email addresses for the contact (`EMAIL`, multi-value).
$name:
anyOf:
- $ref: '#/components/schemas/FullName'
- type: 'null'
description: 'The contact''s name. Unlike other resources, this is an object: `{ firstName?: string, lastName?: string }`, not a plain string.'
$profilePhotoUrl:
anyOf:
- type: string
- type: 'null'
description: URL of the contact's profile photo (`URL`).
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'
title: ContactUpdateFieldsTyped
x-stainless-skip:
- typescript
- python
- go
- java
x-stainless-variantName: typed
- title: ContactUpdateFieldsUntyped
type: object
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'
x-stainless-skip:
- cli
x-stainless-variantName: untyped
description: 'Field values to update — only provided fields are modified; omitted fields are left unchanged. System fields use a `$` prefix (e.g. `$email`); custom attributes use their bare slug. Note: `$name` is an object `{ firstName, lastName }`, not a plain string. Call the <u>[definitions endpoint](/api/resources/contact/methods/definitions)</u> for available fields and types. See <u>[Fields and relationships](/using-the-api/fields-and-relationships/)</u> for value type details.'
relationships:
title: ContactUpdateRelationships
oneOf:
- type: object
properties:
$account:
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: Operation to modify associated accounts.
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`.
title: ContactUpdateRelationshipsTyped
x-stainless-skip:
- typescript
- python
- go
- java
x-stainless-variantName: typed
- title: ContactUpdateRelationshipsUntyped
type: object
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`.
x-stainless-skip:
- cli
x-stainless-variantName: untyped
description: Relationship operations to apply. System relationships use a `$` prefix (e.g. `$account`). Each value is an operation object with `add`, `remove`, or `replace`.
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ContactUpdateResponse'
'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:
- Contacts
get:
operationId: contact.retrieve
summary: Retrieve a contact
description: 'Retrieves a single contact by its ID.
**[Required scope](/using-the-api/scopes/):** `contacts:read`
**[Rate limit category](/using-the-api/rate-limits/):** Read'
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: id
in: path
required: true
schema:
type: string
description: Unique identifier of the contact to retrieve.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ContactRetrieveResponse'
'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:
- Contacts
components:
schemas:
ContactRetrieveResponse:
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`).
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightfield/refs/heads/main/openapi/lightfield-contacts-api-openapi.yml