# Opportunity ## Definitions `opportunity.definitions() -> OpportunityDefinitionsResponse` **get** `/v1/opportunities/definitions` 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 [Fields and relationships](/using-the-api/fields-and-relationships/) for more details. **[Required scope](/using-the-api/scopes/):** `opportunities:read` **[Rate limit category](/using-the-api/rate-limits/):** Read ### Returns - `class OpportunityDefinitionsResponse: …` - `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: Dict[str, Union[str, float, bool, 3 more]]` Type-specific configuration (e.g. select options, currency code). - `str` - `float` - `bool` - `List[Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 11 more]` Data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `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. - `"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. ### Example ```python from lightfield import Lightfield client = Lightfield( api_key="My API Key", ) opportunity_definitions_response = client.opportunity.definitions() print(opportunity_definitions_response.field_definitions) ``` ## Create `opportunity.create(OpportunityCreateParams**kwargs) -> OpportunityCreateResponse` **post** `/v1/opportunities` 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` and `$note` relationships are also read-only — manage them via the `$opportunity` relationship on the task, or the `$account`/`$opportunity` note relationships instead. Supports idempotency via the `Idempotency-Key` header. **[Required scope](/using-the-api/scopes/):** `opportunities:create` **[Rate limit category](/using-the-api/rate-limits/):** Write ### Parameters - `fields: Union[Dict[str, Union[str, float, bool, 3 more]]]` 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 [definitions endpoint](/api/resources/opportunity/methods/definitions) to discover available fields and options. See [Fields and relationships](/using-the-api/fields-and-relationships/) for value type details. - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `SequenceNotStr[Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `Iterable[object]` - `Dict[str, object]` - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `Iterable[object]` - `Dict[str, object]` - `relationships: Union[Dict[str, Union[str, SequenceNotStr[str]]]]` 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 [definitions endpoint](/api/resources/opportunity/methods/definitions) to list available relationship keys. - `Dict[str, Union[str, SequenceNotStr[str]]]` - `str` - `SequenceNotStr[str]` ### Returns - `class OpportunityCreateResponse: …` - `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: Union[str, float, bool, 3 more]` The field value, or null if unset. - `str` - `float` - `bool` - `List[Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 11 more]` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `http_link: Optional[str]` URL to view the entity in the Lightfield web app, or null. - `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. ### Example ```python from lightfield import Lightfield client = Lightfield( api_key="My API Key", ) opportunity_create_response = client.opportunity.create( fields={ "foo": "string" }, relationships={ "foo": "string" }, ) print(opportunity_create_response.id) ``` ## Update `opportunity.update(strid, OpportunityUpdateParams**kwargs) -> OpportunityUpdateResponse` **post** `/v1/opportunities/{id}` 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` and `$note` relationships are also read-only — manage them via the `$opportunity` relationship on the task, or the `$account`/`$opportunity` note relationships instead. Supports idempotency via the `Idempotency-Key` header. **[Required scope](/using-the-api/scopes/):** `opportunities:update` **[Rate limit category](/using-the-api/rate-limits/):** Write ### Parameters - `id: str` Unique identifier of the opportunity to update. - `fields: Optional[Union[Dict[str, Union[str, float, bool, 3 more]]]]` 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 [definitions endpoint](/api/resources/opportunity/methods/definitions) for available options. See [Fields and relationships](/using-the-api/fields-and-relationships/) for value type details. - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `SequenceNotStr[Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `Iterable[object]` - `Dict[str, object]` - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `Iterable[object]` - `Dict[str, object]` - `relationships: Optional[Union[Dict[str, RelationshipsUnionMember0RelationshipsUnionMember0Item]]]` Relationship operations to apply. System relationships use a `$` prefix (e.g. `$owner`, `$champion`). Each value is an operation object with `add`, `remove`, or `replace`. - `Dict[str, RelationshipsUnionMember0RelationshipsUnionMember0Item]` - `add: Optional[Union[str, SequenceNotStr[str]]]` Entity ID(s) to add to the relationship. - `str` - `SequenceNotStr[str]` - `remove: Optional[Union[str, SequenceNotStr[str]]]` Entity ID(s) to remove from the relationship. - `str` - `SequenceNotStr[str]` - `replace: Optional[Union[str, SequenceNotStr[str]]]` Entity ID(s) to set as the entire relationship, replacing all existing associations. - `str` - `SequenceNotStr[str]` ### Returns - `class OpportunityUpdateResponse: …` - `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: Union[str, float, bool, 3 more]` The field value, or null if unset. - `str` - `float` - `bool` - `List[Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 11 more]` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `http_link: Optional[str]` URL to view the entity in the Lightfield web app, or null. - `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. ### Example ```python from lightfield import Lightfield client = Lightfield( api_key="My API Key", ) opportunity_update_response = client.opportunity.update( id="id", ) print(opportunity_update_response.id) ``` ## Retrieve `opportunity.retrieve(strid) -> OpportunityRetrieveResponse` **get** `/v1/opportunities/{id}` Retrieves a single opportunity by its ID. **[Required scope](/using-the-api/scopes/):** `opportunities:read` **[Rate limit category](/using-the-api/rate-limits/):** Read ### Parameters - `id: str` Unique identifier of the opportunity to retrieve. ### Returns - `class OpportunityRetrieveResponse: …` - `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: Union[str, float, bool, 3 more]` The field value, or null if unset. - `str` - `float` - `bool` - `List[Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 11 more]` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `http_link: Optional[str]` URL to view the entity in the Lightfield web app, or null. - `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. ### Example ```python from lightfield import Lightfield client = Lightfield( api_key="My API Key", ) opportunity_retrieve_response = client.opportunity.retrieve( "id", ) print(opportunity_retrieve_response.id) ``` ## List `opportunity.list(OpportunityListParams**kwargs) -> OpportunityListResponse` **get** `/v1/opportunities` Returns a paginated list of opportunities. Use `offset` and `limit` to paginate through results. See [List endpoints](/using-the-api/list-endpoints/) for more information about pagination. **[Required scope](/using-the-api/scopes/):** `opportunities:read` **[Rate limit category](/using-the-api/rate-limits/):** Search ### Parameters - `limit: Optional[int]` Maximum number of records to return. Defaults to 25, maximum 25. - `offset: Optional[int]` Number of records to skip for pagination. Defaults to 0. ### Returns - `class OpportunityListResponse: …` - `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: Union[str, float, bool, 3 more]` The field value, or null if unset. - `str` - `float` - `bool` - `List[Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 11 more]` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `http_link: Optional[str]` URL to view the entity in the Lightfield web app, or null. - `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. - `object: str` The object type, always `"list"`. - `total_count: int` Total number of entities matching the query. ### Example ```python from lightfield import Lightfield client = Lightfield( api_key="My API Key", ) opportunity_list_response = client.opportunity.list() print(opportunity_list_response.data) ``` ## Domain Types ### Opportunity Create Response - `class OpportunityCreateResponse: …` - `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: Union[str, float, bool, 3 more]` The field value, or null if unset. - `str` - `float` - `bool` - `List[Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 11 more]` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `http_link: Optional[str]` URL to view the entity in the Lightfield web app, or null. - `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. ### Opportunity Definitions Response - `class OpportunityDefinitionsResponse: …` - `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: Dict[str, Union[str, float, bool, 3 more]]` Type-specific configuration (e.g. select options, currency code). - `str` - `float` - `bool` - `List[Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 11 more]` Data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `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. - `"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. ### Opportunity List Response - `class OpportunityListResponse: …` - `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: Union[str, float, bool, 3 more]` The field value, or null if unset. - `str` - `float` - `bool` - `List[Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 11 more]` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `http_link: Optional[str]` URL to view the entity in the Lightfield web app, or null. - `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. - `object: str` The object type, always `"list"`. - `total_count: int` Total number of entities matching the query. ### Opportunity Retrieve Response - `class OpportunityRetrieveResponse: …` - `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: Union[str, float, bool, 3 more]` The field value, or null if unset. - `str` - `float` - `bool` - `List[Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 11 more]` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `http_link: Optional[str]` URL to view the entity in the Lightfield web app, or null. - `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. ### Opportunity Update Response - `class OpportunityUpdateResponse: …` - `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: Union[str, float, bool, 3 more]` The field value, or null if unset. - `str` - `float` - `bool` - `List[Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `Dict[str, Union[str, float, bool, 3 more]]` - `str` - `float` - `bool` - `List[Optional[object]]` - `Dict[str, object]` - `value_type: Literal["ADDRESS", "CHECKBOX", "CURRENCY", 11 more]` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `http_link: Optional[str]` URL to view the entity in the Lightfield web app, or null. - `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.