The Accounts API from Lightfield — 3 operation(s) for accounts.
openapi: 3.1.1
info:
title: API Reference Accounts API
version: 0.0.0
tags:
- name: Accounts
paths:
/v1/accounts/definitions:
get:
operationId: account.definitions
summary: Get account field definitions
description: 'Returns the schema for all field and relationship definitions available on accounts, including both system-defined and custom fields. Useful for understanding the shape of account 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/):** `accounts: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/AccountDefinitionsResponse'
'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:
- Accounts
/v1/accounts:
post:
operationId: account.create
summary: Create an account
description: 'Creates a new account record. The `$name` field is required.
If a `$website` is provided, Lightfield automatically enriches the account in the background. The `$howTheyMakeMoney` and `$accountStatus` fields are read-only and cannot be set via the API. The `$opportunity`, `$task`, `$note`, and `$meeting` relationships are also read-only — manage them via the `$account` relationship on the opportunity or task, the `$account`/`$opportunity` note relationships, or via the meeting''s `$contact` attendees that belong to this account.
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/):** `accounts: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: AccountCreateFields
oneOf:
- type: object
properties:
$name:
type: string
description: Display name of the account.
$facebook:
anyOf:
- type: string
- type: 'null'
description: Facebook handle or profile identifier (`SOCIAL_HANDLE`).
$headcount:
anyOf:
- type: string
- type: 'null'
description: Employee count range (`SINGLE_SELECT`). Pass the option ID or label from the field definition.
$industry:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Industries the account operates in (`MULTI_SELECT`). Pass option IDs or labels from the field definition.
$instagram:
anyOf:
- type: string
- type: 'null'
description: Instagram handle or profile identifier (`SOCIAL_HANDLE`).
$lastFundingType:
anyOf:
- type: string
- type: 'null'
description: Most recent funding round type (`SINGLE_SELECT`). Pass the option ID or label from the field definition.
$linkedIn:
anyOf:
- type: string
- type: 'null'
description: LinkedIn handle or profile identifier (`SOCIAL_HANDLE`).
$primaryAddress:
anyOf:
- $ref: '#/components/schemas/Address'
- type: 'null'
description: Primary address (`ADDRESS`).
$twitter:
anyOf:
- type: string
- type: 'null'
description: Twitter/X handle (`SOCIAL_HANDLE`).
$website:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Website URLs associated with the account (`URL`, multi-value).
required:
- $name
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: AccountCreateFieldsTyped
x-stainless-skip:
- typescript
- python
- go
- java
x-stainless-variantName: typed
- title: AccountCreateFieldsUntyped
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 account. System fields use a `$` prefix (e.g. `$name`, `$website`); custom attributes use their bare slug (e.g. `tier`, `renewalDate`). Required: `$name` (string). Fields of type `SINGLE_SELECT` or `MULTI_SELECT` accept either an option ID or label from the field''s `typeConfiguration.options` — call the <u>[definitions endpoint](/api/resources/account/methods/definitions)</u> to discover available fields and options. See <u>[Fields and relationships](/using-the-api/fields-and-relationships/)</u> for value type details.'
relationships:
title: AccountCreateRelationships
oneOf:
- type: object
properties:
$owner:
anyOf:
- type: string
- type: array
items:
type: string
description: ID of the user who owns this account.
$contact:
anyOf:
- type: string
- type: array
items:
type: string
description: ID(s) of contacts to associate with this account.
additionalProperties:
anyOf:
- type: string
- type: array
items:
type: string
description: A single entity ID or an array of entity IDs.
title: AccountCreateRelationshipsTyped
x-stainless-skip:
- typescript
- python
- go
- java
x-stainless-variantName: typed
- title: AccountCreateRelationshipsUntyped
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 account. System relationships use a `$` prefix (e.g. `$owner`, `$contact`); 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/account/methods/definitions)</u> to list available relationship keys.
required:
- fields
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCreateResponse'
'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:
- Accounts
get:
operationId: account.list
summary: List accounts
description: 'Returns a paginated list of accounts. 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/):** `accounts: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/AccountListResponse'
'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:
- Accounts
/v1/accounts/{id}:
post:
operationId: account.update
summary: Update an account
description: 'Updates an existing account by ID. Only included fields and relationships are modified.
The `$howTheyMakeMoney` and `$accountStatus` fields are read-only and cannot be updated. The `$opportunity`, `$task`, `$note`, and `$meeting` relationships are also read-only — manage them via the `$account` relationship on the opportunity or task, the `$account`/`$opportunity` note relationships, or via the meeting''s `$contact` attendees that belong to this account.
Supports idempotency via the `Idempotency-Key` header.
**[Required scope](/using-the-api/scopes/):** `accounts: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 account to update.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
fields:
title: AccountUpdateFields
oneOf:
- type: object
properties:
$name:
anyOf:
- type: string
- type: 'null'
description: Display name of the account.
$facebook:
anyOf:
- type: string
- type: 'null'
description: Facebook handle or profile identifier (`SOCIAL_HANDLE`).
$headcount:
anyOf:
- type: string
- type: 'null'
description: Employee count range (`SINGLE_SELECT`). Pass the option ID or label from the field definition.
$industry:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Industries the account operates in (`MULTI_SELECT`). Pass option IDs or labels from the field definition.
$instagram:
anyOf:
- type: string
- type: 'null'
description: Instagram handle or profile identifier (`SOCIAL_HANDLE`).
$lastFundingType:
anyOf:
- type: string
- type: 'null'
description: Most recent funding round type (`SINGLE_SELECT`). Pass the option ID or label from the field definition.
$linkedIn:
anyOf:
- type: string
- type: 'null'
description: LinkedIn handle or profile identifier (`SOCIAL_HANDLE`).
$primaryAddress:
anyOf:
- $ref: '#/components/schemas/Address'
- type: 'null'
description: Primary address (`ADDRESS`).
$twitter:
anyOf:
- type: string
- type: 'null'
description: Twitter/X handle (`SOCIAL_HANDLE`).
$website:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Website URLs associated with the account (`URL`, multi-value).
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: AccountUpdateFieldsTyped
x-stainless-skip:
- typescript
- python
- go
- java
x-stainless-variantName: typed
- title: AccountUpdateFieldsUntyped
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. `$name`); custom attributes use their bare slug. `SINGLE_SELECT` and `MULTI_SELECT` fields accept an option ID or label — call the <u>[definitions endpoint](/api/resources/account/methods/definitions)</u> for available options. See <u>[Fields and relationships](/using-the-api/fields-and-relationships/)</u> for value type details.
relationships:
title: AccountUpdateRelationships
oneOf:
- type: object
properties:
$owner:
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 the account owner.
$contact:
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 contacts.
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: AccountUpdateRelationshipsTyped
x-stainless-skip:
- typescript
- python
- go
- java
x-stainless-variantName: typed
- title: AccountUpdateRelationshipsUntyped
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. `$owner`, `$contact`). Each value is an operation object with `add`, `remove`, or `replace`.
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountUpdateResponse'
'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
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightfield/refs/heads/main/openapi/lightfield-accounts-api-openapi.yml