> ## Documentation Index > Fetch the complete documentation index at: https://docs-vnext.kiflo.com/llms.txt > Use this file to discover all available pages before exploring further. # Create deal > Create a new deal and associate roles on it for existing partners. ## Body parameters | Parameter | Type | Description | |---|---|---| | `contactId` | integer | ID of an existing contact to link to this deal. Mutually exclusive with `contact`. | | `stage` | string | The deal pipeline stage name. Must match an existing stage configured in your Kiflo account (e.g. `New`, `Qualified`, `Closed Won`). | | `closeDate` | string | Expected close date of the deal. ISO 8601 UTC format (e.g. `2025-12-31T00:00:00Z`). | | `properties` | object | Dictionary of custom deal properties defined in your Kiflo account. Keys are the property API names. | | `partners` | array | List of partner roles on the deal. Each entry links a partner with a specific role type. See **partners[]** below. | | `contact` | object | Inline contact to create and associate with the deal. Mutually exclusive with `contactId`. See **contact** below. | | `source` | string | Origin of the deal data. Accepted values: `Unknown`, `Website`, `Partner`, `Api`, `Zapier`, `Tenant`, `System`, `HubSpot`, `Stripe`, `PartnerDirectory`. | | `contractStartDate` | string | Contract start date. ISO 8601 UTC format. | | `contractEndDate` | string | Contract end date. ISO 8601 UTC format. | | `currency` | string | ISO 4217 currency code (e.g. `USD`, `EUR`). | | `sourcePartnerId` | integer | ID of the partner that sourced this deal. Required when `source` is set to `Partner`. | | `status` | string | Initial deal status. Accepted values: `Pending`, `Accepted`, `Refused`, `Expired`. Defaults to `Pending`. | | `ownerUserId` | integer | ID of the internal user to set as deal owner. Leave null to rely on the `assignToPartnerOwner` logic instead. | | `assignToPartnerOwner` | boolean | When `true`, automatically assigns the deal owner from the source partner's owner. Only applied when `ownerUserId` is not set. Defaults to `true`. | ## partners[] | Parameter | Type | Description | |---|---|---| | `partnerId` | integer | **Required.** ID of the partner to associate with the deal. | | `partnerType` | string | The partner role name (e.g. `Reseller`, `Business Introducer`). Must match an existing partner type in your account. | | `userPartnerOwnerId` | integer | ID of the partner's user to set as deal contact on the partner side. Leave null to use the partner's default owner. | ## contact | Parameter | Type | Description | |---|---|---| | `properties` | object | Contact properties. Must include at minimum `firstName`, `lastName`, and `email`. | | `source` | string | Origin of the contact data. Accepted values: `Unknown`, `Website`, `Partner`, `Api`, `Zapier`, `Tenant`, `System`, `HubSpot`, `Stripe`, `PartnerDirectory`. | ## OpenAPI ````yaml /openapi.json post /v3/deals openapi: 3.0.1 info: title: Kiflo Public API v3 description: "The Kiflo API allows you to have control over your integration and create the best experiences.\r\n\r\n***\r\n\r\n## Format\r\n\r\nThe API follows the REST standard using JSON to format requests and responses. \r\nDecimals are formatted using invariant culture, ie: using \".\" (dot) as a decimal sperator and no thousands separator. \r\nDates are formatted using ISO standards, in UTC format, including the timezone. Ex: 2015-03-25T12:00:00Z\r\n\r\n***\r\n\r\n## Security\r\n\r\nThe API is secured using an API token.\r\n\r\n**How to generate an API Access Token** \r\n 1. Open your [account settings page](https://app.kiflo.com/account/integration)\r\n 2. Go to the \"API Access Token\" section\r\n 3. Click \"Add\" button\r\n 4. Choose a name that will be used to identify the token and click \"Add\"\r\n 4. Copy the generate token\r\n \r\n> **Note:** For security reason, the generated API Access Token won't be visible after you close the settings page. Be sure to copy the generated token otherwise you won't be able to get it later.\r\n \r\n**How to authenticate on the API** \r\n \r\nTo authenticate on the API, send the generated token in the Authorization header using the Bearer scheme: \r\n`Authorization: Bearer #YOUR_GENERATED_TOKEN_HERE#`\r\n" version: v3 servers: [] security: [] paths: /v3/deals: post: tags: - Deals summary: Create deal description: "Create a new deal and associate roles on it for existing partners.\r\n \r\n## Body parameters\r\n \r\n| Parameter | Type | Description |\r\n|---|---|---|\r\n| `contactId` | integer | ID of an existing contact to link to this deal. Mutually exclusive with `contact`. |\r\n| `stage` | string | The deal pipeline stage name. Must match an existing stage configured in your Kiflo account (e.g. `New`, `Qualified`, `Closed Won`). |\r\n| `closeDate` | string | Expected close date of the deal. ISO 8601 UTC format (e.g. `2025-12-31T00:00:00Z`). |\r\n| `properties` | object | Dictionary of custom deal properties defined in your Kiflo account. Keys are the property API names. |\r\n| `partners` | array | List of partner roles on the deal. Each entry links a partner with a specific role type. See **partners[]** below. |\r\n| `contact` | object | Inline contact to create and associate with the deal. Mutually exclusive with `contactId`. See **contact** below. |\r\n| `source` | string | Origin of the deal data. Accepted values: `Unknown`, `Website`, `Partner`, `Api`, `Zapier`, `Tenant`, `System`, `HubSpot`, `Stripe`, `PartnerDirectory`. |\r\n| `contractStartDate` | string | Contract start date. ISO 8601 UTC format. |\r\n| `contractEndDate` | string | Contract end date. ISO 8601 UTC format. |\r\n| `currency` | string | ISO 4217 currency code (e.g. `USD`, `EUR`). |\r\n| `sourcePartnerId` | integer | ID of the partner that sourced this deal. Required when `source` is set to `Partner`. |\r\n| `status` | string | Initial deal status. Accepted values: `Pending`, `Accepted`, `Refused`, `Expired`. Defaults to `Pending`. |\r\n| `ownerUserId` | integer | ID of the internal user to set as deal owner. Leave null to rely on the `assignToPartnerOwner` logic instead. |\r\n| `assignToPartnerOwner` | boolean | When `true`, automatically assigns the deal owner from the source partner's owner. Only applied when `ownerUserId` is not set. Defaults to `true`. |\r\n \r\n## partners[]\r\n \r\n| Parameter | Type | Description |\r\n|---|---|---|\r\n| `partnerId` | integer | **Required.** ID of the partner to associate with the deal. |\r\n| `partnerType` | string | The partner role name (e.g. `Reseller`, `Business Introducer`). Must match an existing partner type in your account. |\r\n| `userPartnerOwnerId` | integer | ID of the partner's user to set as deal contact on the partner side. Leave null to use the partner's default owner. |\r\n \r\n## contact\r\n \r\n| Parameter | Type | Description |\r\n|---|---|---|\r\n| `properties` | object | Contact properties. Must include at minimum `firstName`, `lastName`, and `email`. |\r\n| `source` | string | Origin of the contact data. Accepted values: `Unknown`, `Website`, `Partner`, `Api`, `Zapier`, `Tenant`, `System`, `HubSpot`, `Stripe`, `PartnerDirectory`. |" requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/DealCreateRequestDto' example: contactId: null stage: New closeDate: null properties: name: Contoso Deal service_amount: 10000 arr_amount: 1200 partners: - partnerId: 42 partnerType: Reseller userPartnerOwnerId: null - partnerId: 84 partnerType: Business Introducer userPartnerOwnerId: null contact: properties: firstName: John lastName: Doe email: john@doe.com source: Unknown source: null contractStartDate: null contractEndDate: null currency: USD sourcePartnerId: 84 status: null ownerUserId: null assignToPartnerOwner: false application/json: schema: $ref: '#/components/schemas/DealCreateRequestDto' example: contactId: null stage: New closeDate: null properties: name: Contoso Deal service_amount: 10000 arr_amount: 1200 partners: - partnerId: 42 partnerType: Reseller userPartnerOwnerId: null - partnerId: 84 partnerType: Business Introducer userPartnerOwnerId: null contact: properties: firstName: John lastName: Doe email: john@doe.com source: Unknown source: null contractStartDate: null contractEndDate: null currency: USD sourcePartnerId: 84 status: null ownerUserId: null assignToPartnerOwner: false text/json: schema: $ref: '#/components/schemas/DealCreateRequestDto' example: contactId: null stage: New closeDate: null properties: name: Contoso Deal service_amount: 10000 arr_amount: 1200 partners: - partnerId: 42 partnerType: Reseller userPartnerOwnerId: null - partnerId: 84 partnerType: Business Introducer userPartnerOwnerId: null contact: properties: firstName: John lastName: Doe email: john@doe.com source: Unknown source: null contractStartDate: null contractEndDate: null currency: USD sourcePartnerId: 84 status: null ownerUserId: null assignToPartnerOwner: false application/*+json: schema: $ref: '#/components/schemas/DealCreateRequestDto' example: contactId: null stage: New closeDate: null properties: name: Contoso Deal service_amount: 10000 arr_amount: 1200 partners: - partnerId: 42 partnerType: Reseller userPartnerOwnerId: null - partnerId: 84 partnerType: Business Introducer userPartnerOwnerId: null contact: properties: firstName: John lastName: Doe email: john@doe.com source: Unknown source: null contractStartDate: null contractEndDate: null currency: USD sourcePartnerId: 84 status: null ownerUserId: null assignToPartnerOwner: false responses: '200': description: Deal created content: application/json: schema: $ref: '#/components/schemas/DealDto' '400': description: Invalid request security: - oauth2: - Deal.Create - Api components: schemas: DealCreateRequestDto: type: object properties: contactId: type: integer description: ID of an existing contact to link to this deal. format: int32 nullable: true example: 42 stage: type: string description: The deal pipeline stage name. nullable: true example: Qualified closeDate: type: string description: Expected close date of the deal. format: date-time nullable: true example: '2025-12-31T00:00:00Z' properties: type: object additionalProperties: nullable: true description: Dictionary of custom deal properties defined in your Kiflo account. nullable: true example: dealValue: 15000 region: EMEA partners: type: array items: $ref: '#/components/schemas/DealPartnerRoleCreateRequestDto' description: List of partner roles on the deal. nullable: true contact: $ref: '#/components/schemas/ContactCreateRequestDto' source: $ref: '#/components/schemas/DataSource' contractStartDate: type: string description: Contract start date. format: date-time nullable: true example: '2025-01-01T00:00:00Z' contractEndDate: type: string description: Contract end date. format: date-time nullable: true example: '2025-12-31T00:00:00Z' currency: type: string description: ISO 4217 currency code for the deal value. nullable: true example: USD sourcePartnerId: type: integer description: ID of the partner that sourced this deal. format: int32 nullable: true example: 7 status: $ref: '#/components/schemas/DealStatus' ownerUserId: type: integer description: ID of the internal user to set as deal owner. format: int32 nullable: true example: 3 assignToPartnerOwner: type: boolean description: >- When true, automatically assigns the deal owner from the source partner's owner. example: true additionalProperties: false DealDto: type: object properties: id: type: integer format: int32 contactId: type: integer format: int32 sourcePartnerId: type: integer format: int32 nullable: true stage: type: string nullable: true creationDate: type: string format: date-time totalAmount: type: number format: double nullable: true properties: type: object additionalProperties: nullable: true nullable: true sourceLeadId: type: integer format: int32 nullable: true status: $ref: '#/components/schemas/DealStatus' partners: type: array items: $ref: '#/components/schemas/DealPartnerRoleDto' nullable: true contractStartDate: type: string format: date-time nullable: true contractEndDate: type: string format: date-time nullable: true ownerUserId: type: integer format: int32 nullable: true owner: $ref: '#/components/schemas/UserDto' closeDate: type: string format: date-time nullable: true customerId: type: integer format: int32 nullable: true currency: type: string nullable: true additionalProperties: false DealPartnerRoleCreateRequestDto: type: object properties: partnerId: type: integer description: ID of the partner to associate with the deal. format: int32 example: 7 partnerType: type: string description: The partner type/role name on the deal. nullable: true example: Reseller userPartnerOwnerId: type: integer description: >- ID of the partner's user to set as the deal contact on the partner side. format: int32 nullable: true example: 15 additionalProperties: false description: Defines a partner's role on a deal. ContactCreateRequestDto: type: object properties: properties: type: object additionalProperties: nullable: true description: Dictionary of contact properties. nullable: true example: firstName: Jane lastName: Doe email: jane.doe@example.com source: $ref: '#/components/schemas/DataSource' additionalProperties: false description: Inline contact to create and associate with the deal. DataSource: enum: - Unknown - Website - Partner - Api - Zapier - Tenant - System - HubSpot - Stripe - PartnerDirectory type: string DealStatus: enum: - Unknown - Pending - Accepted - Refused - Expired type: string DealPartnerRoleDto: type: object properties: id: type: integer format: int32 dealId: type: integer format: int32 userPartnerOwnerId: type: integer format: int32 nullable: true userPartnerOwnerName: type: string nullable: true userPartnerFirstName: type: string nullable: true userPartnerLastName: type: string nullable: true userPartnerEmail: type: string nullable: true userPartnerJobTitle: type: string nullable: true userPartnerPhoneNumber: type: string nullable: true userPartnerLinkedInProfileUrl: type: string nullable: true partnerId: type: integer format: int32 partnerTypeId: type: integer format: int32 nullable: true creationDate: type: string format: date-time partnerName: type: string nullable: true partnerTypeName: type: string nullable: true additionalProperties: false UserDto: type: object properties: id: type: integer format: int32 email: type: string nullable: true firstName: type: string nullable: true lastName: type: string nullable: true additionalProperties: false ````