openapi: 3.2.0
info:
title: Clozd /programs/:program Id/deals /programs/:program Id/deals API
contact:
email: support@clozd.com
termsOfService: https://www.clozd.com/privacy/terms-of-use
version: '1.0'
description: 'Operations tagged /programs/:program_id/deals across 2 of this provider''s published API definitions: clozd-data-api-v2-openapi.yml, clozd-data-api-v3-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: Clozd API v2.0
url: https://app.clozd.com/public-api/v2
- description: Clozd API v3.0
url: https://app.clozd.com/public-api/v3
tags:
- name: /programs/:program_id/deals
paths:
/programs/{program_id}/deals:
servers:
- description: Clozd API v2.0
url: https://app.clozd.com/public-api/v2
get:
description: "Get a paged list of deals with basic fields and share link for deals with published feedback. See /programs/:program_id/deals/:deal_id endpoint to get a specific deal with details. Make sure the header is set with a key value pair being Key: x-api-token Value: (api token provided from the settings section within the Clozd application).\n - :program_id is required, you can get the program id from the settings page within the Clozd app."
summary: Get list of Clozd program deals
operationId: get-deals-op
security:
- apiKey: []
responses:
'200':
description: Successful get operation
content:
application/json:
schema:
description: Success response
type: object
properties:
success:
description: Success flag
type: boolean
message:
description: Success message
type: string
links:
description: Absolute path links to paged results
type: object
properties:
self:
description: Current page of results
type: string
prev:
description: Previous page of results
type: string
next:
description: Next page of results
type: string
first:
description: First page of results
type: string
last:
description: Last page of results
type: string
count:
description: Number of deals in current page of results
format: int64
type: integer
total:
description: Number of total deals in all pages of results
format: int64
type: integer
data:
description: Parameter without description.
type: array
items:
description: Deal
type: object
properties:
clozd_deal_name:
description: The name of the deal
type: string
clozd_external_id:
description: Your id for this deal. This is not generated by Clozd. If you have existing deals with the same external id, they will be updated with the import
type: string
clozd_organization_domain:
description: 'Deal domain example: www.clozd.com'
type: string
clozd_organization_name:
description: Clozd organization name (max:250 chars)
type: string
clozd_deal_id:
description: Clozd generated deal id (min:36 chars, max:36 chars)
type: string
format: uuid
clozd_share_link:
description: Read-only, absolute path for sharing (unauthenticated) deals with published feedback
type: string
clozd_insight_gems:
description: Insight gems (AWE flags) associated with the deal
type: array
items:
description: Insight gem element
type: object
properties:
type:
description: 'The type of insight gem (AWE flag): at_risk, win_back, or expansion'
enum:
- at_risk
- win_back
- expansion
type: string
created_by_type:
description: 'Provenance of the insight gem: ai (system-generated), clozd_consultant (created by a Clozd consultant), user (created by a customer user), or null when unclassifiable'
enum:
- ai
- clozd_consultant
- user
type: string
reason:
description: The reason the insight gem was applied to the deal
type: string
created_at:
description: When the insight gem was created (max:25 chars, ISO8601 date-time format)
format: date-time
type: string
notification_date:
description: When the assigned owners will be or were notified to act on the insight gem; null when no notification is scheduled (max:25 chars, ISO8601 date-time format)
format: date-time
type: string
example:
success: true
message: Successfully retrieved deal data.
links:
self: https://app.clozd.com/public-api/v2/programs/c0cc3cd8-4566-4ffd-8125-bec22cf06e47/deals/export?limit=2&offset=4
prev: https://app.clozd.com/public-api/v2/programs/c0cc3cd8-4566-4ffd-8125-bec22cf06e47/deals/export?limit=2&offset=2
next: https://app.clozd.com/public-api/v2/programs/c0cc3cd8-4566-4ffd-8125-bec22cf06e47/deals/export?limit=2&offset=6
first: https://app.clozd.com/public-api/v2/programs/c0cc3cd8-4566-4ffd-8125-bec22cf06e47/deals/export?limit=2&offset=0
last: https://app.clozd.com/public-api/v2/programs/c0cc3cd8-4566-4ffd-8125-bec22cf06e47/deals/export?limit=2&offset=12
count: 2
total: 13
data:
- clozd_deal_id: aef18e08-cbc0-4d86-9013-c74564de2960
clozd_external_id: '0000001'
clozd_deal_name: ACME, Inc.
clozd_organization_name: ACME, Inc.
clozd_organization_domain: acme.com
clozd_share_link: https://app.clozd.com/share/deals/aef18e08-cbc0-4d86-9013-c74564de2960
clozd_insight_gems:
- type: at_risk
created_by_type: ai
reason: No buyer engagement in the last 30 days.
created_at: '2026-07-01T12:00:00.000Z'
notification_date: '2026-07-01T12:00:00.000Z'
- clozd_deal_id: 934e1861-d942-41e9-98a2-b07f20af93aa
clozd_external_id: '0000002'
clozd_deal_name: FUNCO, Inc.
clozd_organization_name: FUNCO, Inc.
clozd_organization_domain: funco.com
clozd_insight_gems: []
'400':
description: Failed operation (Bad Request)
content:
application/json:
schema:
description: Bad Request response
type: object
properties:
success:
description: Success flag
type: boolean
message:
description: Error message
type: string
errorCode:
description: Error code
type: string
data:
description: Data
type: object
properties: {}
example:
success: false
message: Bad Request.
errorCode: API009
data: {}
'401':
description: Failed operation (Unauthorized)
content:
application/json:
schema:
description: Unauthorized response
type: object
properties:
success:
description: Success flag
type: boolean
message:
description: Error message
type: string
errorCode:
description: Error code
type: string
data:
description: Data
type: object
properties: {}
example:
success: false
message: Not authorized.
errorCode: AUTH005
data: {}
tags:
- /programs/:program_id/deals
parameters:
- description: Limit for paging (min:1, max:1000)
in: query
name: limit
required: false
schema:
description: Limit for paging (min:1, max:1000)
default: 1000
example: 100
minimum: 1
maximum: 1000
format: int64
type: integer
example: 100
- description: Offset for paging (min:0, max:100000)
in: query
name: offset
required: false
schema:
description: Offset for paging (min:0, max:100000)
default: 0
example: 100
minimum: 0
maximum: 100000
format: int64
type: integer
example: 100
- description: 'Returns only deals with feedback published since the date and time specified. See GET public-api/v2/programs/:program_id/deals/:deal_id response schema, data.clozd_reponses[].clozd_publish_date. NOTE: Specifying this parameter will by definition filter out deals which have no published feedback. It will also enable periodic query of incremental changes since last pull (instead of always having to pull all deals). (max:25 chars, ISO8601 date-time format)'
in: query
name: filter[feedback_published_since]
required: false
schema:
description: 'Returns only deals with feedback published since the date and time specified. See GET public-api/v2/programs/:program_id/deals/:deal_id response schema, data.clozd_reponses[].clozd_publish_date. NOTE: Specifying this parameter will by definition filter out deals which have no published feedback. It will also enable periodic query of incremental changes since last pull (instead of always having to pull all deals). (max:25 chars, ISO8601 date-time format)'
format: date-time
maxLength: 25
type: string
minLength: 16
- description: 'Comma-separated list of insight gem (AWE flag) types to filter by. Returns only deals that have at least one active flag matching any of the specified values. Valid values: at_risk, win_back, expansion. Available on API v3+.'
in: query
name: filter[clozd_insight_gems]
required: false
schema:
description: 'Comma-separated list of insight gem (AWE flag) types to filter by. Returns only deals that have at least one active flag matching any of the specified values. Valid values: at_risk, win_back, expansion. Available on API v3+.'
type: string
example: win_back,expansion
- description: Clozd program ID (min:36 chars, max:36 chars)
in: path
name: program_id
required: true
schema:
description: Clozd program ID (min:36 chars, max:36 chars)
minLength: 36
maxLength: 36
type: string
format: uuid
example: 2427ee0e-fc37-4537-ae83-b648d5a7c7f5
post:
description: "Create or update 1 to many deals and 0 to many participants associated with the deal. Make sure the header is set with a key value pair being Key: x-api-token Value: (api token provided from the settings section within the Clozd application). The body of the post request will follow the schema below. If an attribute is required or a wrong value type is provided the POST request will be rolled back and rejected. \n - Program id is required, you can get the program id from the settings page within the Clozd app. \n - Custom fields are acceptable. The key name must match the name of the field name created in Clozd app exactly. \n - Participants are included within the deal object \n - Names of properties and display names are not always the same"
summary: Create or update Clozd deal and participant data
operationId: post-deals-op
security:
- apiKey: []
responses:
'200':
description: Successful create or update operation
content:
application/json:
schema:
description: Success response
type: object
properties:
success:
description: Success flag
type: boolean
message:
description: Success message
type: string
data:
description: Data
type: object
properties:
result:
description: Result
type: string
example:
success: true
message: Successfully imported deal data.
data:
result: 'Created Deals: 1 Updated Deals: 0'
'400':
description: Failed operation (Bad Request)
content:
application/json:
schema:
description: Bad Request response
type: object
properties:
success:
description: Success flag
type: boolean
message:
description: Error message
type: string
errorCode:
description: Error code
type: string
data:
description: Data
type: object
properties: {}
example:
success: false
message: Bad Request.
errorCode: API009
data: {}
'401':
description: Failed operation (Unauthorized)
content:
application/json:
schema:
description: Unauthorized response
type: object
properties:
success:
description: Success flag
type: boolean
message:
description: Error message
type: string
errorCode:
description: Error code
type: string
data:
description: Data
type: object
properties: {}
example:
success: false
message: Not authorized.
errorCode: AUTH005
data: {}
400-API009:
description: Failed operation (Missing or invalid API parameters)
content:
application/json:
schema:
description: Missing or invalid API parameters response
type: object
properties:
success:
description: Success flag
type: boolean
message:
description: Error message
type: string
errorCode:
description: Error code
type: string
data:
description: Data
type: object
properties:
field:
description: Missing or invalid field namne
type: string
value:
description: Invalid value
type: string
possibleValues:
description: Possible values
type: string
example:
success: false
message: Missing or invalid API parameters.
errorCode: API009
data:
field: clozd_outcome_type
value: win
possibleValues: '"new business win", "new business loss", "renewal", "churn", "expansion", "upsell", "customer experience"'
400-API010:
description: Failed operation (Clozd Id doesn't match)
content:
application/json:
schema:
description: Clozd Id doesn't match response
type: object
properties:
success:
description: Success flag
type: boolean
message:
description: Error message
type: string
errorCode:
description: Error code
type: string
data:
description: Data
type: object
properties:
deal_id:
description: Non-matching Clozd Id
type: string
example:
success: false
message: If a clozd generated id is provided, this indicates you are trying to update an existing record and the id must match an existing id. One of the provided id's does not have any matches.
errorCode: API010
data:
deal_id: a1bb3107-6909-43bd-a669-0ed5c399c783
400-API011:
description: Failed operation (Attribute not a defined field)
content:
application/json:
schema:
description: Attribute not a defined field response
type: object
properties:
success:
description: Success flag
type: boolean
message:
description: Error message
type: string
errorCode:
description: Error code
type: string
data:
description: Data
type: object
properties:
field:
description: Attribute name which is not a field
type: string
example:
success: false
message: One of the attributes on the deal or participant object does not exist as a field, you can add a field in the app under the configurations section.
errorCode: API011
data:
field: clozd_not_a_field
400-API012:
description: Failed operation (Required field missing)
content:
application/json:
schema:
description: Required field missing response
type: object
properties:
success:
description: Success flag
type: boolean
message:
description: Error message
type: string
errorCode:
description: Error code
type: string
data:
description: Data
type: object
properties:
requiredField:
description: Name of missing required field
type: string
example:
success: false
message: One of the fields that is configured as required is missing.
errorCode: API012
data:
requiredField: clozd_amount
tags:
- /programs/:program_id/deals
parameters:
- description: Clozd program ID (min:36 chars, max:36 chars)
in: path
name: program_id
required: true
schema:
description: Clozd program ID (min:36 chars, max:36 chars)
minLength: 36
maxLength: 36
type: string
format: uuid
example: 2427ee0e-fc37-4537-ae83-b648d5a7c7f5
requestBody:
description: Deal data to import to Clozd Platform
content:
application/json:
schema:
description: Deal data to import to Clozd Platform
type: object
properties:
import_name:
description: The name of your import, defaults to 'Clozd Data API' if nothing provided
type: string
all_deals:
description: Array of deal objects for importing (minItems:1, maxItems:1000)
minItems: 1
maxItems: 1000
type: array
items:
$ref: '#/components/schemas/Deal'
example:
import_name: 2022 Deals Import
all_deals:
- clozd_amount: 10000
clozd_closed_date: '2022-01-09T18:57:08.485Z'
clozd_created_date: '2022-03-09T18:57:08.485Z'
clozd_currency: USD
clozd_deal_name: ACME, Inc.
clozd_external_id: '0000001'
clozd_headcount: 12
clozd_industry: SAAS
clozd_lead_source: SDR
clozd_organization_domain: acme.com
clozd_organization_name: ACME, Inc.
clozd_outcome: win
clozd_outcome_type: churn
clozd_products:
- Flagship
clozd_region: East
clozd_revenue: 10000
clozd_sales_rep_email: rep@sales.com
clozd_sales_rep_name: Sales Rep
clozd_participants:
- clozd_participant_external_id: '0000002'
clozd_participant_first_name: First
clozd_participant_last_name: Last
clozd_participant_email: participant@email.com
clozd_participant_type: buyer
clozd_participant_is_primary: true
clozd_participant_phone: 888-111-2222
clozd_participant_title: Chief Buyer
clozd_participant_role: Buying Agent
components:
schemas:
Deal:
description: An array of deal objects
type: object
properties:
clozd_deal_name:
description: The name of the deal
type: string
clozd_external_id:
description: Your id for this deal. This is not generated by Clozd. If you have existing deals with the same external id, they will be updated with the import
type: string
clozd_organization_domain:
description: 'Deal domain example: www.clozd.com'
type: string
clozd_organization_name:
description: Clozd organization name (max:250 chars)
type: string
clozd_deal_id:
description: Clozd generated deal id (min:36 chars, max:36 chars)
type: string
format: uuid
clozd_amount:
description: This reflects how much the deal was for
format: double
type: number
clozd_closed_date:
description: When the deal was closed (max:25 chars, ISO8601 date-time format)
format: date-time
type: string
clozd_created_date:
description: When the deal was created (max:25 chars, ISO8601 date-time format)
format: date-time
type: string
clozd_currency:
description: The type of currency used in this deal
type: string
clozd_headcount:
description: Head count for the deal
format: int64
type: integer
clozd_industry:
description: Industry from a picklist of values in the Clozd app
type: string
clozd_lead_source:
description: Lead source to the deal
type: string
clozd_outcome:
description: Reflects the outcome of the deal allowed values are 'win' or 'loss'
enum:
- win
- loss
type: string
clozd_outcome_type:
description: What type of deal was the outcome affecting
type: string
clozd_region:
description: Region for the deal, must be a value from the picklist in Clozd app
type: string
clozd_revenue:
description: This is the revenue for the deal
format: double
type: number
clozd_sales_rep_email:
description: The email for the sales rep for the deal
format: email
type: string
clozd_sales_rep_name:
description: The name of the sales rep for the deal
type: string
clozd_products:
description: 'An array of products, if there is only one product, an array of one ie: [''product'']'
type: array
items:
description: Parameter without description.
type: string
clozd_participants:
description: List of participants that belong to the deal (maxItems:1000)
maxItems: 1000
type: array
items:
$ref: '#/components/schemas/Participant'
Participant:
description: An array of participant objects included in the deal under the clozd_participants attribute
type: object
properties:
clozd_participant_id:
description: Clozd generated participant id (min:36 chars, max:36 chars)
type: string
format: uuid
clozd_participant_external_id:
description: Your id for this participant. This is not generated by Clozd. If you have existing participants with the same external id, they will be updated with the import
type: string
clozd_participant_first_name:
description: First name of participant
type: string
clozd_participant_last_name:
description: Last name of participant
type: string
clozd_participant_email:
description: The email for the participant of the deal
format: email
type: string
clozd_participant_type:
description: Specifying if the person is a buyer or a sales participant values are 'buyer' or 'sales'
enum:
- buyer
- sales
type: string
clozd_participant_is_primary:
description: Is the participant the primary participant for the deal
type: boolean
clozd_participant_phone:
description: Phone number for the pariticipant
type: string
clozd_participant_title:
description: Job title of the participant
type: string
clozd_participant_role:
description: The role the participant had in the deal
type: string
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-token
x-refined-from:
- clozd-data-api-v2-openapi.yml
- clozd-data-api-v3-openapi.yml