## Create an opportunity `client.Opportunity.New(ctx, body) (*OpportunityCreateResponse, error)` **post** `/v1/opportunities` Creates a new opportunity record. The `$name` field 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 [list filtering](/using-the-api/list-endpoints/#filtering) 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 ### Parameters - `body OpportunityNewParams` - `Fields param.Field[map[string, OpportunityNewParamsFieldUnion]]` Field values for the new opportunity. System fields use a `$` prefix (e.g. `$name`, `$stage`); custom attributes use their bare slug. Required: `$name` (string). `$stage` accepts an option ID or label when provided. 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. Read definitions for the object type’s configured `$pipeline` and `$stage` fields and options. See [Pipelines and stages](/using-the-api/fields-and-relationships/#pipelines-and-stages) for write rules. - `map[string, OpportunityNewParamsFieldUnion]` - `string` - `float64` - `bool` - `type OpportunityNewParamsFieldArray []string` - `type OpportunityNewParamsFieldAddress struct{…}` - `City string` City name. - `Country string` 2-letter ISO 3166-1 alpha-2 country code. - `Latitude float64` Latitude coordinate. - `Longitude float64` Longitude coordinate. - `PostalCode string` Postal or ZIP code. - `State string` State or province. - `Street string` Street address line 1. - `Street2 string` Street address line 2. - `type OpportunityNewParamsFieldFullName struct{…}` - `FirstName string` The contact's first name. - `LastName string` The contact's last name. - `Relationships param.Field[map[string, OpportunityNewParamsRelationshipUnion]]` 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. - `map[string, OpportunityNewParamsRelationshipUnion]` - `string` - `type OpportunityNewParamsRelationshipArray []string` ### Returns - `type OpportunityCreateResponse struct{…}` - `ID string` Unique identifier for the entity. - `CreatedAt string` ISO 8601 timestamp of when the entity was created. - `Fields map[string, OpportunityCreateResponseField]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `Value OpportunityCreateResponseFieldValueUnion` The field value, or null if unset. - `string` - `float64` - `bool` - `type OpportunityCreateResponseFieldValueArray []string` - `type OpportunityCreateResponseFieldValueAddress struct{…}` - `City string` City name. - `Country string` 2-letter ISO 3166-1 alpha-2 country code. - `Latitude float64` Latitude coordinate. - `Longitude float64` Longitude coordinate. - `PostalCode string` Postal or ZIP code. - `State string` State or province. - `Street string` Street address line 1. - `Street2 string` Street address line 2. - `type OpportunityCreateResponseFieldValueFullName struct{…}` - `FirstName string` The contact's first name. - `LastName string` The contact's last name. - `ValueType string` The data type of the field. - `const OpportunityCreateResponseFieldValueTypeAddress OpportunityCreateResponseFieldValueType = "ADDRESS"` - `const OpportunityCreateResponseFieldValueTypeCheckbox OpportunityCreateResponseFieldValueType = "CHECKBOX"` - `const OpportunityCreateResponseFieldValueTypeCurrency OpportunityCreateResponseFieldValueType = "CURRENCY"` - `const OpportunityCreateResponseFieldValueTypeDatetime OpportunityCreateResponseFieldValueType = "DATETIME"` - `const OpportunityCreateResponseFieldValueTypeEmail OpportunityCreateResponseFieldValueType = "EMAIL"` - `const OpportunityCreateResponseFieldValueTypeFullName OpportunityCreateResponseFieldValueType = "FULL_NAME"` - `const OpportunityCreateResponseFieldValueTypeMarkdown OpportunityCreateResponseFieldValueType = "MARKDOWN"` - `const OpportunityCreateResponseFieldValueTypeMultiSelect OpportunityCreateResponseFieldValueType = "MULTI_SELECT"` - `const OpportunityCreateResponseFieldValueTypeNumber OpportunityCreateResponseFieldValueType = "NUMBER"` - `const OpportunityCreateResponseFieldValueTypeSingleSelect OpportunityCreateResponseFieldValueType = "SINGLE_SELECT"` - `const OpportunityCreateResponseFieldValueTypeSocialHandle OpportunityCreateResponseFieldValueType = "SOCIAL_HANDLE"` - `const OpportunityCreateResponseFieldValueTypeTelephone OpportunityCreateResponseFieldValueType = "TELEPHONE"` - `const OpportunityCreateResponseFieldValueTypeText OpportunityCreateResponseFieldValueType = "TEXT"` - `const OpportunityCreateResponseFieldValueTypeURL OpportunityCreateResponseFieldValueType = "URL"` - `const OpportunityCreateResponseFieldValueTypeHTML OpportunityCreateResponseFieldValueType = "HTML"` - `HTTPLink string` URL to view the entity in the Lightfield web app, or null. - `Relationships map[string, OpportunityCreateResponseRelationship]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). A self-referential relationship keeps its merged values and includes optional directional values. List filters select the current record's role with `:asSource` or `:asDestination`, for example `?parent:asSource[contains]=account_id`. - `Cardinality string` Whether the relationship is `has_one` or `has_many`. - `ObjectType string` The type of the related object (e.g. `account`, `contact`). - `Values []string` IDs of the related entities. - `Directions OpportunityCreateResponseRelationshipDirections` Directional values for a self-referential relationship. List filters use the relationship key with `:asSource` or `:asDestination`; writes continue to use the bare key. - `AsDestination OpportunityCreateResponseRelationshipDirectionsAsDestination` The current record is the destination (incoming) endpoint. - `Cardinality string` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `const OpportunityCreateResponseRelationshipDirectionsAsDestinationCardinalityHasOne OpportunityCreateResponseRelationshipDirectionsAsDestinationCardinality = "HAS_ONE"` - `const OpportunityCreateResponseRelationshipDirectionsAsDestinationCardinalityHasMany OpportunityCreateResponseRelationshipDirectionsAsDestinationCardinality = "HAS_MANY"` - `Values []string` IDs of the related entities in this direction. - `AsSource OpportunityCreateResponseRelationshipDirectionsAsSource` The current record is the source (outgoing) endpoint. - `Cardinality string` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `const OpportunityCreateResponseRelationshipDirectionsAsSourceCardinalityHasOne OpportunityCreateResponseRelationshipDirectionsAsSourceCardinality = "HAS_ONE"` - `const OpportunityCreateResponseRelationshipDirectionsAsSourceCardinalityHasMany OpportunityCreateResponseRelationshipDirectionsAsSourceCardinality = "HAS_MANY"` - `Values []string` IDs of the related entities in this direction. - `UpdatedAt string` ISO 8601 timestamp of when the entity was last updated, or null. - `ExternalID string` External identifier for the entity, or null if unset. ### Example ```go package main import ( "context" "fmt" "github.com/Lightfld/lightfield-go" "github.com/Lightfld/lightfield-go/option" ) func main() { client := githubcomlightfldlightfieldgo.NewClient( option.WithAPIKey("My API Key"), ) opportunityCreateResponse, err := client.Opportunity.New(context.TODO(), githubcomlightfldlightfieldgo.OpportunityNewParams{ Fields: map[string]githubcomlightfldlightfieldgo.OpportunityNewParamsFieldUnion{ "foo": githubcomlightfldlightfieldgo.OpportunityNewParamsFieldUnion{ OfString: githubcomlightfldlightfieldgo.String("string"), }, }, Relationships: map[string]githubcomlightfldlightfieldgo.OpportunityNewParamsRelationshipUnion{ "foo": githubcomlightfldlightfieldgo.OpportunityNewParamsRelationshipUnion{ OfString: githubcomlightfldlightfieldgo.String("string"), }, }, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", opportunityCreateResponse.ID) } ``` #### Response ```json { "id": "id", "createdAt": "createdAt", "fields": { "foo": { "value": "string", "valueType": "ADDRESS" } }, "httpLink": "httpLink", "relationships": { "foo": { "cardinality": "cardinality", "objectType": "objectType", "values": [ "string" ], "directions": { "asDestination": { "cardinality": "HAS_ONE", "values": [ "string" ] }, "asSource": { "cardinality": "HAS_ONE", "values": [ "string" ] } } } }, "updatedAt": "updatedAt", "externalId": "externalId" } ```