Lightfield Opportunities API
The Opportunities API from Lightfield — 3 operation(s) for opportunities.
OpenAPI Specification
openapi: 3.1.1
info:
title: API Reference Accounts Opportunities API
version: 0.0.0
tags:
- name: Opportunities
paths:
/v1/opportunities/definitions:
get:
operationId: opportunity.definitions
summary: Get opportunity field definitions
description: 'Returns the schema for all field and relationship definitions available on opportunities, including both system-defined and custom fields. Useful for understanding the shape of opportunity 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/):** `opportunities: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/OpportunityDefinitionsResponse'
'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:
- Opportunities
/v1/opportunities:
post:
operationId: opportunity.create
summary: Create an opportunity
description: 'Creates a new opportunity record. The `$name` and `$stage` fields and the `$account` relationship are required.
After creation, Lightfield automatically generates an opportunity summary in the background. The `$opportunityStatus` field is read-only and cannot be set via the API. The `$task`, `$note`, and `$meeting` relationships are also read-only — manage them via the `$opportunity` relationship on the task, the `$account`/`$opportunity` note relationships, or via the meeting''s `$contact` attendees that belong to this opportunity''s 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/):** `opportunities: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: OpportunityCreateFields
oneOf:
- type: object
properties:
$name:
type: string
description: Display name of the opportunity.
$stage:
type: string
description: Pipeline stage (`SINGLE_SELECT`). Pass the option ID or label from the field definition.
required:
- $name
- $stage
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: OpportunityCreateFieldsTyped
x-stainless-skip:
- typescript
- python
- go
- java
x-stainless-variantName: typed
- title: OpportunityCreateFieldsUntyped
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 opportunity. System fields use a `$` prefix (e.g. `$name`, `$stage`); custom attributes use their bare slug. Required: `$name` (string) and `$stage` (option ID or label). 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/opportunity/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: OpportunityCreateRelationships
oneOf:
- type: object
properties:
$account:
anyOf:
- type: string
- type: array
items:
type: string
description: ID of the account this opportunity belongs to.
$owner:
anyOf:
- type: string
- type: array
items:
type: string
description: ID of the user who owns this opportunity.
$createdBy:
anyOf:
- type: string
- type: array
items:
type: string
description: ID of the user who created this opportunity.
$champion:
anyOf:
- type: string
- type: array
items:
type: string
description: ID of the contact who is the internal champion.
$evaluator:
anyOf:
- type: string
- type: array
items:
type: string
description: ID of the contact who is the evaluator.
required:
- $account
additionalProperties:
anyOf:
- type: string
- type: array
items:
type: string
description: A single entity ID or an array of entity IDs.
title: OpportunityCreateRelationshipsTyped
x-stainless-skip:
- typescript
- python
- go
- java
x-stainless-variantName: typed
- title: OpportunityCreateRelationshipsUntyped
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 opportunity. System relationships use a `$` prefix (e.g. `$account`, `$owner`); custom relationships use their bare slug. `$account` is required. Each value is a single entity ID or an array of IDs. Call the <u>[definitions endpoint](/api/resources/opportunity/methods/definitions)</u> to list available relationship keys.
required:
- fields
- relationships
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OpportunityCreateResponse'
'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:
- Opportunities
get:
operationId: opportunity.list
summary: List opportunities
description: 'Returns a paginated list of opportunities. 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/):** `opportunities: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/OpportunityListResponse'
'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:
- Opportunities
/v1/opportunities/{id}:
post:
operationId: opportunity.update
summary: Update an opportunity
description: 'Updates an existing opportunity by ID. Only included fields and relationships are modified.
The `$opportunityStatus` field is read-only and cannot be updated. The `$task`, `$note`, and `$meeting` relationships are also read-only — manage them via the `$opportunity` relationship on the task, the `$account`/`$opportunity` note relationships, or via the meeting''s `$contact` attendees that belong to this opportunity''s account.
Supports idempotency via the `Idempotency-Key` header.
**[Required scope](/using-the-api/scopes/):** `opportunities: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 opportunity to update.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
fields:
title: OpportunityUpdateFields
oneOf:
- type: object
properties:
$name:
anyOf:
- type: string
- type: 'null'
description: Display name of the opportunity.
$stage:
anyOf:
- type: string
- type: 'null'
description: Pipeline stage (`SINGLE_SELECT`). Pass the option ID or label from the field definition.
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: OpportunityUpdateFieldsTyped
x-stainless-skip:
- typescript
- python
- go
- java
x-stainless-variantName: typed
- title: OpportunityUpdateFieldsUntyped
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`, `$stage`); 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/opportunity/methods/definitions)</u> for available options. See <u>[Fields and relationships](/using-the-api/fields-and-relationships/)</u> for value type details.
relationships:
title: OpportunityUpdateRelationships
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 opportunity owner.
$champion:
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 internal champion.
$evaluator:
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 evaluator.
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: OpportunityUpdateRelationshipsTyped
x-stainless-skip:
- typescript
- python
- go
- java
x-stainless-variantName: typed
- title: OpportunityUpdateRelationshipsUntyped
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`, `$champion`). Each value is an operation object with `add`, `remove`, or `replace`.
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OpportunityUpdateResponse'
'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:
- Opportunities
get:
operationId: opportunity.retrieve
summary: Retrieve an opportunity
description: 'Retrieves a single opportunity by its ID.
**[Required scope](/using-the-api/scopes/):** `opportunities: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 opportunity to retrieve.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OpportunityRetrieveResponse'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: '401'
content:
application/json:
sche
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightfield/refs/heads/main/openapi/lightfield-opportunities-api-openapi.yml