generated: '2026-08-04'
method: searched
source: >-
  openapi/clozd-data-api-v3-openapi.yml, openapi/clozd-data-api-v2-openapi.yml,
  https://help.clozd.com/hc/en-us/articles/9948957669659-API-Imports-Exports
applies_to:
- Clozd Data API v1.0
- Clozd Data API v2.0
- Clozd Data API v3.0
authentication:
  style: api-key-header
  header: x-api-token
  scope: organization
  detail: authentication/clozd-authentication.yml
versioning:
  scheme: uri-path
  pattern: https://app.clozd.com/public-api/{version}
  versions:
  - v1
  - v2
  - v3
  current: v3
  concurrent_versions_live: 3
  detail: lifecycle/clozd-lifecycle.yml
pagination:
  style: offset-limit
  params:
  - name: limit
    in: query
    default: 1000
    minimum: 1
    maximum: 1000
  - name: offset
    in: query
    default: 0
    minimum: 0
    maximum: 100000
  response_envelope:
    container: links
    fields:
    - self
    - prev
    - next
    - first
    - last
    counts:
    - count
    - total
  absolute_links: true
  note: >-
    Paging links are absolute URLs including the query string, so a client can follow `next` verbatim. The
    100,000 offset ceiling caps a full walk at 100k records per collection.
filtering:
  style: deepObject
  param: filter
  explode: true
  incremental_sync: true
  fields:
    competitors:
    - competitor_updated_since
    deals:
    - feedback_published_since
    - feedback_updated_since
    - clozd_insight_gems
    touchpoints:
    - feedback_published_since
    - feedback_updated_since
  format: ISO 8601 date-time (max 25 chars)
  note: >-
    Every collection operation supports an *_updated_since filter, which Clozd documents as the mechanism
    for periodic incremental pulls instead of full re-reads. This is the closest thing the API has to a
    change feed; there is no webhook or event stream.
field_expansion:
  style: include
  param: include
  explode: true
  max_items:
    competitors: 2
    deals: 5
    deal: 7
    touchpoints: 5
    touchpoint: 6
  values:
    competitors:
    - deals
    - responses
    deals:
    - customFields
    - products
    - feedback
    - tags
    - surveyQuestions
    deal:
    - customFields
    - participants
    - products
    - feedback
    - transcripts
    - tags
    - surveyQuestions
    touchpoints:
    - customFields
    - feedback
    - tags
    - surveyQuestions
    touchpoint:
    - customFields
    - participants
    - feedback
    - transcripts
    - tags
    - surveyQuestions
  constraints:
  - Cannot include 'responses' without also including 'deals' on the competitors operation.
  - Participants and transcripts are only available on the single-record (deal/touchpoint by id) operations.
  note: >-
    Expansion is how nested feedback is reached — feedback responses, transcripts, participants, products,
    tags, survey questions and custom fields have no standalone collection endpoint and exist only as
    includes on deals, touchpoints and competitors.
idempotency:
  supported: true
  mechanism: natural-key-upsert
  key_field: clozd_external_id
  key_scope: program
  header: null
  documented_at: openapi/clozd-data-api-v3-openapi.yml
  quote: >-
    "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"
  applies_to:
  - post-deals-op
  - post-touchpoints-op
  atomicity: >-
    "If an attribute is required or a wrong value type is provided the POST request will be rolled back and
    rejected" — the import is all-or-nothing per request.
  gaps:
  - No RFC-style Idempotency-Key request header.
  - No replayed-request detection or stored-response semantics; a repeat import re-runs the upsert.
  - Idempotency is a property of the import contract only; there are no other write operations.
metadata:
  supported: true
  mechanism: custom fields
  note: >-
    Arbitrary custom fields are accepted on import. "The key name must match the name of the field name
    created in Clozd app exactly" — custom fields must first exist in the Clozd application. Custom
    metadata is read back via include=metadata on the deal operations.
  quote: >-
    "Custom fields are acceptable. The key name must match the name of the field name created in Clozd app
    exactly."
response_envelope:
  style: wrapped
  success_shape:
    success: boolean
    message: string
    data: object | array
    links: object (collection responses only)
    count: integer (collection responses only)
    total: integer (collection responses only)
  error_shape:
    success: boolean (false)
    message: string
    errorCode: string
    data: object
    errors: array (observed on the MCP surface)
  content_type: application/json
  detail: errors/clozd-problem-types.yml
error_semantics:
  format: proprietary-envelope
  rfc9457: false
  machine_readable_code: errorCode
  http_status_used: true
  detail: errors/clozd-problem-types.yml
request_tracing:
  request_id_header: not-published
  correlation_id: not-published
rate_limiting:
  documented: false
  headers: not-published
  note: >-
    Clozd publishes no rate limit, quota or throttling documentation, and the OpenAPI declares no 429
    response on any operation. The only capacity signals in the contract are the limit<=1000 page size and
    the offset<=100000 walk ceiling.
field_naming:
  convention: snake_case with a clozd_ prefix on every platform-owned field
  examples:
  - clozd_deal_id
  - clozd_external_id
  - clozd_organization_domain
  - clozd_update_date
  note: >-
    The clozd_ prefix namespaces platform fields away from customer custom fields in the same flat object,
    which is why custom field names must match the Clozd app exactly.
identifiers:
  format: uuid
  length: 36
  fields:
  - clozd_program_id
  - clozd_deal_id
  - clozd_touchpoint_id
  - clozd_competitor_id
  - clozd_response_id
  external_ids: clozd_external_id (customer-owned, used as the upsert key)
cross_links:
  authentication: authentication/clozd-authentication.yml
  errors: errors/clozd-problem-types.yml
  lifecycle: lifecycle/clozd-lifecycle.yml
  data_model: data-model/clozd-data-model.yml
  scopes: scopes/clozd-scopes.yml