> ## Documentation Index > Fetch the complete documentation index at: https://docs.heffl.com/llms.txt > Use this file to discover all available pages before exploring further. # Create deal > Creates a new deal in your CRM pipeline. Related entity IDs use prefixed string IDs (for example `clt_`, `dpl_`, `dps_`). Custom field values use `cf_*` keys — see the [Custom fields](/api-v2/custom-fields) guide. ## OpenAPI ````yaml /openapi.v2.json post /deals openapi: 3.1.1 info: title: Heffl API v2 (Beta) version: 2.0.0 description: >- Heffl REST API v2 (beta) — resource-oriented endpoints with consistent response envelopes. Endpoints, schemas, and behavior may change until GA. See Agent workflows and ID prefixes guides for automation. contact: name: Heffl Support url: https://heffl.com/support email: support@heffl.com servers: - url: https://api.heffl.com/api/v2 description: Production API Server security: - ApiKeyAuth: [] paths: /deals: post: tags: - Objects summary: Create deal description: >- Creates a new deal in your CRM pipeline. Related entity IDs use prefixed string IDs (for example `clt_`, `dpl_`, `dps_`). Custom field values use `cf_*` keys — see the [Custom fields](/api-v2/custom-fields) guide. operationId: objects.deals.create requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DealInput' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Deal' '400': description: Validation error or bad request content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '403': description: Insufficient permission content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/V2ApiError' components: schemas: DealInput: type: object properties: title: type: string description: Deal title clientId: type: string description: Contact or company ID (clt_ prefix) pipelineId: type: string description: Pipeline ID stageId: anyOf: - type: string - type: 'null' description: Pipeline stage ID leadId: type: string description: Lead ID sourceId: type: string description: CRM source ID ownerUserId: type: string description: Owner user ID price: type: number description: Deal value expectedCloseDate: type: string format: date-time description: Expected close date priority: type: string enum: - LOW - MEDIUM - HIGH description: Deal priority status: type: string enum: - ACTIVE - WON - LOST description: Deal status currency: type: string description: 3-letter ISO currency code isInclusiveTax: type: boolean description: Whether prices include tax assignees: type: array items: type: string description: Assignee user IDs contacts: type: array items: type: string description: Contact IDs linked to the deal tags: type: array items: type: string description: Tag IDs products: type: array items: $ref: '#/components/schemas/DealProductInput' description: Deal line items required: - title - clientId - pipelineId additionalProperties: description: >- Custom field values using cf_* keys. Only documented fields and cf_* keys are accepted. Deal: type: object properties: id: type: string description: Deal ID number: type: string description: Auto-generated deal number title: type: string description: Deal title clientId: anyOf: - type: string - type: 'null' description: Contact or company ID (clt_ prefix) client: anyOf: - type: object - type: 'null' description: Linked client record price: anyOf: - type: number - type: 'null' description: Deal value expectedCloseDate: anyOf: - type: string format: date-time - type: 'null' description: Expected close date status: anyOf: - type: string enum: - ACTIVE - WON - LOST - type: 'null' description: Deal status priority: anyOf: - type: string enum: - LOW - MEDIUM - HIGH - type: 'null' description: Deal priority pipelineId: anyOf: - type: string - type: 'null' description: Pipeline ID (dpl_ prefix) stageId: anyOf: - type: string - type: 'null' description: Pipeline stage ID (dps_ prefix) stage: anyOf: - type: string - type: 'null' description: Pipeline stage name leadId: anyOf: - type: string - type: 'null' description: Lead ID leadName: anyOf: - type: string - type: 'null' description: Lead name crmSourceId: anyOf: - type: string - type: 'null' description: CRM source ID (src_ prefix) source: anyOf: - type: string - type: 'null' description: CRM source name ownerUserId: anyOf: - type: string - type: 'null' description: Owner user ID (usr_ prefix) ownerId: anyOf: - type: string - type: 'null' description: Owner user ID (usr_ prefix) ownerName: anyOf: - type: string - type: 'null' description: Owner name contactEmails: type: array items: type: string description: Emails of linked contacts createdAt: anyOf: - type: string format: date-time - type: 'null' description: When the deal was created updatedAt: anyOf: - type: string format: date-time - type: 'null' description: When the deal was last updated required: - id - number - title - contactEmails additionalProperties: description: >- Custom field values as top-level cf_* keys (for example cf_priority). There is no customFields wrapper. V2ApiError: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string details: type: object DealProductInput: type: object properties: name: type: string description: Line item name productId: anyOf: - type: string - type: 'null' description: Product ID quantity: type: number minimum: 0 description: Quantity price: type: number minimum: 0 description: Unit price description: anyOf: - type: string - type: 'null' description: Line item description tax: type: number minimum: 0 description: Tax amount taxRateId: anyOf: - type: string - type: 'null' description: Tax rate ID discount: type: number minimum: 0 description: Discount amount discountType: type: string enum: - fixed - percent description: Discount type required: - name - quantity - price securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key for authentication. Get yours at app.heffl.com/settings/developers ````