---
openapi: 3.0.1
info:
  title: Vixiees API
  version: v1
  description: Vixiees API - See published documentation for full details.
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Api-Key
      in: header
  schemas:
    MetricComparison:
      type: object
      description: A metric with current value, previous period value, and difference
      properties:
        current:
          type: integer
          example: 10
        previous:
          type: integer
          example: 8
        difference:
          type: integer
          example: 2
    WebhookEventEnvelope:
      type: object
      required:
      - event
      - payload
      - timestamp
      - source
      properties:
        event:
          type: string
          description: Webhook event type
          enum:
          - contact_created
          - contact_updated
          - contact_deleted
          - contact_comment_created
          - document_created
          - whatsapp_received
          - deal_created
          - deal_updated
          - task_completed
          - incoming_call
          - submitted_form_created
        payload:
          "$ref": "#/components/schemas/WebhookPayload"
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp (seconds)
        source:
          type: string
          description: 'Origin of the event that triggered this webhook: api, user,
            automation, or unknown. `unknown` is the common case for webhook- and
            background-job-originated events (e.g. inbound WhatsApp/Twilio/form webhooks,
            Sidekiq jobs), where `Current` resets and no user/automation context is
            available. Not to be confused with Contact#source (payload.contact.source),
            which describes how the contact itself was created (whatsapp, form, import,
            etc.).'
          enum:
          - api
          - user
          - automation
          - unknown
    WebhookPayload:
      oneOf:
      - "$ref": "#/components/schemas/ContactPayload"
      - "$ref": "#/components/schemas/ContactWithMessagePayload"
      - "$ref": "#/components/schemas/ContactWithCommentPayload"
      - "$ref": "#/components/schemas/ContactWithDocumentPayload"
      - "$ref": "#/components/schemas/DealPayload"
      - "$ref": "#/components/schemas/TaskPayload"
      - "$ref": "#/components/schemas/CallPayload"
    ContactPayload:
      type: object
      required:
      - contact
      properties:
        contact:
          "$ref": "#/components/schemas/Contact"
    ContactUpdatedPayload:
      type: object
      required:
      - contact
      properties:
        contact:
          "$ref": "#/components/schemas/Contact"
        action:
          type: string
          enum:
          - flow_step_changed
          description: 'Present only when the update has a known cause. flow_step_changed:
            the contact entered a flow step (a move, or its first step on creation,
            where the previous ids are null).'
        changes:
          type: object
          description: Present only together with action. Maps the fields tied to
            the action to [previous, new]; ids are strings. flow_step_changed contains
            exactly current_flow_step_id and current_playbook_id (the latter may be
            unchanged).
          additionalProperties:
            type: array
            minItems: 2
            maxItems: 2
            items:
              type: string
              nullable: true
    Contact:
      type: object
      properties:
        id:
          type: string
          description: Unique contact identifier
        account_id:
          type: string
          description: Account this contact belongs to
        assignee_id:
          type: string
          nullable: true
          description: ID of the user assigned to this contact
        current_playbook_id:
          type: string
          nullable: true
          description: Current playbook (sales workflow) the contact is in
        current_flow_step_id:
          type: string
          nullable: true
          description: Current stage within the playbook
        current_flow_step_since:
          type: string
          format: date-time
          nullable: true
          description: When contact entered current flow step
        contact_import_id:
          type: string
          nullable: true
          description: ID of the import batch if contact was imported
        title:
          type: string
          nullable: true
          description: Computed full name (first_name + last_name)
        app_url:
          type: string
          nullable: true
          description: Direct URL to view contact in Vixiees app
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        second_last_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
          description: Primary email address
        canonical_email:
          type: string
          nullable: true
          description: Normalized email (lowercase, no aliases)
        phone:
          type: string
          nullable: true
          description: Primary phone number in E.164 format
        phone_country_code:
          type: string
          nullable: true
          description: ISO country code derived from phone number
        invalid_phone:
          type: boolean
          description: True if phone number failed validation
        invalid_email:
          type: boolean
          description: True if email address failed validation
        company_name:
          type: string
          nullable: true
        additional_phones:
          type: array
          items:
            type: string
          description: Secondary phone numbers
        additional_emails:
          type: array
          items:
            type: string
          description: Secondary email addresses
        all_emails:
          type: array
          items:
            type: string
          description: All email addresses (primary + additional)
        all_phones:
          type: array
          items:
            type: string
          description: All phone numbers (primary + additional)
        priority:
          type: integer
          description: Contact priority (1=highest, 5=lowest). Used for task ordering.
        source:
          type: string
          nullable: true
          description: 'How the contact was created: manual, csv, api, call, whatsapp,
            email, crm, web, typeform, calendly, meta_ads, tiktok_ads, bankflip'
        last_message:
          type: string
          nullable: true
          description: Content of the most recent WhatsApp message
        last_message_at:
          type: string
          format: date-time
          nullable: true
          description: When the last WhatsApp message was received
        unread_messages:
          type: integer
          description: Number of unread WhatsApp messages
        answered_at_least_once:
          type: boolean
          description: True if contact has received at least one response
        answered_via_call:
          type: boolean
          description: True if contact was answered via phone call
        answered_via_email:
          type: boolean
          description: True if contact was answered via email
        answered_via_whatsapp:
          type: boolean
          description: True if contact was answered via WhatsApp
        first_answer_time:
          type: integer
          nullable: true
          description: Seconds between contact creation and first response
        first_answered_at:
          type: string
          format: date-time
          nullable: true
          description: When contact received first response
        last_answered_at:
          type: string
          format: date-time
          nullable: true
          description: When contact received most recent response
        whatsapp_transactional_opt_in:
          type: boolean
          description: Consent to receive transactional WhatsApp messages
        email_transactional_opt_in:
          type: boolean
          description: Consent to receive transactional emails
        whatsapp_marketing_opt_in:
          type: boolean
          description: Consent to receive marketing WhatsApp messages
        email_marketing_opt_in:
          type: boolean
          description: Consent to receive marketing emails
        external_reference_id:
          type: string
          nullable: true
          description: ID in external system (CRM, ERP, etc.)
        external_reference_url:
          type: string
          nullable: true
          description: URL to view contact in external system
        bankflip_user_link:
          type: string
          nullable: true
        bankflip_documentation_area_id:
          type: string
          nullable: true
        unattended:
          type: boolean
          description: True if contact has no assignee or pending tasks
        unanswered_email:
          type: boolean
          description: True if contact sent email that has not been replied to
        unanswered_whatsapp:
          type: boolean
          description: True if contact sent WhatsApp that has not been replied to
        unanswered_call:
          type: boolean
          description: True if contact has missed/unreturned calls
        on_task:
          type: boolean
          description: True if contact has an active task assigned
        check_tasks_pending:
          type: boolean
          description: True if contact has unfinished check tasks (checklist items)
        ignored:
          type: boolean
          description: True if contact is marked as ignored/archived
        is_client:
          type: boolean
          description: True if contact has at least one won deal
        remove_requested:
          type: boolean
          description: True if contact requested data removal (GDPR)
        last_close_won_reason:
          type: string
          nullable: true
          description: Reason for most recent won deal
        last_close_lost_reason:
          type: string
          nullable: true
          description: Reason for most recent lost deal
        merged:
          type: boolean
          nullable: true
          description: True if contact was merged into another contact
        merged_at:
          type: string
          format: date-time
          nullable: true
        last_closed_office_message_sent_at:
          type: string
          format: date-time
          nullable: true
        last_assignee_at:
          type: string
          format: date-time
          nullable: true
          description: When contact was last assigned to a user
        last_started_task_at:
          type: string
          format: date-time
          nullable: true
          description: When most recent task was started
        last_completed_task_at:
          type: string
          format: date-time
          nullable: true
          description: When most recent task was completed
        last_successful_call_at:
          type: string
          format: date-time
          nullable: true
          description: When last successful call was made
        last_unsuccessful_call_at:
          type: string
          format: date-time
          nullable: true
          description: When last unsuccessful call attempt was made
        last_email_sent_at:
          type: string
          format: date-time
          nullable: true
        last_email_received_at:
          type: string
          format: date-time
          nullable: true
        last_window_opened_at:
          type: string
          format: date-time
          nullable: true
          description: When WhatsApp 24h window was last opened
        ai_controlling:
          type: boolean
          nullable: true
          description: True if AI is currently managing this contact
        ai_disabled:
          type: boolean
          nullable: true
          description: True if AI is disabled for this contact
        ai_test:
          type: boolean
          nullable: true
          description: True if this is a test contact for AI
        ai_suppressed_until_flow_step_change:
          type: boolean
          nullable: true
        ai_reply_count_in_state:
          type: integer
          nullable: true
        deals_count:
          type: integer
          description: Total number of deals for this contact
        meetings_count:
          type: integer
          description: Total number of meetings scheduled
        pinned_comment_id:
          type: string
          nullable: true
          description: ID of comment pinned to contact profile
        has_skills:
          type: boolean
          nullable: true
        skills:
          type: array
          items:
            type: string
          nullable: true
          description: Skills assigned to contact
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: When contact was soft-deleted
        locale:
          type: string
          nullable: true
          description: Preferred language (ISO 639-1)
        country_code:
          type: string
          nullable: true
          description: Country code (ISO 3166-1 alpha-2)
        utm_source:
          type: string
          nullable: true
          description: UTM source parameter from landing page
        utm_medium:
          type: string
          nullable: true
          description: UTM medium parameter from landing page
        utm_campaign:
          type: string
          nullable: true
          description: UTM campaign parameter from landing page
        utm_term:
          type: string
          nullable: true
        utm_content:
          type: string
          nullable: true
        gclid:
          type: string
          nullable: true
          description: Google Click ID for ad attribution
        fbclid:
          type: string
          nullable: true
          description: Meta Click ID for ad attribution
        landing_page_url:
          type: string
          nullable: true
          description: URL of the page where contact was captured
        landing_page_query:
          type: string
          nullable: true
        leadgen_id:
          type: string
          nullable: true
          description: Meta Lead Generation form ID
        ad_id:
          type: string
          nullable: true
          description: ID of the Meta or TikTok ad the contact came from (see source)
        ad_name:
          type: string
          nullable: true
          description: Name of the Meta or TikTok ad the contact came from
        adgroup_id:
          type: string
          nullable: true
          description: ID of the Meta ad set or TikTok ad group the contact came from
        adgroup_name:
          type: string
          nullable: true
          description: Name of the Meta ad set or TikTok ad group the contact came
            from
        campaign_id:
          type: string
          nullable: true
          description: ID of the TikTok campaign the contact came from
        campaign_name:
          type: string
          nullable: true
          description: Name of the TikTok campaign the contact came from
        tiktok_lead_id:
          type: string
          nullable: true
          description: TikTok lead ID of the Instant Form submission that created
            the contact
        page_id:
          type: string
          nullable: true
          description: Meta page ID
        page_name:
          type: string
          nullable: true
        form_id:
          type: string
          nullable: true
          description: ID of the web form, Meta Lead Ad form or TikTok Instant Form
            that created this contact
        deleted_phone:
          type: string
          nullable: true
        deleted_email:
          type: string
          nullable: true
        deleted_external_reference_id:
          type: string
          nullable: true
        deleted_crm_id:
          type: string
          nullable: true
        sent_imported_email_ids:
          type: array
          items:
            type: string
          nullable: true
        received_imported_email_ids:
          type: array
          items:
            type: string
          nullable: true
        custom_attributes:
          type: array
          items:
            "$ref": "#/components/schemas/CustomAttribute"
          description: Custom fields defined by account
    CustomAttribute:
      type: object
      properties:
        id:
          type: string
        field_name:
          type: string
        humanized_name:
          type: string
        field_type:
          type: string
        editable:
          type: boolean
        value:
          description: Typed value based on field_type
        string_value:
          type: string
          nullable: true
        integer_value:
          type: integer
          nullable: true
        float_value:
          type: number
          nullable: true
        date_value:
          type: string
          format: date-time
          nullable: true
        boolean_value:
          type: boolean
          nullable: true
        array_value:
          type: array
          items:
            type: string
          nullable: true
        nullable:
          type: boolean
    ContactWithMessagePayload:
      type: object
      required:
      - contact
      - message
      properties:
        contact:
          "$ref": "#/components/schemas/Contact"
        message:
          description: Raw WhatsApp message object from Twilio/WhatsApp API
    ContactWithCommentPayload:
      type: object
      required:
      - contact
      - comment
      properties:
        contact:
          "$ref": "#/components/schemas/Contact"
        comment:
          "$ref": "#/components/schemas/Comment"
    ContactWithDocumentPayload:
      type: object
      required:
      - contact
      - document
      properties:
        contact:
          "$ref": "#/components/schemas/Contact"
        document:
          "$ref": "#/components/schemas/Document"
    Comment:
      type: object
      properties:
        id:
          type: string
        created_by_id:
          type: string
          nullable: true
        content:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Document:
      type: object
      properties:
        id:
          type: string
        file_file_name:
          type: string
          nullable: true
        file_file_size:
          type: integer
          nullable: true
        file_content_type:
          type: string
          nullable: true
        file_fingerprint:
          type: string
          nullable: true
        file_updated_at:
          type: string
          format: date-time
          nullable: true
        tag:
          type: string
          nullable: true
        source:
          type: string
          nullable: true
        email_content_id:
          type: string
          nullable: true
        expiring_url:
          type: string
          nullable: true
          description: Temporary download URL (expires in 5 minutes)
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DealPayload:
      type: object
      required:
      - deal
      properties:
        deal:
          "$ref": "#/components/schemas/Deal"
    DealUpdatedPayload:
      type: object
      required:
      - deal
      properties:
        deal:
          "$ref": "#/components/schemas/Deal"
        action:
          type: string
          enum:
          - won
          - lost
          - reopened
          description: 'Present only when the update has a known cause. won, lost,
            reopened: the deal was won, lost or reopened through the dedicated win/lose/reopen
            operation. Status changes made through a generic deal update carry no
            action.'
        changes:
          type: object
          description: Present only together with action. Maps the fields tied to
            the action to [previous, new]. won, lost and reopened contain only status
            (closed, won and close_date are not listed); previous equals new when
            the operation is re-applied to a deal already in that status.
          additionalProperties:
            type: array
            minItems: 2
            maxItems: 2
            items:
              type: string
              nullable: true
    Deal:
      type: object
      properties:
        id:
          type: string
        account_id:
          type: string
        contact_id:
          type: string
        assignee_id:
          type: string
          nullable: true
        closer_id:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        amount:
          type: number
          nullable: true
        close_date:
          type: string
          format: date-time
          nullable: true
        closed:
          type: boolean
        won:
          type: boolean
        status:
          type: string
          nullable: true
        external_reference_id:
          type: string
          nullable: true
        deleted_external_reference_id:
          type: string
          nullable: true
        deleted_crm_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        deleted_at:
          type: string
          format: date-time
          nullable: true
    TaskPayload:
      type: object
      required:
      - task
      properties:
        task:
          "$ref": "#/components/schemas/Task"
    Task:
      type: object
      properties:
        identifier:
          type: string
          nullable: true
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        time_spent:
          type: integer
          nullable: true
        attempts:
          type: integer
          nullable: true
        active_on:
          type: string
          format: date
          nullable: true
        finish_status:
          type: string
          nullable: true
        subject_id:
          type: string
          nullable: true
        assignee_id:
          type: string
          nullable: true
        playbook_id:
          type: string
          nullable: true
        calls:
          type: array
          items:
            type: object
            properties:
              _id:
                type: string
              to:
                type: string
              from:
                type: string
              started_at:
                type: string
                format: date-time
                nullable: true
              completed_at:
                type: string
                format: date-time
                nullable: true
              incoming_call:
                type: boolean
                nullable: true
              duration:
                type: integer
                nullable: true
              response_status:
                type: string
                nullable: true
              status:
                type: string
                nullable: true
              user_id:
                type: string
                nullable: true
        subject:
          type: object
          properties:
            _id:
              type: string
            external_reference_id:
              type: string
              nullable: true
    CallPayload:
      type: object
      required:
      - from
      - to
      properties:
        from:
          type: string
        to:
          type: string
        forwarded_from:
          type: string
          nullable: true
    SubmittedFormResponse:
      type: object
      description: A single answered field of a submitted form
      properties:
        id:
          type: string
          description: Unique identifier of this response
        label:
          type: string
          nullable: true
          description: Human-readable label of the form field
        input_id:
          type: string
          nullable: true
          description: Identifier of the field on the source form
        field_string_value:
          type: string
          nullable: true
        field_number_value:
          type: integer
          nullable: true
        field_float_value:
          type: number
          nullable: true
        field_date_value:
          type: string
          format: date
          nullable: true
        field_date_time_value:
          type: string
          format: date-time
          nullable: true
        field_time_value:
          type: string
          format: date-time
          nullable: true
        field_boolean_value:
          type: boolean
          nullable: true
        field_string_values:
          type: array
          items:
            type: string
          nullable: true
          description: Populated when the field allows multiple values (e.g., checkboxes)
    SubmittedForm:
      type: object
      properties:
        id:
          type: string
          description: Unique submitted form identifier
        account_id:
          type: string
          description: Account this submitted form belongs to
        contact_id:
          type: string
          nullable: true
          description: Contact created or matched from this form submission
        form_id:
          type: string
          nullable: true
          description: ID of the source form (Typeform, Meta Lead Ad, TikTok Instant
            Form, or web form)
        form_name:
          type: string
          nullable: true
        source:
          type: string
          nullable: true
          description: Where the form was submitted from
          enum:
          - web
          - meta
          - typeform
          - tiktok
        field_errors:
          type: array
          items:
            type: string
          description: Validation or mapping errors encountered while processing this
            submission
        typeform_response:
          type: object
          nullable: true
          description: Raw Typeform webhook payload, documented as-is (not sanitized)
        meta_response:
          type: object
          nullable: true
          description: Raw Meta Lead Ads API response, documented as-is (not sanitized)
        meta_webhook_change:
          type: object
          nullable: true
          description: Raw Meta webhook change payload, documented as-is (not sanitized)
        web_response:
          type: object
          nullable: true
          description: Raw web form submission payload, documented as-is (not sanitized)
        tiktok_response:
          type: object
          nullable: true
          description: 'Raw TikTok lead webhook entry: answers in changes, plus the
            lead, campaign, ad group and ad IDs and names. Documented as-is (not sanitized)'
        meta_leadgen_id:
          type: string
          nullable: true
          description: Meta Lead Generation form ID
        meta_page_id:
          type: string
          nullable: true
          description: Facebook/Meta page ID
        meta_page_name:
          type: string
          nullable: true
        meta_ad_id:
          type: string
          nullable: true
          description: Facebook/Meta ad ID
        meta_ad_name:
          type: string
          nullable: true
        meta_adgroup_id:
          type: string
          nullable: true
        meta_adgroup_name:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        responses:
          type: array
          items:
            "$ref": "#/components/schemas/SubmittedFormResponse"
    SubmittedFormPayload:
      type: object
      required:
      - submitted_form
      properties:
        submitted_form:
          "$ref": "#/components/schemas/SubmittedForm"
    WebhookEnvelopeContactCreated:
      type: object
      required:
      - event
      - payload
      - timestamp
      - source
      properties:
        event:
          type: string
          enum:
          - contact_created
        payload:
          "$ref": "#/components/schemas/ContactPayload"
        timestamp:
          type: integer
          format: int64
        source:
          type: string
          enum:
          - api
          - user
          - automation
          - unknown
      example:
        event: contact_created
        source: unknown
        payload:
          contact:
            id: 507f1f77bcf86cd799439011
            account_id: 507f191e810c19729de860ea
            assignee_id: 507f191e810c19729de860eb
            current_playbook_id: 507f191e810c19729de860ec
            current_flow_step_id: 507f191e810c19729de860ed
            current_flow_step_since: '2024-08-15T14:30:00Z'
            contact_import_id:
            title: John Smith
            app_url: https://app.vixiees.com/contacts/507f1f77bcf86cd799439011
            first_name: John
            last_name: Smith
            second_last_name:
            email: john.smith@example.com
            canonical_email: john.smith@example.com
            phone: "+1234567890"
            phone_country_code: US
            invalid_phone: false
            invalid_email: false
            company_name: Acme Corp
            additional_phones:
            - "+1234567891"
            additional_emails:
            - j.smith@example.com
            all_emails:
            - john.smith@example.com
            - j.smith@example.com
            all_phones:
            - "+1234567890"
            - "+1234567891"
            priority: 1
            source: whatsapp
            last_message: Hello, I need help with...
            last_message_at: '2024-08-18T10:45:00Z'
            unread_messages: 0
            answered_at_least_once: true
            answered_via_call: false
            answered_via_email: false
            answered_via_whatsapp: true
            first_answer_time: 120
            first_answered_at: '2024-08-15T14:32:00Z'
            last_answered_at: '2024-08-18T10:50:00Z'
            whatsapp_transactional_opt_in: true
            email_transactional_opt_in: true
            whatsapp_marketing_opt_in: false
            email_marketing_opt_in: false
            external_reference_id: CRM-12345
            external_reference_url: https://crm.example.com/contacts/12345
            bankflip_user_link:
            bankflip_documentation_area_id:
            unattended: false
            unanswered_email: false
            unanswered_whatsapp: false
            unanswered_call: false
            on_task: true
            check_tasks_pending: false
            ignored: false
            is_client: false
            remove_requested: false
            last_close_won_reason:
            last_close_lost_reason:
            merged: false
            merged_at:
            last_closed_office_message_sent_at:
            last_assignee_at: '2024-08-15T14:30:00Z'
            last_started_task_at: '2024-08-18T09:00:00Z'
            last_completed_task_at:
            last_successful_call_at:
            last_unsuccessful_call_at:
            last_email_sent_at:
            last_email_received_at:
            last_window_opened_at: '2024-08-18T11:00:00Z'
            ai_controlling: false
            ai_disabled: false
            ai_test: false
            ai_suppressed_until_flow_step_change: false
            ai_reply_count_in_state: 0
            deals_count: 2
            meetings_count: 1
            pinned_comment_id:
            has_skills: false
            skills: []
            created_at: '2024-08-15T14:30:00Z'
            updated_at: '2024-08-18T11:00:00Z'
            deleted_at:
            locale: en
            country_code: US
            utm_source: google
            utm_medium: cpc
            utm_campaign: summer_2024
            utm_term:
            utm_content:
            gclid: Cj0KCQjw...
            landing_page_url: https://example.com/landing
            landing_page_query: "?ref=google"
            leadgen_id:
            ad_id:
            ad_name:
            adgroup_id:
            adgroup_name:
            page_id:
            page_name:
            form_id:
            deleted_phone:
            deleted_email:
            deleted_external_reference_id:
            deleted_crm_id:
            sent_imported_email_ids: []
            received_imported_email_ids: []
            custom_attributes:
            - id: 507f1f77bcf86cd799439012
              field_name: budget
              humanized_name: Budget
              field_type: integer
              editable: true
              value: 50000
              string_value:
              integer_value: 50000
              float_value:
              date_value:
              boolean_value:
              array_value:
              nullable: false
        timestamp: 1724000000
    WebhookEnvelopeContactUpdated:
      type: object
      required:
      - event
      - payload
      - timestamp
      - source
      properties:
        event:
          type: string
          enum:
          - contact_updated
        payload:
          "$ref": "#/components/schemas/ContactUpdatedPayload"
        timestamp:
          type: integer
          format: int64
        source:
          type: string
          enum:
          - api
          - user
          - automation
          - unknown
      example:
        event: contact_updated
        source: user
        payload:
          contact:
            id: 507f1f77bcf86cd799439011
            account_id: 507f191e810c19729de860ea
            assignee_id: 507f191e810c19729de860eb
            current_playbook_id: 507f191e810c19729de860ec
            current_flow_step_id: 507f191e810c19729de860ed
            current_flow_step_since: '2024-08-19T15:22:00Z'
            contact_import_id:
            title: John Smith
            app_url: https://app.vixiees.com/contacts/507f1f77bcf86cd799439011
            first_name: John
            last_name: Smith
            second_last_name:
            email: john.smith@example.com
            canonical_email: john.smith@example.com
            phone: "+1234567890"
            phone_country_code: US
            invalid_phone: false
            invalid_email: false
            company_name: Acme Corp
            additional_phones: []
            additional_emails: []
            all_emails:
            - john.smith@example.com
            all_phones:
            - "+1234567890"
            priority: 2
            source: whatsapp
            last_message: Hello, I need help with...
            last_message_at: '2024-08-18T10:45:00Z'
            unread_messages: 0
            answered_at_least_once: true
            answered_via_call: false
            answered_via_email: false
            answered_via_whatsapp: true
            first_answer_time: 120
            first_answered_at: '2024-08-15T14:32:00Z'
            last_answered_at: '2024-08-19T15:10:00Z'
            whatsapp_transactional_opt_in: true
            email_transactional_opt_in: true
            whatsapp_marketing_opt_in: false
            email_marketing_opt_in: false
            external_reference_id: CRM-12345
            external_reference_url: https://crm.example.com/contacts/12345
            bankflip_user_link:
            bankflip_documentation_area_id:
            unattended: false
            unanswered_email: false
            unanswered_whatsapp: false
            unanswered_call: false
            on_task: false
            check_tasks_pending: false
            ignored: false
            is_client: true
            remove_requested: false
            last_close_won_reason:
            last_close_lost_reason:
            merged: false
            merged_at:
            last_closed_office_message_sent_at:
            last_assignee_at: '2024-08-15T14:30:00Z'
            last_started_task_at: '2024-08-18T09:00:00Z'
            last_completed_task_at: '2024-08-19T15:15:00Z'
            last_successful_call_at: '2024-08-19T15:00:00Z'
            last_unsuccessful_call_at:
            last_email_sent_at:
            last_email_received_at:
            last_window_opened_at: '2024-08-19T15:20:00Z'
            ai_controlling: false
            ai_disabled: false
            ai_test: false
            ai_suppressed_until_flow_step_change: false
            ai_reply_count_in_state: 0
            deals_count: 3
            meetings_count: 1
            pinned_comment_id:
            has_skills: false
            skills: []
            created_at: '2024-08-15T14:30:00Z'
            updated_at: '2024-08-19T15:22:00Z'
            deleted_at:
            locale: en
            country_code: US
            utm_source: google
            utm_medium: cpc
            utm_campaign: summer_2024
            utm_term:
            utm_content:
            gclid: Cj0KCQjw...
            landing_page_url: https://example.com/landing
            landing_page_query: "?ref=google"
            leadgen_id:
            ad_id:
            ad_name:
            adgroup_id:
            adgroup_name:
            page_id:
            page_name:
            form_id:
            deleted_phone:
            deleted_email:
            deleted_external_reference_id:
            deleted_crm_id:
            sent_imported_email_ids: []
            received_imported_email_ids: []
            custom_attributes:
            - id: 507f1f77bcf86cd799439012
              field_name: budget
              humanized_name: Budget
              field_type: integer
              editable: true
              value: 50000
              string_value:
              integer_value: 50000
              float_value:
              date_value:
              boolean_value:
              array_value:
              nullable: false
          action: flow_step_changed
          changes:
            current_flow_step_id:
            - 507f191e810c19729de860ee
            - 507f191e810c19729de860ed
            current_playbook_id:
            - 507f191e810c19729de860ec
            - 507f191e810c19729de860ec
        timestamp: 1724100000
    WebhookEnvelopeContactDeleted:
      type: object
      required:
      - event
      - payload
      - timestamp
      - source
      properties:
        event:
          type: string
          enum:
          - contact_deleted
        payload:
          "$ref": "#/components/schemas/ContactPayload"
        timestamp:
          type: integer
          format: int64
        source:
          type: string
          enum:
          - api
          - user
          - automation
          - unknown
      example:
        event: contact_deleted
        source: user
        payload:
          contact:
            id: 507f1f77bcf86cd799439011
            account_id: 507f191e810c19729de860ea
            assignee_id: 507f191e810c19729de860eb
            current_playbook_id:
            current_flow_step_id:
            current_flow_step_since: '2024-08-15T14:30:00Z'
            contact_import_id:
            title: John Smith
            app_url: https://app.vixiees.com/contacts/507f1f77bcf86cd799439011
            first_name: John
            last_name: Smith
            second_last_name:
            email:
            canonical_email:
            phone:
            phone_country_code: US
            invalid_phone: false
            invalid_email: false
            company_name: Acme Corp
            additional_phones:
            - "+1234567891"
            additional_emails:
            - j.smith@example.com
            all_emails:
            - j.smith@example.com
            all_phones:
            - "+1234567891"
            priority: 1
            source: whatsapp
            last_message: Hello, I need help with...
            last_message_at: '2024-08-18T10:45:00Z'
            unread_messages: 0
            answered_at_least_once: true
            answered_via_call: false
            answered_via_email: false
            answered_via_whatsapp: true
            first_answer_time: 120
            first_answered_at: '2024-08-15T14:32:00Z'
            last_answered_at: '2024-08-18T10:50:00Z'
            whatsapp_transactional_opt_in: true
            email_transactional_opt_in: true
            whatsapp_marketing_opt_in: false
            email_marketing_opt_in: false
            external_reference_id:
            external_reference_url: https://crm.example.com/contacts/12345
            bankflip_user_link:
            bankflip_documentation_area_id:
            unattended: false
            unanswered_email: false
            unanswered_whatsapp: false
            unanswered_call: false
            on_task: false
            check_tasks_pending: false
            ignored: true
            is_client: false
            remove_requested: false
            last_close_won_reason:
            last_close_lost_reason:
            merged: false
            merged_at:
            last_closed_office_message_sent_at:
            last_assignee_at: '2024-08-15T14:30:00Z'
            last_started_task_at: '2024-08-18T09:00:00Z'
            last_completed_task_at:
            last_successful_call_at:
            last_unsuccessful_call_at:
            last_email_sent_at:
            last_email_received_at:
            last_window_opened_at: '2024-08-18T11:00:00Z'
            ai_controlling: false
            ai_disabled: false
            ai_test: false
            ai_suppressed_until_flow_step_change: false
            ai_reply_count_in_state: 0
            deals_count: 2
            meetings_count: 1
            pinned_comment_id:
            has_skills: false
            skills: []
            created_at: '2024-08-15T14:30:00Z'
            updated_at: '2024-08-20T10:00:00Z'
            deleted_at: '2024-08-20T10:00:00Z'
            locale: en
            country_code: US
            utm_source: google
            utm_medium: cpc
            utm_campaign: summer_2024
            utm_term:
            utm_content:
            gclid: Cj0KCQjw...
            landing_page_url: https://example.com/landing
            landing_page_query: "?ref=google"
            leadgen_id:
            ad_id:
            ad_name:
            adgroup_id:
            adgroup_name:
            page_id:
            page_name:
            form_id:
            deleted_phone: "+1234567890"
            deleted_email: john.smith@example.com
            deleted_external_reference_id: CRM-12345
            deleted_crm_id:
            sent_imported_email_ids: []
            received_imported_email_ids: []
            custom_attributes:
            - id: 507f1f77bcf86cd799439012
              field_name: budget
              humanized_name: Budget
              field_type: integer
              editable: true
              value: 50000
              string_value:
              integer_value: 50000
              float_value:
              date_value:
              boolean_value:
              array_value:
              nullable: false
        timestamp: 1724150000
    WebhookEnvelopeContactCommentCreated:
      type: object
      required:
      - event
      - payload
      - timestamp
      - source
      properties:
        event:
          type: string
          enum:
          - contact_comment_created
        payload:
          "$ref": "#/components/schemas/ContactWithCommentPayload"
        timestamp:
          type: integer
          format: int64
        source:
          type: string
          enum:
          - api
          - user
          - automation
          - unknown
      example:
        event: contact_comment_created
        source: user
        payload:
          contact:
            id: 507f1f77bcf86cd799439011
            account_id: 507f191e810c19729de860ea
            assignee_id: 507f191e810c19729de860eb
            current_playbook_id: 507f191e810c19729de860ec
            current_flow_step_id: 507f191e810c19729de860ed
            current_flow_step_since: '2024-08-15T14:30:00Z'
            contact_import_id:
            title: John Smith
            app_url: https://app.vixiees.com/contacts/507f1f77bcf86cd799439011
            first_name: John
            last_name: Smith
            second_last_name:
            email: john.smith@example.com
            canonical_email: john.smith@example.com
            phone: "+1234567890"
            phone_country_code: US
            invalid_phone: false
            invalid_email: false
            company_name: Acme Corp
            additional_phones:
            - "+1234567891"
            additional_emails:
            - j.smith@example.com
            all_emails:
            - john.smith@example.com
            - j.smith@example.com
            all_phones:
            - "+1234567890"
            - "+1234567891"
            priority: 1
            source: whatsapp
            last_message: Hello, I need help with...
            last_message_at: '2024-08-18T10:45:00Z'
            unread_messages: 0
            answered_at_least_once: true
            answered_via_call: false
            answered_via_email: false
            answered_via_whatsapp: true
            first_answer_time: 120
            first_answered_at: '2024-08-15T14:32:00Z'
            last_answered_at: '2024-08-18T10:50:00Z'
            whatsapp_transactional_opt_in: true
            email_transactional_opt_in: true
            whatsapp_marketing_opt_in: false
            email_marketing_opt_in: false
            external_reference_id: CRM-12345
            external_reference_url: https://crm.example.com/contacts/12345
            bankflip_user_link:
            bankflip_documentation_area_id:
            unattended: false
            unanswered_email: false
            unanswered_whatsapp: false
            unanswered_call: false
            on_task: true
            check_tasks_pending: false
            ignored: false
            is_client: false
            remove_requested: false
            last_close_won_reason:
            last_close_lost_reason:
            merged: false
            merged_at:
            last_closed_office_message_sent_at:
            last_assignee_at: '2024-08-15T14:30:00Z'
            last_started_task_at: '2024-08-18T09:00:00Z'
            last_completed_task_at:
            last_successful_call_at:
            last_unsuccessful_call_at:
            last_email_sent_at:
            last_email_received_at:
            last_window_opened_at: '2024-08-18T11:00:00Z'
            ai_controlling: false
            ai_disabled: false
            ai_test: false
            ai_suppressed_until_flow_step_change: false
            ai_reply_count_in_state: 0
            deals_count: 2
            meetings_count: 1
            pinned_comment_id: 507f1f77bcf86cd799439022
            has_skills: false
            skills: []
            created_at: '2024-08-15T14:30:00Z'
            updated_at: '2024-08-19T16:30:00Z'
            deleted_at:
            locale: en
            country_code: US
            utm_source: google
            utm_medium: cpc
            utm_campaign: summer_2024
            utm_term:
            utm_content:
            gclid: Cj0KCQjw...
            landing_page_url: https://example.com/landing
            landing_page_query: "?ref=google"
            leadgen_id:
            ad_id:
            ad_name:
            adgroup_id:
            adgroup_name:
            page_id:
            page_name:
            form_id:
            deleted_phone:
            deleted_email:
            deleted_external_reference_id:
            deleted_crm_id:
            sent_imported_email_ids: []
            received_imported_email_ids: []
            custom_attributes:
            - id: 507f1f77bcf86cd799439012
              field_name: budget
              humanized_name: Budget
              field_type: integer
              editable: true
              value: 50000
              string_value:
              integer_value: 50000
              float_value:
              date_value:
              boolean_value:
              array_value:
              nullable: false
          comment:
            id: 507f1f77bcf86cd799439022
            created_by_id: 507f191e810c19729de860eb
            content: Client requested a follow-up call next week
            created_at: '2024-08-19T16:30:00Z'
            updated_at: '2024-08-19T16:30:00Z'
        timestamp: 1724180000
    WebhookEnvelopeDocumentCreated:
      type: object
      required:
      - event
      - payload
      - timestamp
      - source
      properties:
        event:
          type: string
          enum:
          - document_created
        payload:
          "$ref": "#/components/schemas/ContactWithDocumentPayload"
        timestamp:
          type: integer
          format: int64
        source:
          type: string
          enum:
          - api
          - user
          - automation
          - unknown
      example:
        event: document_created
        source: unknown
        payload:
          contact:
            id: 507f1f77bcf86cd799439011
            account_id: 507f191e810c19729de860ea
            assignee_id: 507f191e810c19729de860eb
            current_playbook_id: 507f191e810c19729de860ec
            current_flow_step_id: 507f191e810c19729de860ed
            current_flow_step_since: '2024-08-15T14:30:00Z'
            contact_import_id:
            title: John Smith
            app_url: https://app.vixiees.com/contacts/507f1f77bcf86cd799439011
            first_name: John
            last_name: Smith
            second_last_name:
            email: john.smith@example.com
            canonical_email: john.smith@example.com
            phone: "+1234567890"
            phone_country_code: US
            invalid_phone: false
            invalid_email: false
            company_name: Acme Corp
            additional_phones:
            - "+1234567891"
            additional_emails:
            - j.smith@example.com
            all_emails:
            - john.smith@example.com
            - j.smith@example.com
            all_phones:
            - "+1234567890"
            - "+1234567891"
            priority: 1
            source: whatsapp
            last_message: Hello, I need help with...
            last_message_at: '2024-08-18T10:45:00Z'
            unread_messages: 0
            answered_at_least_once: true
            answered_via_call: false
            answered_via_email: false
            answered_via_whatsapp: true
            first_answer_time: 120
            first_answered_at: '2024-08-15T14:32:00Z'
            last_answered_at: '2024-08-18T10:50:00Z'
            whatsapp_transactional_opt_in: true
            email_transactional_opt_in: true
            whatsapp_marketing_opt_in: false
            email_marketing_opt_in: false
            external_reference_id: CRM-12345
            external_reference_url: https://crm.example.com/contacts/12345
            bankflip_user_link:
            bankflip_documentation_area_id:
            unattended: false
            unanswered_email: false
            unanswered_whatsapp: false
            unanswered_call: false
            on_task: true
            check_tasks_pending: false
            ignored: false
            is_client: false
            remove_requested: false
            last_close_won_reason:
            last_close_lost_reason:
            merged: false
            merged_at:
            last_closed_office_message_sent_at:
            last_assignee_at: '2024-08-15T14:30:00Z'
            last_started_task_at: '2024-08-18T09:00:00Z'
            last_completed_task_at:
            last_successful_call_at:
            last_unsuccessful_call_at:
            last_email_sent_at:
            last_email_received_at:
            last_window_opened_at: '2024-08-18T11:00:00Z'
            ai_controlling: false
            ai_disabled: false
            ai_test: false
            ai_suppressed_until_flow_step_change: false
            ai_reply_count_in_state: 0
            deals_count: 2
            meetings_count: 1
            pinned_comment_id:
            has_skills: false
            skills: []
            created_at: '2024-08-15T14:30:00Z'
            updated_at: '2024-08-19T17:00:00Z'
            deleted_at:
            locale: en
            country_code: US
            utm_source: google
            utm_medium: cpc
            utm_campaign: summer_2024
            utm_term:
            utm_content:
            gclid: Cj0KCQjw...
            landing_page_url: https://example.com/landing
            landing_page_query: "?ref=google"
            leadgen_id:
            ad_id:
            ad_name:
            adgroup_id:
            adgroup_name:
            page_id:
            page_name:
            form_id:
            deleted_phone:
            deleted_email:
            deleted_external_reference_id:
            deleted_crm_id:
            sent_imported_email_ids: []
            received_imported_email_ids: []
            custom_attributes:
            - id: 507f1f77bcf86cd799439012
              field_name: budget
              humanized_name: Budget
              field_type: integer
              editable: true
              value: 50000
              string_value:
              integer_value: 50000
              float_value:
              date_value:
              boolean_value:
              array_value:
              nullable: false
          document:
            id: 507f1f77bcf86cd799439033
            file_file_name: contract.pdf
            file_file_size: 245678
            file_content_type: application/pdf
            file_fingerprint: abc123def456
            file_updated_at: '2024-08-19T17:00:00Z'
            tag: contract
            source: whatsapp
            email_content_id:
            expiring_url: https://cdn.vixiees.com/documents/contract.pdf?expires=1724182000&signature=xyz
            created_at: '2024-08-19T17:00:00Z'
            updated_at: '2024-08-19T17:00:00Z'
        timestamp: 1724182000
    WebhookEnvelopeWhatsappReceived:
      type: object
      required:
      - event
      - payload
      - timestamp
      - source
      properties:
        event:
          type: string
          enum:
          - whatsapp_received
        payload:
          "$ref": "#/components/schemas/ContactWithMessagePayload"
        timestamp:
          type: integer
          format: int64
        source:
          type: string
          enum:
          - api
          - user
          - automation
          - unknown
      example:
        event: whatsapp_received
        source: unknown
        payload:
          contact:
            id: 507f1f77bcf86cd799439011
            account_id: 507f191e810c19729de860ea
            assignee_id: 507f191e810c19729de860eb
            current_playbook_id: 507f191e810c19729de860ec
            current_flow_step_id: 507f191e810c19729de860ed
            current_flow_step_since: '2024-08-15T14:30:00Z'
            contact_import_id:
            title: John Smith
            app_url: https://app.vixiees.com/contacts/507f1f77bcf86cd799439011
            first_name: John
            last_name: Smith
            second_last_name:
            email: john.smith@example.com
            canonical_email: john.smith@example.com
            phone: "+1234567890"
            phone_country_code: US
            invalid_phone: false
            invalid_email: false
            company_name: Acme Corp
            additional_phones:
            - "+1234567891"
            additional_emails:
            - j.smith@example.com
            all_emails:
            - john.smith@example.com
            - j.smith@example.com
            all_phones:
            - "+1234567890"
            - "+1234567891"
            priority: 1
            source: whatsapp
            last_message: Hello, I have a question about your services
            last_message_at: '2024-08-19T17:20:00Z'
            unread_messages: 1
            answered_at_least_once: true
            answered_via_call: false
            answered_via_email: false
            answered_via_whatsapp: true
            first_answer_time: 120
            first_answered_at: '2024-08-15T14:32:00Z'
            last_answered_at: '2024-08-18T10:50:00Z'
            whatsapp_transactional_opt_in: true
            email_transactional_opt_in: true
            whatsapp_marketing_opt_in: false
            email_marketing_opt_in: false
            external_reference_id: CRM-12345
            external_reference_url: https://crm.example.com/contacts/12345
            bankflip_user_link:
            bankflip_documentation_area_id:
            unattended: false
            unanswered_email: false
            unanswered_whatsapp: true
            unanswered_call: false
            on_task: true
            check_tasks_pending: false
            ignored: false
            is_client: false
            remove_requested: false
            last_close_won_reason:
            last_close_lost_reason:
            merged: false
            merged_at:
            last_closed_office_message_sent_at:
            last_assignee_at: '2024-08-15T14:30:00Z'
            last_started_task_at: '2024-08-18T09:00:00Z'
            last_completed_task_at:
            last_successful_call_at:
            last_unsuccessful_call_at:
            last_email_sent_at:
            last_email_received_at:
            last_window_opened_at: '2024-08-19T17:20:00Z'
            ai_controlling: false
            ai_disabled: false
            ai_test: false
            ai_suppressed_until_flow_step_change: false
            ai_reply_count_in_state: 0
            deals_count: 2
            meetings_count: 1
            pinned_comment_id:
            has_skills: false
            skills: []
            created_at: '2024-08-15T14:30:00Z'
            updated_at: '2024-08-19T17:20:00Z'
            deleted_at:
            locale: en
            country_code: US
            utm_source: google
            utm_medium: cpc
            utm_campaign: summer_2024
            utm_term:
            utm_content:
            gclid: Cj0KCQjw...
            landing_page_url: https://example.com/landing
            landing_page_query: "?ref=google"
            leadgen_id:
            ad_id:
            ad_name:
            adgroup_id:
            adgroup_name:
            page_id:
            page_name:
            form_id:
            deleted_phone:
            deleted_email:
            deleted_external_reference_id:
            deleted_crm_id:
            sent_imported_email_ids: []
            received_imported_email_ids: []
            custom_attributes:
            - id: 507f1f77bcf86cd799439012
              field_name: budget
              humanized_name: Budget
              field_type: integer
              editable: true
              value: 50000
              string_value:
              integer_value: 50000
              float_value:
              date_value:
              boolean_value:
              array_value:
              nullable: false
          message:
            from: '1234567890'
            id: wamid.HBgNMTIzNDU2Nzg5MAAKMD==
            timestamp: '1724185200'
            type: text
            text:
              body: Hello, I have a question about your services
        timestamp: 1724185200
    WebhookEnvelopeDealCreated:
      type: object
      required:
      - event
      - payload
      - timestamp
      - source
      properties:
        event:
          type: string
          enum:
          - deal_created
        payload:
          "$ref": "#/components/schemas/DealPayload"
        timestamp:
          type: integer
          format: int64
        source:
          type: string
          enum:
          - api
          - user
          - automation
          - unknown
      example:
        event: deal_created
        source: api
        payload:
          deal:
            id: 507f1f77bcf86cd799439044
            account_id: 507f191e810c19729de860ea
            contact_id: 507f1f77bcf86cd799439011
            assignee_id: 507f191e810c19729de860eb
            closer_id:
            title: Q3 Enterprise License
            description: Annual enterprise software license renewal
            amount: 150000.5
            close_date:
            closed: false
            won: false
            status: open
            external_reference_id: DEAL-2024-089
            deleted_external_reference_id:
            deleted_crm_id:
            created_at: '2024-08-01T10:00:00Z'
            updated_at: '2024-08-01T10:00:00Z'
            deleted_at:
        timestamp: 1722506400
    WebhookEnvelopeDealUpdated:
      type: object
      required:
      - event
      - payload
      - timestamp
      - source
      properties:
        event:
          type: string
          enum:
          - deal_updated
        payload:
          "$ref": "#/components/schemas/DealUpdatedPayload"
        timestamp:
          type: integer
          format: int64
        source:
          type: string
          enum:
          - api
          - user
          - automation
          - unknown
      example:
        event: deal_updated
        source: user
        payload:
          deal:
            id: 507f1f77bcf86cd799439044
            account_id: 507f191e810c19729de860ea
            contact_id: 507f1f77bcf86cd799439011
            assignee_id: 507f191e810c19729de860eb
            closer_id:
            title: Q3 Enterprise License
            description: Annual enterprise software license renewal
            amount: 150000.5
            close_date:
            closed: false
            won: false
            status: open
            external_reference_id: DEAL-2024-089
            deleted_external_reference_id:
            deleted_crm_id:
            created_at: '2024-08-01T10:00:00Z'
            updated_at: '2024-08-19T18:30:00Z'
            deleted_at:
          action: reopened
          changes:
            status:
            - lost
            - open
        timestamp: 1724188200
    WebhookEnvelopeTaskCompleted:
      type: object
      required:
      - event
      - payload
      - timestamp
      - source
      properties:
        event:
          type: string
          enum:
          - task_completed
        payload:
          "$ref": "#/components/schemas/TaskPayload"
        timestamp:
          type: integer
          format: int64
        source:
          type: string
          enum:
          - api
          - user
          - automation
          - unknown
      example:
        event: task_completed
        source: user
        payload:
          task:
            identifier: TASK-20240819-001
            started_at: '2024-08-19T09:00:00Z'
            completed_at: '2024-08-19T09:15:30Z'
            time_spent: 930
            attempts: 2
            active_on: '2024-08-19'
            finish_status: completed
            subject_id: 507f1f77bcf86cd799439011
            assignee_id: 507f191e810c19729de860eb
            playbook_id: 507f191e810c19729de860ec
            calls:
            - _id: 507f1f77bcf86cd799439055
              to: "+1234567890"
              from: "+0987654321"
              started_at: '2024-08-19T09:00:00Z'
              completed_at: '2024-08-19T09:15:30Z'
              incoming_call: false
              duration: 930
              response_status: completed
              status: completed
              user_id: 507f191e810c19729de860eb
            subject:
              _id: 507f1f77bcf86cd799439011
              external_reference_id: CRM-12345
        timestamp: 1724190000
    WebhookEnvelopeIncomingCall:
      type: object
      required:
      - event
      - payload
      - timestamp
      - source
      properties:
        event:
          type: string
          enum:
          - incoming_call
        payload:
          "$ref": "#/components/schemas/CallPayload"
        timestamp:
          type: integer
          format: int64
        source:
          type: string
          enum:
          - api
          - user
          - automation
          - unknown
      example:
        event: incoming_call
        source: unknown
        payload:
          from: "+1234567890"
          to: "+0987654321"
          forwarded_from:
        timestamp: 1724192000
    WebhookEnvelopeSubmittedFormCreated:
      type: object
      required:
      - event
      - payload
      - timestamp
      - source
      properties:
        event:
          type: string
          enum:
          - submitted_form_created
        payload:
          "$ref": "#/components/schemas/SubmittedFormPayload"
        timestamp:
          type: integer
          format: int64
        source:
          type: string
          enum:
          - api
          - user
          - automation
          - unknown
      example:
        event: submitted_form_created
        source: unknown
        payload:
          submitted_form:
            id: 507f1f77bcf86cd799439066
            account_id: 507f191e810c19729de860ea
            contact_id: 507f1f77bcf86cd799439011
            form_id: '120210000000000'
            form_name: Get a free quote
            source: meta
            field_errors: []
            typeform_response:
            meta_response:
            meta_webhook_change:
              field: leadgen
              value:
                leadgen_id: '120210000000001'
                page_id: '987654321012345'
                ad_id: '120210000000002'
                adgroup_id: '120210000000003'
                form_id: '120210000000000'
            web_response:
            meta_leadgen_id: '120210000000001'
            meta_page_id: '987654321012345'
            meta_page_name: Acme Corp
            meta_ad_id: '120210000000002'
            meta_ad_name: Summer promo
            meta_adgroup_id: '120210000000003'
            meta_adgroup_name: Summer campaign
            created_at: '2024-08-19T18:00:00Z'
            updated_at: '2024-08-19T18:00:00Z'
            responses:
            - id: 507f1f77bcf86cd799439077
              label: What is your budget?
              input_id: question_budget
              field_string_value:
              field_number_value: 50000
              field_float_value:
              field_date_value:
              field_date_time_value:
              field_time_value:
              field_boolean_value:
              field_string_values:
        timestamp: 1724192500
    WebhookEventEnvelopeOneOf:
      oneOf:
      - "$ref": "#/components/schemas/WebhookEnvelopeContactCreated"
      - "$ref": "#/components/schemas/WebhookEnvelopeContactUpdated"
      - "$ref": "#/components/schemas/WebhookEnvelopeContactDeleted"
      - "$ref": "#/components/schemas/WebhookEnvelopeContactCommentCreated"
      - "$ref": "#/components/schemas/WebhookEnvelopeDocumentCreated"
      - "$ref": "#/components/schemas/WebhookEnvelopeWhatsappReceived"
      - "$ref": "#/components/schemas/WebhookEnvelopeDealCreated"
      - "$ref": "#/components/schemas/WebhookEnvelopeDealUpdated"
      - "$ref": "#/components/schemas/WebhookEnvelopeTaskCompleted"
      - "$ref": "#/components/schemas/WebhookEnvelopeIncomingCall"
      - "$ref": "#/components/schemas/WebhookEnvelopeSubmittedFormCreated"
      discriminator:
        propertyName: event
        mapping:
          contact_created: "#/components/schemas/WebhookEnvelopeContactCreated"
          contact_updated: "#/components/schemas/WebhookEnvelopeContactUpdated"
          contact_deleted: "#/components/schemas/WebhookEnvelopeContactDeleted"
          contact_comment_created: "#/components/schemas/WebhookEnvelopeContactCommentCreated"
          document_created: "#/components/schemas/WebhookEnvelopeDocumentCreated"
          whatsapp_received: "#/components/schemas/WebhookEnvelopeWhatsappReceived"
          deal_created: "#/components/schemas/WebhookEnvelopeDealCreated"
          deal_updated: "#/components/schemas/WebhookEnvelopeDealUpdated"
          task_completed: "#/components/schemas/WebhookEnvelopeTaskCompleted"
          incoming_call: "#/components/schemas/WebhookEnvelopeIncomingCall"
          submitted_form_created: "#/components/schemas/WebhookEnvelopeSubmittedFormCreated"
paths:
  "/webhooks":
    post:
      tags:
      - Webhooks
      servers:
      - url: "{YOUR_WEBHOOK_URL}"
        description: YOUR_WEBHOOK_URL
        variables:
          YOUR_WEBHOOK_URL:
            default: https://example.com
            description: 'Example: https://hooks.example.com'
      parameters: []
      responses:
        '200':
          description: Acknowledged
      summary: Webhooks
      description: Receive webhook events. All events POST to this single path. See
        multiple examples below.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebhookEventEnvelopeOneOf"
            examples:
              contact_created:
                summary: contact_created
                value:
                  event: contact_created
                  source: unknown
                  payload:
                    contact:
                      id: 507f1f77bcf86cd799439011
                      account_id: 507f191e810c19729de860ea
                      assignee_id: 507f191e810c19729de860eb
                      current_playbook_id: 507f191e810c19729de860ec
                      current_flow_step_id: 507f191e810c19729de860ed
                      current_flow_step_since: '2024-08-15T14:30:00Z'
                      contact_import_id:
                      title: John Smith
                      app_url: https://app.vixiees.com/contacts/507f1f77bcf86cd799439011
                      first_name: John
                      last_name: Smith
                      second_last_name:
                      email: john.smith@example.com
                      canonical_email: john.smith@example.com
                      phone: "+1234567890"
                      phone_country_code: US
                      invalid_phone: false
                      invalid_email: false
                      company_name: Acme Corp
                      additional_phones:
                      - "+1234567891"
                      additional_emails:
                      - j.smith@example.com
                      all_emails:
                      - john.smith@example.com
                      - j.smith@example.com
                      all_phones:
                      - "+1234567890"
                      - "+1234567891"
                      priority: 1
                      source: whatsapp
                      last_message: Hello, I need help with...
                      last_message_at: '2024-08-18T10:45:00Z'
                      unread_messages: 0
                      answered_at_least_once: true
                      answered_via_call: false
                      answered_via_email: false
                      answered_via_whatsapp: true
                      first_answer_time: 120
                      first_answered_at: '2024-08-15T14:32:00Z'
                      last_answered_at: '2024-08-18T10:50:00Z'
                      whatsapp_transactional_opt_in: true
                      email_transactional_opt_in: true
                      whatsapp_marketing_opt_in: false
                      email_marketing_opt_in: false
                      external_reference_id: CRM-12345
                      external_reference_url: https://crm.example.com/contacts/12345
                      bankflip_user_link:
                      bankflip_documentation_area_id:
                      unattended: false
                      unanswered_email: false
                      unanswered_whatsapp: false
                      unanswered_call: false
                      on_task: true
                      check_tasks_pending: false
                      ignored: false
                      is_client: false
                      remove_requested: false
                      last_close_won_reason:
                      last_close_lost_reason:
                      merged: false
                      merged_at:
                      last_closed_office_message_sent_at:
                      last_assignee_at: '2024-08-15T14:30:00Z'
                      last_started_task_at: '2024-08-18T09:00:00Z'
                      last_completed_task_at:
                      last_successful_call_at:
                      last_unsuccessful_call_at:
                      last_email_sent_at:
                      last_email_received_at:
                      last_window_opened_at: '2024-08-18T11:00:00Z'
                      ai_controlling: false
                      ai_disabled: false
                      ai_test: false
                      ai_suppressed_until_flow_step_change: false
                      ai_reply_count_in_state: 0
                      deals_count: 2
                      meetings_count: 1
                      pinned_comment_id:
                      has_skills: false
                      skills: []
                      created_at: '2024-08-15T14:30:00Z'
                      updated_at: '2024-08-18T11:00:00Z'
                      deleted_at:
                      locale: en
                      country_code: US
                      utm_source: google
                      utm_medium: cpc
                      utm_campaign: summer_2024
                      utm_term:
                      utm_content:
                      gclid: Cj0KCQjw...
                      landing_page_url: https://example.com/landing
                      landing_page_query: "?ref=google"
                      leadgen_id:
                      ad_id:
                      ad_name:
                      adgroup_id:
                      adgroup_name:
                      page_id:
                      page_name:
                      form_id:
                      deleted_phone:
                      deleted_email:
                      deleted_external_reference_id:
                      deleted_crm_id:
                      sent_imported_email_ids: []
                      received_imported_email_ids: []
                      custom_attributes:
                      - id: 507f1f77bcf86cd799439012
                        field_name: budget
                        humanized_name: Budget
                        field_type: integer
                        editable: true
                        value: 50000
                        string_value:
                        integer_value: 50000
                        float_value:
                        date_value:
                        boolean_value:
                        array_value:
                        nullable: false
                  timestamp: 1724000000
              contact_updated:
                summary: contact_updated
                value:
                  event: contact_updated
                  source: user
                  payload:
                    contact:
                      id: 507f1f77bcf86cd799439011
                      account_id: 507f191e810c19729de860ea
                      assignee_id: 507f191e810c19729de860eb
                      current_playbook_id: 507f191e810c19729de860ec
                      current_flow_step_id: 507f191e810c19729de860ed
                      current_flow_step_since: '2024-08-19T15:22:00Z'
                      contact_import_id:
                      title: John Smith
                      app_url: https://app.vixiees.com/contacts/507f1f77bcf86cd799439011
                      first_name: John
                      last_name: Smith
                      second_last_name:
                      email: john.smith@example.com
                      canonical_email: john.smith@example.com
                      phone: "+1234567890"
                      phone_country_code: US
                      invalid_phone: false
                      invalid_email: false
                      company_name: Acme Corp
                      additional_phones: []
                      additional_emails: []
                      all_emails:
                      - john.smith@example.com
                      all_phones:
                      - "+1234567890"
                      priority: 2
                      source: whatsapp
                      last_message: Hello, I need help with...
                      last_message_at: '2024-08-18T10:45:00Z'
                      unread_messages: 0
                      answered_at_least_once: true
                      answered_via_call: false
                      answered_via_email: false
                      answered_via_whatsapp: true
                      first_answer_time: 120
                      first_answered_at: '2024-08-15T14:32:00Z'
                      last_answered_at: '2024-08-19T15:10:00Z'
                      whatsapp_transactional_opt_in: true
                      email_transactional_opt_in: true
                      whatsapp_marketing_opt_in: false
                      email_marketing_opt_in: false
                      external_reference_id: CRM-12345
                      external_reference_url: https://crm.example.com/contacts/12345
                      bankflip_user_link:
                      bankflip_documentation_area_id:
                      unattended: false
                      unanswered_email: false
                      unanswered_whatsapp: false
                      unanswered_call: false
                      on_task: false
                      check_tasks_pending: false
                      ignored: false
                      is_client: true
                      remove_requested: false
                      last_close_won_reason:
                      last_close_lost_reason:
                      merged: false
                      merged_at:
                      last_closed_office_message_sent_at:
                      last_assignee_at: '2024-08-15T14:30:00Z'
                      last_started_task_at: '2024-08-18T09:00:00Z'
                      last_completed_task_at: '2024-08-19T15:15:00Z'
                      last_successful_call_at: '2024-08-19T15:00:00Z'
                      last_unsuccessful_call_at:
                      last_email_sent_at:
                      last_email_received_at:
                      last_window_opened_at: '2024-08-19T15:20:00Z'
                      ai_controlling: false
                      ai_disabled: false
                      ai_test: false
                      ai_suppressed_until_flow_step_change: false
                      ai_reply_count_in_state: 0
                      deals_count: 3
                      meetings_count: 1
                      pinned_comment_id:
                      has_skills: false
                      skills: []
                      created_at: '2024-08-15T14:30:00Z'
                      updated_at: '2024-08-19T15:22:00Z'
                      deleted_at:
                      locale: en
                      country_code: US
                      utm_source: google
                      utm_medium: cpc
                      utm_campaign: summer_2024
                      utm_term:
                      utm_content:
                      gclid: Cj0KCQjw...
                      landing_page_url: https://example.com/landing
                      landing_page_query: "?ref=google"
                      leadgen_id:
                      ad_id:
                      ad_name:
                      adgroup_id:
                      adgroup_name:
                      page_id:
                      page_name:
                      form_id:
                      deleted_phone:
                      deleted_email:
                      deleted_external_reference_id:
                      deleted_crm_id:
                      sent_imported_email_ids: []
                      received_imported_email_ids: []
                      custom_attributes:
                      - id: 507f1f77bcf86cd799439012
                        field_name: budget
                        humanized_name: Budget
                        field_type: integer
                        editable: true
                        value: 50000
                        string_value:
                        integer_value: 50000
                        float_value:
                        date_value:
                        boolean_value:
                        array_value:
                        nullable: false
                    action: flow_step_changed
                    changes:
                      current_flow_step_id:
                      - 507f191e810c19729de860ee
                      - 507f191e810c19729de860ed
                      current_playbook_id:
                      - 507f191e810c19729de860ec
                      - 507f191e810c19729de860ec
                  timestamp: 1724100000
              contact_deleted:
                summary: contact_deleted
                value:
                  event: contact_deleted
                  source: user
                  payload:
                    contact:
                      id: 507f1f77bcf86cd799439011
                      account_id: 507f191e810c19729de860ea
                      assignee_id: 507f191e810c19729de860eb
                      current_playbook_id:
                      current_flow_step_id:
                      current_flow_step_since: '2024-08-15T14:30:00Z'
                      contact_import_id:
                      title: John Smith
                      app_url: https://app.vixiees.com/contacts/507f1f77bcf86cd799439011
                      first_name: John
                      last_name: Smith
                      second_last_name:
                      email:
                      canonical_email:
                      phone:
                      phone_country_code: US
                      invalid_phone: false
                      invalid_email: false
                      company_name: Acme Corp
                      additional_phones:
                      - "+1234567891"
                      additional_emails:
                      - j.smith@example.com
                      all_emails:
                      - j.smith@example.com
                      all_phones:
                      - "+1234567891"
                      priority: 1
                      source: whatsapp
                      last_message: Hello, I need help with...
                      last_message_at: '2024-08-18T10:45:00Z'
                      unread_messages: 0
                      answered_at_least_once: true
                      answered_via_call: false
                      answered_via_email: false
                      answered_via_whatsapp: true
                      first_answer_time: 120
                      first_answered_at: '2024-08-15T14:32:00Z'
                      last_answered_at: '2024-08-18T10:50:00Z'
                      whatsapp_transactional_opt_in: true
                      email_transactional_opt_in: true
                      whatsapp_marketing_opt_in: false
                      email_marketing_opt_in: false
                      external_reference_id:
                      external_reference_url: https://crm.example.com/contacts/12345
                      bankflip_user_link:
                      bankflip_documentation_area_id:
                      unattended: false
                      unanswered_email: false
                      unanswered_whatsapp: false
                      unanswered_call: false
                      on_task: false
                      check_tasks_pending: false
                      ignored: true
                      is_client: false
                      remove_requested: false
                      last_close_won_reason:
                      last_close_lost_reason:
                      merged: false
                      merged_at:
                      last_closed_office_message_sent_at:
                      last_assignee_at: '2024-08-15T14:30:00Z'
                      last_started_task_at: '2024-08-18T09:00:00Z'
                      last_completed_task_at:
                      last_successful_call_at:
                      last_unsuccessful_call_at:
                      last_email_sent_at:
                      last_email_received_at:
                      last_window_opened_at: '2024-08-18T11:00:00Z'
                      ai_controlling: false
                      ai_disabled: false
                      ai_test: false
                      ai_suppressed_until_flow_step_change: false
                      ai_reply_count_in_state: 0
                      deals_count: 2
                      meetings_count: 1
                      pinned_comment_id:
                      has_skills: false
                      skills: []
                      created_at: '2024-08-15T14:30:00Z'
                      updated_at: '2024-08-20T10:00:00Z'
                      deleted_at: '2024-08-20T10:00:00Z'
                      locale: en
                      country_code: US
                      utm_source: google
                      utm_medium: cpc
                      utm_campaign: summer_2024
                      utm_term:
                      utm_content:
                      gclid: Cj0KCQjw...
                      landing_page_url: https://example.com/landing
                      landing_page_query: "?ref=google"
                      leadgen_id:
                      ad_id:
                      ad_name:
                      adgroup_id:
                      adgroup_name:
                      page_id:
                      page_name:
                      form_id:
                      deleted_phone: "+1234567890"
                      deleted_email: john.smith@example.com
                      deleted_external_reference_id: CRM-12345
                      deleted_crm_id:
                      sent_imported_email_ids: []
                      received_imported_email_ids: []
                      custom_attributes:
                      - id: 507f1f77bcf86cd799439012
                        field_name: budget
                        humanized_name: Budget
                        field_type: integer
                        editable: true
                        value: 50000
                        string_value:
                        integer_value: 50000
                        float_value:
                        date_value:
                        boolean_value:
                        array_value:
                        nullable: false
                  timestamp: 1724150000
              contact_comment_created:
                summary: contact_comment_created
                value:
                  event: contact_comment_created
                  source: user
                  payload:
                    contact:
                      id: 507f1f77bcf86cd799439011
                      account_id: 507f191e810c19729de860ea
                      assignee_id: 507f191e810c19729de860eb
                      current_playbook_id: 507f191e810c19729de860ec
                      current_flow_step_id: 507f191e810c19729de860ed
                      current_flow_step_since: '2024-08-15T14:30:00Z'
                      contact_import_id:
                      title: John Smith
                      app_url: https://app.vixiees.com/contacts/507f1f77bcf86cd799439011
                      first_name: John
                      last_name: Smith
                      second_last_name:
                      email: john.smith@example.com
                      canonical_email: john.smith@example.com
                      phone: "+1234567890"
                      phone_country_code: US
                      invalid_phone: false
                      invalid_email: false
                      company_name: Acme Corp
                      additional_phones:
                      - "+1234567891"
                      additional_emails:
                      - j.smith@example.com
                      all_emails:
                      - john.smith@example.com
                      - j.smith@example.com
                      all_phones:
                      - "+1234567890"
                      - "+1234567891"
                      priority: 1
                      source: whatsapp
                      last_message: Hello, I need help with...
                      last_message_at: '2024-08-18T10:45:00Z'
                      unread_messages: 0
                      answered_at_least_once: true
                      answered_via_call: false
                      answered_via_email: false
                      answered_via_whatsapp: true
                      first_answer_time: 120
                      first_answered_at: '2024-08-15T14:32:00Z'
                      last_answered_at: '2024-08-18T10:50:00Z'
                      whatsapp_transactional_opt_in: true
                      email_transactional_opt_in: true
                      whatsapp_marketing_opt_in: false
                      email_marketing_opt_in: false
                      external_reference_id: CRM-12345
                      external_reference_url: https://crm.example.com/contacts/12345
                      bankflip_user_link:
                      bankflip_documentation_area_id:
                      unattended: false
                      unanswered_email: false
                      unanswered_whatsapp: false
                      unanswered_call: false
                      on_task: true
                      check_tasks_pending: false
                      ignored: false
                      is_client: false
                      remove_requested: false
                      last_close_won_reason:
                      last_close_lost_reason:
                      merged: false
                      merged_at:
                      last_closed_office_message_sent_at:
                      last_assignee_at: '2024-08-15T14:30:00Z'
                      last_started_task_at: '2024-08-18T09:00:00Z'
                      last_completed_task_at:
                      last_successful_call_at:
                      last_unsuccessful_call_at:
                      last_email_sent_at:
                      last_email_received_at:
                      last_window_opened_at: '2024-08-18T11:00:00Z'
                      ai_controlling: false
                      ai_disabled: false
                      ai_test: false
                      ai_suppressed_until_flow_step_change: false
                      ai_reply_count_in_state: 0
                      deals_count: 2
                      meetings_count: 1
                      pinned_comment_id: 507f1f77bcf86cd799439022
                      has_skills: false
                      skills: []
                      created_at: '2024-08-15T14:30:00Z'
                      updated_at: '2024-08-19T16:30:00Z'
                      deleted_at:
                      locale: en
                      country_code: US
                      utm_source: google
                      utm_medium: cpc
                      utm_campaign: summer_2024
                      utm_term:
                      utm_content:
                      gclid: Cj0KCQjw...
                      landing_page_url: https://example.com/landing
                      landing_page_query: "?ref=google"
                      leadgen_id:
                      ad_id:
                      ad_name:
                      adgroup_id:
                      adgroup_name:
                      page_id:
                      page_name:
                      form_id:
                      deleted_phone:
                      deleted_email:
                      deleted_external_reference_id:
                      deleted_crm_id:
                      sent_imported_email_ids: []
                      received_imported_email_ids: []
                      custom_attributes:
                      - id: 507f1f77bcf86cd799439012
                        field_name: budget
                        humanized_name: Budget
                        field_type: integer
                        editable: true
                        value: 50000
                        string_value:
                        integer_value: 50000
                        float_value:
                        date_value:
                        boolean_value:
                        array_value:
                        nullable: false
                    comment:
                      id: 507f1f77bcf86cd799439022
                      created_by_id: 507f191e810c19729de860eb
                      content: Client requested a follow-up call next week
                      created_at: '2024-08-19T16:30:00Z'
                      updated_at: '2024-08-19T16:30:00Z'
                  timestamp: 1724180000
              document_created:
                summary: document_created
                value:
                  event: document_created
                  source: unknown
                  payload:
                    contact:
                      id: 507f1f77bcf86cd799439011
                      account_id: 507f191e810c19729de860ea
                      assignee_id: 507f191e810c19729de860eb
                      current_playbook_id: 507f191e810c19729de860ec
                      current_flow_step_id: 507f191e810c19729de860ed
                      current_flow_step_since: '2024-08-15T14:30:00Z'
                      contact_import_id:
                      title: John Smith
                      app_url: https://app.vixiees.com/contacts/507f1f77bcf86cd799439011
                      first_name: John
                      last_name: Smith
                      second_last_name:
                      email: john.smith@example.com
                      canonical_email: john.smith@example.com
                      phone: "+1234567890"
                      phone_country_code: US
                      invalid_phone: false
                      invalid_email: false
                      company_name: Acme Corp
                      additional_phones:
                      - "+1234567891"
                      additional_emails:
                      - j.smith@example.com
                      all_emails:
                      - john.smith@example.com
                      - j.smith@example.com
                      all_phones:
                      - "+1234567890"
                      - "+1234567891"
                      priority: 1
                      source: whatsapp
                      last_message: Hello, I need help with...
                      last_message_at: '2024-08-18T10:45:00Z'
                      unread_messages: 0
                      answered_at_least_once: true
                      answered_via_call: false
                      answered_via_email: false
                      answered_via_whatsapp: true
                      first_answer_time: 120
                      first_answered_at: '2024-08-15T14:32:00Z'
                      last_answered_at: '2024-08-18T10:50:00Z'
                      whatsapp_transactional_opt_in: true
                      email_transactional_opt_in: true
                      whatsapp_marketing_opt_in: false
                      email_marketing_opt_in: false
                      external_reference_id: CRM-12345
                      external_reference_url: https://crm.example.com/contacts/12345
                      bankflip_user_link:
                      bankflip_documentation_area_id:
                      unattended: false
                      unanswered_email: false
                      unanswered_whatsapp: false
                      unanswered_call: false
                      on_task: true
                      check_tasks_pending: false
                      ignored: false
                      is_client: false
                      remove_requested: false
                      last_close_won_reason:
                      last_close_lost_reason:
                      merged: false
                      merged_at:
                      last_closed_office_message_sent_at:
                      last_assignee_at: '2024-08-15T14:30:00Z'
                      last_started_task_at: '2024-08-18T09:00:00Z'
                      last_completed_task_at:
                      last_successful_call_at:
                      last_unsuccessful_call_at:
                      last_email_sent_at:
                      last_email_received_at:
                      last_window_opened_at: '2024-08-18T11:00:00Z'
                      ai_controlling: false
                      ai_disabled: false
                      ai_test: false
                      ai_suppressed_until_flow_step_change: false
                      ai_reply_count_in_state: 0
                      deals_count: 2
                      meetings_count: 1
                      pinned_comment_id:
                      has_skills: false
                      skills: []
                      created_at: '2024-08-15T14:30:00Z'
                      updated_at: '2024-08-19T17:00:00Z'
                      deleted_at:
                      locale: en
                      country_code: US
                      utm_source: google
                      utm_medium: cpc
                      utm_campaign: summer_2024
                      utm_term:
                      utm_content:
                      gclid: Cj0KCQjw...
                      landing_page_url: https://example.com/landing
                      landing_page_query: "?ref=google"
                      leadgen_id:
                      ad_id:
                      ad_name:
                      adgroup_id:
                      adgroup_name:
                      page_id:
                      page_name:
                      form_id:
                      deleted_phone:
                      deleted_email:
                      deleted_external_reference_id:
                      deleted_crm_id:
                      sent_imported_email_ids: []
                      received_imported_email_ids: []
                      custom_attributes:
                      - id: 507f1f77bcf86cd799439012
                        field_name: budget
                        humanized_name: Budget
                        field_type: integer
                        editable: true
                        value: 50000
                        string_value:
                        integer_value: 50000
                        float_value:
                        date_value:
                        boolean_value:
                        array_value:
                        nullable: false
                    document:
                      id: 507f1f77bcf86cd799439033
                      file_file_name: contract.pdf
                      file_file_size: 245678
                      file_content_type: application/pdf
                      file_fingerprint: abc123def456
                      file_updated_at: '2024-08-19T17:00:00Z'
                      tag: contract
                      source: whatsapp
                      email_content_id:
                      expiring_url: https://cdn.vixiees.com/documents/contract.pdf?expires=1724182000&signature=xyz
                      created_at: '2024-08-19T17:00:00Z'
                      updated_at: '2024-08-19T17:00:00Z'
                  timestamp: 1724182000
              whatsapp_received:
                summary: whatsapp_received
                value:
                  event: whatsapp_received
                  source: unknown
                  payload:
                    contact:
                      id: 507f1f77bcf86cd799439011
                      account_id: 507f191e810c19729de860ea
                      assignee_id: 507f191e810c19729de860eb
                      current_playbook_id: 507f191e810c19729de860ec
                      current_flow_step_id: 507f191e810c19729de860ed
                      current_flow_step_since: '2024-08-15T14:30:00Z'
                      contact_import_id:
                      title: John Smith
                      app_url: https://app.vixiees.com/contacts/507f1f77bcf86cd799439011
                      first_name: John
                      last_name: Smith
                      second_last_name:
                      email: john.smith@example.com
                      canonical_email: john.smith@example.com
                      phone: "+1234567890"
                      phone_country_code: US
                      invalid_phone: false
                      invalid_email: false
                      company_name: Acme Corp
                      additional_phones:
                      - "+1234567891"
                      additional_emails:
                      - j.smith@example.com
                      all_emails:
                      - john.smith@example.com
                      - j.smith@example.com
                      all_phones:
                      - "+1234567890"
                      - "+1234567891"
                      priority: 1
                      source: whatsapp
                      last_message: Hello, I have a question about your services
                      last_message_at: '2024-08-19T17:20:00Z'
                      unread_messages: 1
                      answered_at_least_once: true
                      answered_via_call: false
                      answered_via_email: false
                      answered_via_whatsapp: true
                      first_answer_time: 120
                      first_answered_at: '2024-08-15T14:32:00Z'
                      last_answered_at: '2024-08-18T10:50:00Z'
                      whatsapp_transactional_opt_in: true
                      email_transactional_opt_in: true
                      whatsapp_marketing_opt_in: false
                      email_marketing_opt_in: false
                      external_reference_id: CRM-12345
                      external_reference_url: https://crm.example.com/contacts/12345
                      bankflip_user_link:
                      bankflip_documentation_area_id:
                      unattended: false
                      unanswered_email: false
                      unanswered_whatsapp: true
                      unanswered_call: false
                      on_task: true
                      check_tasks_pending: false
                      ignored: false
                      is_client: false
                      remove_requested: false
                      last_close_won_reason:
                      last_close_lost_reason:
                      merged: false
                      merged_at:
                      last_closed_office_message_sent_at:
                      last_assignee_at: '2024-08-15T14:30:00Z'
                      last_started_task_at: '2024-08-18T09:00:00Z'
                      last_completed_task_at:
                      last_successful_call_at:
                      last_unsuccessful_call_at:
                      last_email_sent_at:
                      last_email_received_at:
                      last_window_opened_at: '2024-08-19T17:20:00Z'
                      ai_controlling: false
                      ai_disabled: false
                      ai_test: false
                      ai_suppressed_until_flow_step_change: false
                      ai_reply_count_in_state: 0
                      deals_count: 2
                      meetings_count: 1
                      pinned_comment_id:
                      has_skills: false
                      skills: []
                      created_at: '2024-08-15T14:30:00Z'
                      updated_at: '2024-08-19T17:20:00Z'
                      deleted_at:
                      locale: en
                      country_code: US
                      utm_source: google
                      utm_medium: cpc
                      utm_campaign: summer_2024
                      utm_term:
                      utm_content:
                      gclid: Cj0KCQjw...
                      landing_page_url: https://example.com/landing
                      landing_page_query: "?ref=google"
                      leadgen_id:
                      ad_id:
                      ad_name:
                      adgroup_id:
                      adgroup_name:
                      page_id:
                      page_name:
                      form_id:
                      deleted_phone:
                      deleted_email:
                      deleted_external_reference_id:
                      deleted_crm_id:
                      sent_imported_email_ids: []
                      received_imported_email_ids: []
                      custom_attributes:
                      - id: 507f1f77bcf86cd799439012
                        field_name: budget
                        humanized_name: Budget
                        field_type: integer
                        editable: true
                        value: 50000
                        string_value:
                        integer_value: 50000
                        float_value:
                        date_value:
                        boolean_value:
                        array_value:
                        nullable: false
                    message:
                      from: '1234567890'
                      id: wamid.HBgNMTIzNDU2Nzg5MAAKMD==
                      timestamp: '1724185200'
                      type: text
                      text:
                        body: Hello, I have a question about your services
                  timestamp: 1724185200
              deal_created:
                summary: deal_created
                value:
                  event: deal_created
                  source: api
                  payload:
                    deal:
                      id: 507f1f77bcf86cd799439044
                      account_id: 507f191e810c19729de860ea
                      contact_id: 507f1f77bcf86cd799439011
                      assignee_id: 507f191e810c19729de860eb
                      closer_id:
                      title: Q3 Enterprise License
                      description: Annual enterprise software license renewal
                      amount: 150000.5
                      close_date:
                      closed: false
                      won: false
                      status: open
                      external_reference_id: DEAL-2024-089
                      deleted_external_reference_id:
                      deleted_crm_id:
                      created_at: '2024-08-01T10:00:00Z'
                      updated_at: '2024-08-01T10:00:00Z'
                      deleted_at:
                  timestamp: 1722506400
              deal_updated:
                summary: deal_updated
                value:
                  event: deal_updated
                  source: user
                  payload:
                    deal:
                      id: 507f1f77bcf86cd799439044
                      account_id: 507f191e810c19729de860ea
                      contact_id: 507f1f77bcf86cd799439011
                      assignee_id: 507f191e810c19729de860eb
                      closer_id:
                      title: Q3 Enterprise License
                      description: Annual enterprise software license renewal
                      amount: 150000.5
                      close_date:
                      closed: false
                      won: false
                      status: open
                      external_reference_id: DEAL-2024-089
                      deleted_external_reference_id:
                      deleted_crm_id:
                      created_at: '2024-08-01T10:00:00Z'
                      updated_at: '2024-08-19T18:30:00Z'
                      deleted_at:
                    action: reopened
                    changes:
                      status:
                      - lost
                      - open
                  timestamp: 1724188200
              task_completed:
                summary: task_completed
                value:
                  event: task_completed
                  source: user
                  payload:
                    task:
                      identifier: TASK-20240819-001
                      started_at: '2024-08-19T09:00:00Z'
                      completed_at: '2024-08-19T09:15:30Z'
                      time_spent: 930
                      attempts: 2
                      active_on: '2024-08-19'
                      finish_status: completed
                      subject_id: 507f1f77bcf86cd799439011
                      assignee_id: 507f191e810c19729de860eb
                      playbook_id: 507f191e810c19729de860ec
                      calls:
                      - _id: 507f1f77bcf86cd799439055
                        to: "+1234567890"
                        from: "+0987654321"
                        started_at: '2024-08-19T09:00:00Z'
                        completed_at: '2024-08-19T09:15:30Z'
                        incoming_call: false
                        duration: 930
                        response_status: completed
                        status: completed
                        user_id: 507f191e810c19729de860eb
                      subject:
                        _id: 507f1f77bcf86cd799439011
                        external_reference_id: CRM-12345
                  timestamp: 1724190000
              incoming_call:
                summary: incoming_call
                value:
                  event: incoming_call
                  source: unknown
                  payload:
                    from: "+1234567890"
                    to: "+0987654321"
                    forwarded_from:
                  timestamp: 1724192000
              submitted_form_created:
                summary: submitted_form_created
                value:
                  event: submitted_form_created
                  source: unknown
                  payload:
                    submitted_form:
                      id: 507f1f77bcf86cd799439066
                      account_id: 507f191e810c19729de860ea
                      contact_id: 507f1f77bcf86cd799439011
                      form_id: '120210000000000'
                      form_name: Get a free quote
                      source: meta
                      field_errors: []
                      typeform_response:
                      meta_response:
                      meta_webhook_change:
                        field: leadgen
                        value:
                          leadgen_id: '120210000000001'
                          page_id: '987654321012345'
                          ad_id: '120210000000002'
                          adgroup_id: '120210000000003'
                          form_id: '120210000000000'
                      web_response:
                      meta_leadgen_id: '120210000000001'
                      meta_page_id: '987654321012345'
                      meta_page_name: Acme Corp
                      meta_ad_id: '120210000000002'
                      meta_ad_name: Summer promo
                      meta_adgroup_id: '120210000000003'
                      meta_adgroup_name: Summer campaign
                      created_at: '2024-08-19T18:00:00Z'
                      updated_at: '2024-08-19T18:00:00Z'
                      responses:
                      - id: 507f1f77bcf86cd799439077
                        label: What is your budget?
                        input_id: question_budget
                        field_string_value:
                        field_number_value: 50000
                        field_float_value:
                        field_date_value:
                        field_date_time_value:
                        field_time_value:
                        field_boolean_value:
                        field_string_values:
                  timestamp: 1724192500
  "/webhooks/example/contact_created":
    post:
      tags:
      - Webhooks
      servers:
      - url: "{YOUR_WEBHOOK_URL}"
        description: YOUR_WEBHOOK_URL
        variables:
          YOUR_WEBHOOK_URL:
            default: https://example.com
            description: 'Example: https://hooks.example.com'
      parameters: []
      responses:
        '200':
          description: Acknowledged
      summary: 'Webhooks example: contact_created'
      description: Example only. Actual endpoint path is /webhooks. Use YOUR_WEBHOOK_URL;
        only the body varies.
      operationId: webhooks_example_contact_created
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebhookEnvelopeContactCreated"
  "/webhooks/example/contact_updated":
    post:
      tags:
      - Webhooks
      servers:
      - url: "{YOUR_WEBHOOK_URL}"
        description: YOUR_WEBHOOK_URL
        variables:
          YOUR_WEBHOOK_URL:
            default: https://example.com
            description: 'Example: https://hooks.example.com'
      parameters: []
      responses:
        '200':
          description: Acknowledged
      summary: 'Webhooks example: contact_updated'
      description: Example only. Actual endpoint path is /webhooks. Use YOUR_WEBHOOK_URL;
        only the body varies.
      operationId: webhooks_example_contact_updated
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebhookEnvelopeContactUpdated"
  "/webhooks/example/contact_deleted":
    post:
      tags:
      - Webhooks
      servers:
      - url: "{YOUR_WEBHOOK_URL}"
        description: YOUR_WEBHOOK_URL
        variables:
          YOUR_WEBHOOK_URL:
            default: https://example.com
            description: 'Example: https://hooks.example.com'
      parameters: []
      responses:
        '200':
          description: Acknowledged
      summary: 'Webhooks example: contact_deleted'
      description: Example only. Actual endpoint path is /webhooks. Use YOUR_WEBHOOK_URL;
        only the body varies.
      operationId: webhooks_example_contact_deleted
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebhookEnvelopeContactDeleted"
  "/webhooks/example/contact_comment_created":
    post:
      tags:
      - Webhooks
      servers:
      - url: "{YOUR_WEBHOOK_URL}"
        description: YOUR_WEBHOOK_URL
        variables:
          YOUR_WEBHOOK_URL:
            default: https://example.com
            description: 'Example: https://hooks.example.com'
      parameters: []
      responses:
        '200':
          description: Acknowledged
      summary: 'Webhooks example: contact_comment_created'
      description: Example only. Actual endpoint path is /webhooks. Use YOUR_WEBHOOK_URL;
        only the body varies.
      operationId: webhooks_example_contact_comment_created
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebhookEnvelopeContactCommentCreated"
  "/webhooks/example/document_created":
    post:
      tags:
      - Webhooks
      servers:
      - url: "{YOUR_WEBHOOK_URL}"
        description: YOUR_WEBHOOK_URL
        variables:
          YOUR_WEBHOOK_URL:
            default: https://example.com
            description: 'Example: https://hooks.example.com'
      parameters: []
      responses:
        '200':
          description: Acknowledged
      summary: 'Webhooks example: document_created'
      description: Example only. Actual endpoint path is /webhooks. Use YOUR_WEBHOOK_URL;
        only the body varies.
      operationId: webhooks_example_document_created
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebhookEnvelopeDocumentCreated"
  "/webhooks/example/whatsapp_received":
    post:
      tags:
      - Webhooks
      servers:
      - url: "{YOUR_WEBHOOK_URL}"
        description: YOUR_WEBHOOK_URL
        variables:
          YOUR_WEBHOOK_URL:
            default: https://example.com
            description: 'Example: https://hooks.example.com'
      parameters: []
      responses:
        '200':
          description: Acknowledged
      summary: 'Webhooks example: whatsapp_received'
      description: Example only. Actual endpoint path is /webhooks. Use YOUR_WEBHOOK_URL;
        only the body varies.
      operationId: webhooks_example_whatsapp_received
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebhookEnvelopeWhatsappReceived"
  "/webhooks/example/deal_created":
    post:
      tags:
      - Webhooks
      servers:
      - url: "{YOUR_WEBHOOK_URL}"
        description: YOUR_WEBHOOK_URL
        variables:
          YOUR_WEBHOOK_URL:
            default: https://example.com
            description: 'Example: https://hooks.example.com'
      parameters: []
      responses:
        '200':
          description: Acknowledged
      summary: 'Webhooks example: deal_created'
      description: Example only. Actual endpoint path is /webhooks. Use YOUR_WEBHOOK_URL;
        only the body varies.
      operationId: webhooks_example_deal_created
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebhookEnvelopeDealCreated"
  "/webhooks/example/deal_updated":
    post:
      tags:
      - Webhooks
      servers:
      - url: "{YOUR_WEBHOOK_URL}"
        description: YOUR_WEBHOOK_URL
        variables:
          YOUR_WEBHOOK_URL:
            default: https://example.com
            description: 'Example: https://hooks.example.com'
      parameters: []
      responses:
        '200':
          description: Acknowledged
      summary: 'Webhooks example: deal_updated'
      description: Example only. Actual endpoint path is /webhooks. Use YOUR_WEBHOOK_URL;
        only the body varies.
      operationId: webhooks_example_deal_updated
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebhookEnvelopeDealUpdated"
  "/webhooks/example/task_completed":
    post:
      tags:
      - Webhooks
      servers:
      - url: "{YOUR_WEBHOOK_URL}"
        description: YOUR_WEBHOOK_URL
        variables:
          YOUR_WEBHOOK_URL:
            default: https://example.com
            description: 'Example: https://hooks.example.com'
      parameters: []
      responses:
        '200':
          description: Acknowledged
      summary: 'Webhooks example: task_completed'
      description: Example only. Actual endpoint path is /webhooks. Use YOUR_WEBHOOK_URL;
        only the body varies.
      operationId: webhooks_example_task_completed
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebhookEnvelopeTaskCompleted"
  "/webhooks/example/incoming_call":
    post:
      tags:
      - Webhooks
      servers:
      - url: "{YOUR_WEBHOOK_URL}"
        description: YOUR_WEBHOOK_URL
        variables:
          YOUR_WEBHOOK_URL:
            default: https://example.com
            description: 'Example: https://hooks.example.com'
      parameters: []
      responses:
        '200':
          description: Acknowledged
      summary: 'Webhooks example: incoming_call'
      description: Example only. Actual endpoint path is /webhooks. Use YOUR_WEBHOOK_URL;
        only the body varies.
      operationId: webhooks_example_incoming_call
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebhookEnvelopeIncomingCall"
  "/webhooks/example/submitted_form_created":
    post:
      tags:
      - Webhooks
      servers:
      - url: "{YOUR_WEBHOOK_URL}"
        description: YOUR_WEBHOOK_URL
        variables:
          YOUR_WEBHOOK_URL:
            default: https://example.com
            description: 'Example: https://hooks.example.com'
      parameters: []
      responses:
        '200':
          description: Acknowledged
      summary: 'Webhooks example: submitted_form_created'
      description: Example only. Actual endpoint path is /webhooks. Use YOUR_WEBHOOK_URL;
        only the body varies.
      operationId: webhooks_example_submitted_form_created
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebhookEnvelopeSubmittedFormCreated"
  "/call_recordings":
    get:
      summary: Retrieves call recordings
      tags:
      - Call Recordings
      security:
      - api_key: []
      description: |
        Returns a paginated list of call recordings with transcription status.

        Each recording includes an `encrypted_url` for secure playback access.
        Filter by contact, user, playbook, or task to narrow results.
      parameters:
      - name: contact_id
        in: query
        required: false
        description: Filter by contact ID
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      - name: call_id
        in: query
        required: false
        description: Filter by call ID
        schema:
          type: string
        example: CAabcd1234567890
      - name: user_id
        in: query
        required: false
        description: Filter by user ID
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234cd
      - name: playbook_id
        in: query
        required: false
        description: Filter by playbook ID
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ef
      - name: flow_step_id
        in: query
        required: false
        description: Filter by flow step ID
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234gh
      - name: task_identifier
        in: query
        required: false
        description: Filter by task identifier
        schema:
          type: string
        example: TASK-001
      - name: partial
        in: query
        required: false
        description: Filter by partial status
        schema:
          type: boolean
        example: false
      - name: created_at
        in: query
        required: false
        description: Filter by creation date (ISO 8601 format)
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00Z'
      - name: page
        in: query
        required: false
        description: Page number for pagination
        schema:
          type: integer
          default: 1
          minimum: 1
        example: 1
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 100
        example: 25
      - name: order_by
        in: query
        required: false
        description: Field to order results by
        schema:
          type: string
          default: created_at
        example: created_at
      - name: sort
        in: query
        required: false
        description: Sort direction (asc or desc)
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
        example: desc
      responses:
        '200':
          description: call recordings found
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        title:
                          type: string
                          nullable: true
                        contact_title:
                          type: string
                          nullable: true
                        duration:
                          type: integer
                          nullable: true
                        channels:
                          type: integer
                          nullable: true
                        start_time:
                          type: string
                          format: date-time
                          nullable: true
                        incoming_call:
                          type: boolean
                          nullable: true
                        language_code:
                          type: string
                          nullable: true
                        task_identifier:
                          type: string
                          nullable: true
                        transcription_status:
                          type: string
                          nullable: true
                        sentiment_analysis_score:
                          type: number
                          format: float
                          nullable: true
                        score:
                          type: integer
                          nullable: true
                        call_id:
                          type: string
                          nullable: true
                        user_id:
                          type: string
                          nullable: true
                        contact_id:
                          type: string
                          nullable: true
                        account_id:
                          type: string
                          nullable: true
                        playbook_id:
                          type: string
                          nullable: true
                        flow_step_id:
                          type: string
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                        encrypted_url:
                          type: string
                          nullable: true
                        conference_encrypted_url:
                          type: string
                          nullable: true
                        partial:
                          type: boolean
                          nullable: true
                  page_info:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        nullable: true
                      limit:
                        type: integer
                        nullable: true
        '401':
          description: unauthorized
  "/contacts/{contact_id}/calls":
    parameters:
    - name: contact_id
      in: path
      required: true
      description: The ID or external reference ID of the contact
      schema:
        type: string
      example: 64a1b2c3d4e5f678901234ab
    post:
      summary: Logs a call made outside Vixiees
      tags:
      - Contacts
      security:
      - api_key: []
      description: |
        Records a call that already happened outside Vixiees (another dialer, an AI voice agent, a mobile phone) on the contact.

        No call is placed. The call appears in the contact timeline; it does not change the contact's state or tasks. It is not billed and does not count in Vixiees call analytics.
        When omitted, `to` (outgoing) or `from` (incoming) defaults to the contact phone.
      parameters: []
      responses:
        '200':
          description: call logged
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the created call
                required:
                - id
        '401':
          description: unauthorized
        '404':
          description: contact not found
        '422':
          description: unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    example:
                      direction:
                      - is not included in the list
                      user_id:
                      - User not found in this account
                      started_at:
                      - Can't be in the future
                      duration:
                      - Call can't end in the future
                      external_reference_id:
                      - A call with this external reference id was already logged
                      transcript:
                      - Must be a list of turns, each with a speaker (agent or contact)
                        and a text
                required:
                - errors
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                direction:
                  type: string
                  enum:
                  - incoming
                  - outgoing
                  example: outgoing
                started_at:
                  type: string
                  format: date-time
                  example: '2026-10-27T10:00:00Z'
                  description: ISO 8601, not in the future
                duration:
                  type: integer
                  minimum: 0
                  maximum: 86400
                  example: 95
                  description: Duration in seconds; the call cannot end in the future
                response_status:
                  type: string
                  enum:
                  - completed
                  - failed
                  - canceled
                  - no_answer
                  - busy
                  - blocked_high_risk
                  - closed_office
                  - machine_answered
                  - answered_but_busy
                  - short_duration
                  - declined
                  example: completed
                user_id:
                  type: string
                  example: 64a1b2c3d4e5f678901235fe
                  description: Vixiees user who made or took the call. Omit it when
                    no Vixiees user was involved (e.g. an AI agent)
                from:
                  type: string
                  example: "+34600000002"
                  description: Calling number, E.164. Defaults to the contact phone
                    for incoming calls
                to:
                  type: string
                  example: "+34600000001"
                  description: Called number, E.164. Defaults to the contact phone
                    for outgoing calls
                external_reference_id:
                  type: string
                  example: dialer-call-8812
                  description: Your id for this call. If a call with this id was already
                    logged for the account, the request is rejected with 422 and an
                    `external_reference_id` error, meaning the call already exists
                transcript:
                  type: array
                  description: 'What was said on the call, turn by turn, in order.
                    Up to 100000 characters in total; a longer transcript rejects
                    the whole request. Send it with the call: it cannot be added later.
                    It is stored with the call; it is not shown in the app or returned
                    by the API yet'
                  items:
                    type: object
                    properties:
                      speaker:
                        type: string
                        enum:
                        - agent
                        - contact
                        example: agent
                        description: "`agent` for whoever spoke on your behalf (a
                          person or an AI agent), `contact` for the contact"
                      text:
                        type: string
                        nullable: true
                        example: Hola, le llamo de Vixiees
                        description: Turns with an empty or null text are left out
                    required:
                    - speaker
                    - text
              required:
              - direction
              - started_at
              - duration
              - response_status
  "/contacts/{contact_id}/documents":
    parameters:
    - name: contact_id
      in: path
      required: true
      description: ID of the contact
      schema:
        type: string
    get:
      summary: Retrieves documents for a contact
      tags:
      - Contacts
      security:
      - api_key: []
      description: |
        Returns all files attached to the contact (PDFs, images, etc.).

        Each document includes a secure `url` for downloading the file.
      responses:
        '200':
          description: documents found
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        file_name:
                          type: string
                        file_size:
                          type: integer
                        file_content_type:
                          type: string
                        tag:
                          type: string
                          nullable: true
                        source:
                          type: string
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                        url:
                          type: string
        '401':
          description: unauthorized
        '404':
          description: contact not found
    post:
      summary: Uploads a document to a contact
      tags:
      - Contacts
      security:
      - api_key: []
      description: |
        Uploads a file to the contact. Maximum file size is 35MB.

        Use the `tag` parameter to categorize documents (e.g., "contract", "id", "invoice").
      parameters: []
      responses:
        '200':
          description: document created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 507f1f77bcf86cd799439011
                    description: ID of the created document
        '401':
          description: unauthorized
        '404':
          description: contact not found
        '422':
          description: unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    description: Validation errors (e.g., invalid file type or size
                      exceeds 35MB)
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    example:
                      file_content_type:
                      - is invalid
                      file_file_size:
                      - must be less than 35 MB
                required:
                - errors
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: file
        required: true
        description: The document file to upload
  "/contacts/{contact_id}/feed":
    parameters:
    - name: contact_id
      in: path
      required: true
      description: ID of the contact
      schema:
        type: string
    get:
      summary: Retrieves the activity feed for a contact
      tags:
      - Contacts
      security:
      - api_key: []
      description: |
        Returns a paginated activity feed for a contact, including calls (regular, WhatsApp and calls logged through the API), comments, tasks, emails, SMS messages, and other events.

        Items are ordered by occurrence_at descending (most recent first).
        Use subject_types[] to filter by event type, and from/to to filter by date range.
      parameters:
      - name: page
        in: query
        required: false
        description: Page number (1-based)
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: limit
        in: query
        required: false
        description: Number of items per page (max 100)
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 100
      - name: subject_types
        in: query
        required: false
        description: 'Filter by subject type(s). Valid values: Call, WhatsappCall,
          ExternalCall, Comment, Task, Sms, Email, PlaybookContactStatus, AssigneeChange,
          ContactMergeEvent, ContactCreation, DealCreation, Meeting, WorkflowLog,
          EntityUpdate. Call returns every call type (Call, WhatsappCall, ExternalCall);
          use WhatsappCall or ExternalCall to narrow it.'
        schema:
          type: array
          items:
            type: string
            enum:
            - Call
            - WhatsappCall
            - ExternalCall
            - Comment
            - Task
            - Sms
            - Email
            - PlaybookContactStatus
            - AssigneeChange
            - ContactMergeEvent
            - ContactCreation
            - DealCreation
            - Meeting
            - WorkflowLog
            - EntityUpdate
        style: form
        explode: true
      - name: from
        in: query
        required: false
        description: ISO8601 datetime — return items with occurrence_at >= from
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        description: ISO8601 datetime — return items with occurrence_at <= to
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: feed retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        subject_type:
                          type: string
                        subject_id:
                          type: string
                          nullable: true
                        occurrence_at:
                          type: string
                          format: date-time
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                        subject:
                          type: object
                          nullable: true
                          description: Serialized subject entity — shape varies by
                            subject_type (e.g. Call, WhatsappCall, ExternalCall, Comment,
                            Task, Sms, PlaybookContactStatus, etc.)
                  page_info:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      limit:
                        type: integer
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
        '404':
          description: contact not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
        '422':
          description: invalid date params
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
  "/contacts/{contact_id}/whatsapp_conversations":
    parameters:
    - name: contact_id
      in: path
      required: true
      description: ID of the contact
      schema:
        type: string
    get:
      summary: Retrieves whatsapp conversations for a contact
      tags:
      - Contacts
      security:
      - api_key: []
      description: |
        Returns the WhatsApp conversation history for a contact.

        Messages include media URLs for attachments (images, documents, audio, video).
        Both sent and received messages are included with timestamps and delivery status.

        For template messages, `message_template_body` returns the full rendered message
        (header, body and footer joined by newlines) with the template variables resolved to
        their sent values when the corresponding parameters are present, instead of raw
        `{{1}}`/`{{2}}` placeholders.
      responses:
        '200':
          description: whatsapp conversations found
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        body:
                          type: string
                        sent:
                          type: boolean
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                        from:
                          type: string
                        to:
                          type: string
                        text:
                          type: boolean
                        status:
                          type: string
                        message_type:
                          type: string
                        message_template_body:
                          type: string
                          nullable: true
                        template:
                          type: boolean
                        header_parameters:
                          type: array
                          items:
                            type: string
                          nullable: true
                        body_parameters:
                          type: array
                          items:
                            type: string
                          nullable: true
                        buttons_parameters:
                          type: array
                          items:
                            type: string
                          nullable: true
                        url_parameter:
                          type: string
                          nullable: true
                        wa_id:
                          type: string
                          nullable: true
                        reply:
                          type: boolean
                          nullable: true
                        reply_wa_id:
                          type: string
                          nullable: true
                        attachment:
                          type: boolean
                          nullable: true
                        image:
                          type: boolean
                          nullable: true
                        audio:
                          type: boolean
                          nullable: true
                        video:
                          type: boolean
                          nullable: true
                        application:
                          type: boolean
                          nullable: true
                        filename:
                          type: string
                          nullable: true
                        media_id:
                          type: string
                          nullable: true
                        media_url:
                          type: string
                          nullable: true
                        media_content_type:
                          type: string
                          nullable: true
                        voice:
                          type: boolean
                          nullable: true
                        location:
                          type: boolean
                          nullable: true
                        latitude:
                          type: number
                          format: float
                          nullable: true
                        longitude:
                          type: number
                          format: float
                          nullable: true
                        label:
                          type: string
                          nullable: true
                        address:
                          type: string
                          nullable: true
        '401':
          description: unauthorized
        '404':
          description: contact not found
  "/contacts":
    get:
      summary: Retrieves contacts
      tags:
      - Contacts
      security:
      - api_key: []
      description: |
        Returns a paginated list of contacts. Use filters to narrow results:
        - `words`: Full-text search across name, email, phone, company
        - `exact_search`: Exact match on email/phone (useful for deduplication)
        - Date filters: `created_at_from/to`, `updated_at_from/to`
        - `playbook_id`/`flow_step_id`: Restrict to contacts currently in that playbook/flow step

        **Tip:** For webhook-driven sync, filter by `updated_at` to get only changed records.
      parameters:
      - name: playbook_id
        in: query
        required: false
        description: Filter by the contact's current playbook ID. A malformed ID returns
          an empty result set rather than an error.
        schema:
          type: string
        example: 507f1f77bcf86cd799439011
      - name: flow_step_id
        in: query
        required: false
        description: Filter by the contact's current flow step ID. A malformed ID
          returns an empty result set rather than an error.
        schema:
          type: string
        example: 507f1f77bcf86cd799439012
      - name: words
        in: query
        required: false
        description: Search terms to filter contacts
        schema:
          type: string
        example: Jon Smith
      - name: exact_search
        in: query
        required: false
        description: Whether to perform an exact match search on email and phone
        schema:
          type: boolean
      - name: sort
        in: query
        required: false
        description: Sort direction (asc or desc)
        schema:
          type: string
          enum:
          - asc
          - desc
        example: desc
      - name: order_by
        in: query
        required: false
        description: Field to order results by
        schema:
          type: string
        example: created_at
      - name: page
        in: query
        required: false
        description: Page number for pagination
        schema:
          type: integer
          minimum: 1
        example: 1
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
        example: 25
      - name: created_at_from
        in: query
        required: false
        description: Filter by creation date from
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00Z'
      - name: created_at_to
        in: query
        required: false
        description: Filter by creation date to
        schema:
          type: string
          format: date-time
        example: '2024-12-31T23:59:59Z'
      - name: updated_at_from
        in: query
        required: false
        description: Filter by update date from
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00Z'
      - name: updated_at_to
        in: query
        required: false
        description: Filter by update date to
        schema:
          type: string
          format: date-time
        example: '2024-12-31T23:59:59Z'
      responses:
        '200':
          description: contacts found
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: 507f1f77bcf86cd799439011
                        first_name:
                          type: string
                          nullable: true
                          example: John
                        last_name:
                          type: string
                          nullable: true
                          example: Doe
                        second_last_name:
                          type: string
                          nullable: true
                          example: Smith
                        email:
                          type: string
                          nullable: true
                          example: john.doe@example.com
                        phone:
                          type: string
                          nullable: true
                          example: "+34627352692"
                        company_name:
                          type: string
                          nullable: true
                          example: Acme Corporation
                        additional_phones:
                          type: array
                          items:
                            type: string
                          nullable: true
                          example:
                          - "+34627352693"
                        additional_emails:
                          type: array
                          items:
                            type: string
                          nullable: true
                          example:
                          - john.doe+work@example.com
                        priority:
                          type: integer
                          nullable: true
                          example: 3
                        source:
                          type: string
                          nullable: true
                          example: api
                        country_code:
                          type: string
                          nullable: true
                          example: ES
                        language:
                          type: string
                          nullable: true
                          example: es
                        whatsapp_transactional_opt_in:
                          type: boolean
                          nullable: true
                          example: true
                        email_transactional_opt_in:
                          type: boolean
                          nullable: true
                          example: true
                        whatsapp_marketing_opt_in:
                          type: boolean
                          nullable: true
                          example: false
                        email_marketing_opt_in:
                          type: boolean
                          nullable: true
                          example: false
                        external_reference_id:
                          type: string
                          nullable: true
                          example: EXT-12345
                        external_reference_url:
                          type: string
                          nullable: true
                          example: https://external-system.com/contacts/12345
                        ignored:
                          type: boolean
                          nullable: true
                          example: false
                        is_client:
                          type: boolean
                          nullable: true
                          example: false
                        last_close_won_reason:
                          type: string
                          nullable: true
                          example: Product demo convinced them
                        last_close_lost_reason:
                          type: string
                          nullable: true
                          example: Budget constraints
                        skills:
                          type: array
                          items:
                            type: string
                          nullable: true
                          example:
                          - spanish
                          - english
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                          example: '2023-01-15T10:30:00Z'
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                          example: '2023-01-15T14:30:00Z'
                        title:
                          type: string
                          nullable: true
                          example: John Doe
                        closed_won_reason:
                          type: string
                          nullable: true
                          example: Product demo convinced them
                        closed_lost_reason:
                          type: string
                          nullable: true
                          example: Budget constraints
                        custom_attributes:
                          type: array
                          items:
                            type: object
                            properties:
                              field_name:
                                type: string
                                example: industry
                              value:
                                type: string
                                example: Technology
                          nullable: true
                  page_info:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        nullable: true
                      limit:
                        type: integer
                        nullable: true
        '401':
          description: unauthorized
    post:
      summary: Creates a new contact
      tags:
      - Contacts
      security:
      - api_key: []
      description: |
        Creates a new contact. At least one of `email` or `phone` is required for WhatsApp/email communication.

        Optionally assign the contact to a playbook, flow step, and user at creation time.
      parameters: []
      responses:
        '200':
          description: contact created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        '401':
          description: unauthorized
        '422':
          description: unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  example: John
                  description: Contact first name
                last_name:
                  type: string
                  example: Doe
                  description: Contact last name
                second_last_name:
                  type: string
                  example: Smith
                  description: Contact second last name
                email:
                  type: string
                  example: john.doe@example.com
                  description: Contact email address
                phone:
                  type: string
                  example: "+34627352692"
                  description: Contact phone number
                company_name:
                  type: string
                  example: Acme Corporation
                  description: Company name
                additional_phones:
                  type: array
                  items:
                    type: string
                  example:
                  - "+34627352693"
                  - "+34627352694"
                  description: Additional phone numbers
                additional_emails:
                  type: array
                  items:
                    type: string
                  example:
                  - john.doe+work@example.com
                  - j.doe@company.com
                  description: Additional email addresses
                source:
                  type: string
                  example: api
                  description: Contact source
                  enum:
                  - manual
                  - csv
                  - api
                  - call
                  - whatsapp
                  - email
                  - crm
                country_code:
                  type: string
                  example: ES
                  description: Country code (ISO 3166-1 alpha-2)
                language:
                  type: string
                  example: es
                  description: Language code (ISO 639-1)
                whatsapp_transactional_opt_in:
                  type: boolean
                  example: true
                  description: WhatsApp transactional messages opt-in
                email_transactional_opt_in:
                  type: boolean
                  example: true
                  description: Email transactional messages opt-in
                whatsapp_marketing_opt_in:
                  type: boolean
                  example: false
                  description: WhatsApp marketing messages opt-in
                email_marketing_opt_in:
                  type: boolean
                  example: false
                  description: Email marketing messages opt-in
                external_reference_id:
                  type: string
                  example: EXT-12345
                  description: External system reference ID
                external_reference_url:
                  type: string
                  example: https://external-system.com/contacts/12345
                  description: External system reference URL
                skills:
                  type: array
                  items:
                    type: string
                  example:
                  - spanish
                  - english
                  - sales
                  description: Contact skills
                custom_attributes:
                  type: array
                  items:
                    type: object
                    properties:
                      field_name:
                        type: string
                        example: industry
                      value:
                        type: string
                        example: Technology
                  nullable: true
                playbook_id:
                  type: string
                  example: 507f1f77bcf86cd799439011
                  description: ID of playbook to assign
                flow_step_id:
                  type: string
                  example: 507f1f77bcf86cd799439012
                  description: ID of flow step to assign
                assignee_id:
                  type: string
                  example: 507f1f77bcf86cd799439013
                  description: ID of user to assign as contact owner
              description: Contact creation parameters. Either email or phone is required.
  "/contacts/{id}":
    get:
      summary: Retrieves a specific contact
      tags:
      - Contacts
      security:
      - api_key: []
      description: |
        Returns a single contact with all fields including custom attributes.

        You can use either the internal ID or the `external_reference_id` to retrieve the contact.
      parameters:
      - name: id
        in: path
        required: true
        description: The ID or external reference ID of the contact to retrieve
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      responses:
        '200':
          description: contact found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 507f1f77bcf86cd799439011
                  first_name:
                    type: string
                    nullable: true
                    example: John
                  last_name:
                    type: string
                    nullable: true
                    example: Doe
                  second_last_name:
                    type: string
                    nullable: true
                    example: Smith
                  email:
                    type: string
                    nullable: true
                    example: john.doe@example.com
                  phone:
                    type: string
                    nullable: true
                    example: "+34627352692"
                  company_name:
                    type: string
                    nullable: true
                    example: Acme Corporation
                  additional_phones:
                    type: array
                    items:
                      type: string
                    nullable: true
                    example:
                    - "+34627352693"
                  additional_emails:
                    type: array
                    items:
                      type: string
                    nullable: true
                    example:
                    - john.doe+work@example.com
                  source:
                    type: string
                    nullable: true
                    example: api
                  country_code:
                    type: string
                    nullable: true
                    example: ES
                  language:
                    type: string
                    nullable: true
                    example: es
                  whatsapp_transactional_opt_in:
                    type: boolean
                    nullable: true
                    example: true
                  email_transactional_opt_in:
                    type: boolean
                    nullable: true
                    example: true
                  whatsapp_marketing_opt_in:
                    type: boolean
                    nullable: true
                    example: false
                  email_marketing_opt_in:
                    type: boolean
                    nullable: true
                    example: false
                  external_reference_id:
                    type: string
                    nullable: true
                    example: EXT-12345
                  external_reference_url:
                    type: string
                    nullable: true
                    example: https://external-system.com/contacts/12345
                  skills:
                    type: array
                    items:
                      type: string
                    nullable: true
                    example:
                    - spanish
                    - english
                  custom_attributes:
                    type: array
                    items:
                      type: object
                      properties:
                        field_name:
                          type: string
                          example: industry
                        value:
                          type: string
                          example: Technology
                    nullable: true
        '401':
          description: unauthorized
        '404':
          description: contact not found
    delete:
      summary: Deletes a contact
      tags:
      - Contacts
      security:
      - api_key: []
      description: 'Deletes a contact. All associated tasks and deals will be preserved
        but no longer visible in the app.

        '
      parameters:
      - name: id
        in: path
        required: true
        description: The ID or external reference ID of the contact to delete
        schema:
          type: string
      responses:
        '200':
          description: contact deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
        '401':
          description: unauthorized
        '404':
          description: contact not found
    put:
      summary: Updates a contact
      tags:
      - Contacts
      security:
      - api_key: []
      description: |
        Partial update of a contact. Only provided fields are modified; omitted fields remain unchanged.

        Custom attributes can be updated by including them in the `custom_attributes` array.
      parameters:
      - name: id
        in: path
        required: true
        description: The ID or external reference ID of the contact to update
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      responses:
        '200':
          description: contact updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 507f1f77bcf86cd799439011
                  first_name:
                    type: string
                    nullable: true
                    example: John
                  last_name:
                    type: string
                    nullable: true
                    example: Doe
                  second_last_name:
                    type: string
                    nullable: true
                    example: Smith
                  email:
                    type: string
                    nullable: true
                    example: john.doe@example.com
                  phone:
                    type: string
                    nullable: true
                    example: "+34627352692"
                  company_name:
                    type: string
                    nullable: true
                    example: Acme Corporation
                  additional_phones:
                    type: array
                    items:
                      type: string
                    nullable: true
                    example:
                    - "+34627352693"
                  additional_emails:
                    type: array
                    items:
                      type: string
                    nullable: true
                    example:
                    - john.doe+work@example.com
                  priority:
                    type: integer
                    nullable: true
                    example: 3
                  source:
                    type: string
                    nullable: true
                    example: api
                  country_code:
                    type: string
                    nullable: true
                    example: ES
                  language:
                    type: string
                    nullable: true
                    example: es
                  whatsapp_transactional_opt_in:
                    type: boolean
                    nullable: true
                    example: true
                  email_transactional_opt_in:
                    type: boolean
                    nullable: true
                    example: true
                  whatsapp_marketing_opt_in:
                    type: boolean
                    nullable: true
                    example: false
                  email_marketing_opt_in:
                    type: boolean
                    nullable: true
                    example: false
                  external_reference_id:
                    type: string
                    nullable: true
                    example: EXT-12345
                  external_reference_url:
                    type: string
                    nullable: true
                    example: https://external-system.com/contacts/12345
                  ignored:
                    type: boolean
                    nullable: true
                    example: false
                  is_client:
                    type: boolean
                    nullable: true
                    example: false
                  last_close_won_reason:
                    type: string
                    nullable: true
                    example: Product demo convinced them
                  last_close_lost_reason:
                    type: string
                    nullable: true
                    example: Budget constraints
                  skills:
                    type: array
                    items:
                      type: string
                    nullable: true
                    example:
                    - spanish
                    - english
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                    example: '2023-01-15T10:30:00Z'
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                    example: '2023-01-15T14:30:00Z'
                  title:
                    type: string
                    nullable: true
                    example: John Doe
                  closed_won_reason:
                    type: string
                    nullable: true
                    example: Product demo convinced them
                  closed_lost_reason:
                    type: string
                    nullable: true
                    example: Budget constraints
                  custom_attributes:
                    type: array
                    items:
                      type: object
                      properties:
                        field_name:
                          type: string
                          example: industry
                        value:
                          type: string
                          example: Technology
                    nullable: true
        '401':
          description: unauthorized
        '404':
          description: contact not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  example: John
                  description: Contact first name
                last_name:
                  type: string
                  example: Doe
                  description: Contact last name
                second_last_name:
                  type: string
                  example: Smith
                  description: Contact second last name
                email:
                  type: string
                  example: john.doe@example.com
                  description: Contact email address
                phone:
                  type: string
                  example: "+34627352692"
                  description: Contact phone number
                company_name:
                  type: string
                  example: Acme Corporation
                  description: Company name
                additional_phones:
                  type: array
                  items:
                    type: string
                  example:
                  - "+34627352693"
                  - "+34627352694"
                  description: Additional phone numbers
                additional_emails:
                  type: array
                  items:
                    type: string
                  example:
                  - john.doe+work@example.com
                  - j.doe@company.com
                  description: Additional email addresses
                priority:
                  type: integer
                  example: 3
                  description: Contact priority (1-5)
                  enum:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                source:
                  type: string
                  example: api
                  description: Contact source
                  enum:
                  - manual
                  - csv
                  - api
                  - call
                  - whatsapp
                  - email
                  - crm
                country_code:
                  type: string
                  example: ES
                  description: Country code (ISO 3166-1 alpha-2)
                language:
                  type: string
                  example: es
                  description: Language code (ISO 639-1)
                whatsapp_transactional_opt_in:
                  type: boolean
                  example: true
                  description: WhatsApp transactional messages opt-in
                email_transactional_opt_in:
                  type: boolean
                  example: true
                  description: Email transactional messages opt-in
                whatsapp_marketing_opt_in:
                  type: boolean
                  example: false
                  description: WhatsApp marketing messages opt-in
                email_marketing_opt_in:
                  type: boolean
                  example: false
                  description: Email marketing messages opt-in
                external_reference_id:
                  type: string
                  example: EXT-12345
                  description: External system reference ID
                external_reference_url:
                  type: string
                  example: https://external-system.com/contacts/12345
                  description: External system reference URL
                skills:
                  type: array
                  items:
                    type: string
                  example:
                  - spanish
                  - english
                  - sales
                  description: Contact skills
                custom_attributes:
                  type: array
                  items:
                    type: object
                    properties:
                      field_name:
                        type: string
                        example: industry
                      value:
                        type: string
                        example: Technology
                  nullable: true
              description: Contact update parameters. All fields are optional.
  "/contacts/{id}/update_current_playbook":
    post:
      summary: Updates a contact's current playbook
      tags:
      - Contacts
      security:
      - api_key: []
      description: |
        Moves a contact to a different playbook and/or flow step.

        Use this to progress contacts through your sales pipeline or reassign them to different workflows.
        Optionally update contact fields at the same time using `contact_required_fields`.
      parameters:
      - name: id
        in: path
        required: true
        description: The ID or external reference ID of the contact
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      responses:
        '200':
          description: playbook updated with contact required fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 507f1f77bcf86cd799439011
                  first_name:
                    type: string
                    nullable: true
                    example: John
                  last_name:
                    type: string
                    nullable: true
                    example: Doe
                  second_last_name:
                    type: string
                    nullable: true
                    example: Smith
                  email:
                    type: string
                    nullable: true
                    example: john.doe@example.com
                  phone:
                    type: string
                    nullable: true
                    example: "+34627352692"
                  company_name:
                    type: string
                    nullable: true
                    example: Acme Corporation
                  additional_phones:
                    type: array
                    items:
                      type: string
                    nullable: true
                    example:
                    - "+34627352693"
                  additional_emails:
                    type: array
                    items:
                      type: string
                    nullable: true
                    example:
                    - john.doe+work@example.com
                  priority:
                    type: integer
                    nullable: true
                    example: 3
                  source:
                    type: string
                    nullable: true
                    example: api
                  country_code:
                    type: string
                    nullable: true
                    example: ES
                  language:
                    type: string
                    nullable: true
                    example: es
                  whatsapp_transactional_opt_in:
                    type: boolean
                    nullable: true
                    example: true
                  email_transactional_opt_in:
                    type: boolean
                    nullable: true
                    example: true
                  whatsapp_marketing_opt_in:
                    type: boolean
                    nullable: true
                    example: false
                  email_marketing_opt_in:
                    type: boolean
                    nullable: true
                    example: false
                  external_reference_id:
                    type: string
                    nullable: true
                    example: EXT-12345
                  external_reference_url:
                    type: string
                    nullable: true
                    example: https://external-system.com/contacts/12345
                  ignored:
                    type: boolean
                    nullable: true
                    example: false
                  is_client:
                    type: boolean
                    nullable: true
                    example: false
                  last_close_won_reason:
                    type: string
                    nullable: true
                    example: Product demo convinced them
                  last_close_lost_reason:
                    type: string
                    nullable: true
                    example: Budget constraints
                  skills:
                    type: array
                    items:
                      type: string
                    nullable: true
                    example:
                    - spanish
                    - english
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                    example: '2023-01-15T10:30:00Z'
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                    example: '2023-01-15T14:30:00Z'
                  title:
                    type: string
                    nullable: true
                    example: John Doe
                  closed_won_reason:
                    type: string
                    nullable: true
                    example: Product demo convinced them
                  closed_lost_reason:
                    type: string
                    nullable: true
                    example: Budget constraints
                  custom_attributes:
                    type: array
                    items:
                      type: object
                      properties:
                        field_name:
                          type: string
                          example: industry
                        value:
                          type: string
                          example: Technology
                    nullable: true
        '401':
          description: unauthorized
        '404':
          description: contact not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                playbook_id:
                  type: string
                  example: 64a1b2c3d4e5f678901234cd
                flow_step_id:
                  type: string
                  example: 64a1b2c3d4e5f678901234ef
                contact_required_fields:
                  type: array
                  description: Optional array of contact fields to update along with
                    the playbook change
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                        description: Field name (can be a contact attribute or custom
                          attribute)
                        example: custom_field_name
                      value:
                        type: string
                        description: Field value
                        example: custom_value
                    required:
                    - key
                    - value
                  example:
                  - key: custom_field_name
                    value: custom_value
              required:
              - playbook_id
  "/contacts/{id}/assign_user":
    post:
      summary: Assigns a user to a contact
      tags:
      - Contacts
      security:
      - api_key: []
      description: |
        Assigns a team member to be the owner of this contact.

        The assigned user will see this contact in their task queue and receive notifications.
      parameters:
      - name: id
        in: path
        required: true
        description: The ID or external reference ID of the contact
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      responses:
        '200':
          description: user assigned
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        '401':
          description: unauthorized
        '404':
          description: contact not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                assignee_id:
                  type: string
                  example: 64a1b2c3d4e5f678901234gh
              required:
              - assignee_id
  "/contacts/{id}/add_comment":
    post:
      summary: Adds a comment to a contact
      tags:
      - Contacts
      security:
      - api_key: []
      description: |
        Adds a comment to a contact's activity feed.

        Comments are visible in the contact timeline and can be synced to integrated CRMs (Hubspot, Pipedrive).
      parameters:
      - name: id
        in: path
        required: true
        description: The ID or external reference ID of the contact
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      responses:
        '200':
          description: comment added
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the created comment
        '401':
          description: unauthorized
        '404':
          description: contact not found
        '422':
          description: validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  description: The comment text
                  example: Called the contact, left voicemail.
              required:
              - content
  "/contracts":
    get:
      summary: Retrieves contracts
      tags:
      - Contracts
      security:
      - api_key: []
      description: |
        Returns a paginated list of contract documents.

        Contracts track agreements with clients including status, start/end dates.
      parameters:
      - name: page
        in: query
        required: false
        description: Page number for pagination
        schema:
          type: integer
          default: 1
          minimum: 1
        example: 1
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 100
        example: 25
      - name: order_by
        in: query
        required: false
        description: Field to order results by
        schema:
          type: string
          default: created_at
        example: created_at
      - name: sort
        in: query
        required: false
        description: Sort direction (asc or desc)
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
        example: desc
      responses:
        '200':
          description: contracts found
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        name:
                          type: string
                          nullable: true
                        status:
                          type: string
                          nullable: true
                        start_date:
                          type: string
                          format: date-time
                          nullable: true
                        end_date:
                          type: string
                          format: date-time
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  page_info:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        nullable: true
                      limit:
                        type: integer
                        nullable: true
        '401':
          description: unauthorized
  "/dashboard/leaderboard":
    get:
      summary: Retrieves dashboard leaderboard
      tags:
      - Dashboard
      security:
      - api_key: []
      description: |
        Returns per-agent performance metrics for a given playbook and time period.
        Includes contact metrics, task metrics, call metrics, WhatsApp metrics, agent status, and rankings.
      parameters:
      - name: playbook_id
        in: query
        required: true
        description: ID of the playbook to filter by
        schema:
          type: string
        example: 507f1f77bcf86cd799439011
      - name: period
        in: query
        required: false
        description: Time period (e.g. this_week, this_month, last_week, last_month,
          last_two_months, last_7_days, last_14_days, last_30_days, custom)
        schema:
          type: string
        example: this_week
      - name: start_date
        in: query
        required: false
        description: Start date for custom period (ISO 8601)
        schema:
          type: string
          format: date
        example: '2024-01-01'
      - name: end_date
        in: query
        required: false
        description: End date for custom period (ISO 8601)
        schema:
          type: string
          format: date
        example: '2024-01-31'
      responses:
        '200':
          description: leaderboard data returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  top_metrics:
                    type: array
                    items:
                      type: object
                  users:
                    type: array
                    items:
                      type: object
                      properties:
                        user:
                          type: object
                          properties:
                            id:
                              type: string
                              example: 507f1f77bcf86cd799439011
                            full_name:
                              type: string
                              example: Alice Smith
                            email:
                              type: string
                              example: alice@example.com
                        contacted_count:
                          type: integer
                          example: 5
                        won_count:
                          type: integer
                          example: 2
                        conversion_rate:
                          type: number
                          example: 40.0
                        tasks_count:
                          type: integer
                          example: 10
                        task_time:
                          type: integer
                          example: 600
                          description: Total task time in seconds
                        calls_count:
                          type: integer
                          example: 8
                        calls_answered:
                          type: integer
                          example: 6
                        call_time:
                          type: integer
                          example: 1800
                          description: Total call time in seconds
                        whatsapp_messages_sent:
                          type: integer
                          example: 3
                        status:
                          type: string
                          nullable: true
                          example: available
                        status_since:
                          type: string
                          format: date-time
                          nullable: true
                        last_task_completed_at:
                          type: string
                          format: date-time
                          nullable: true
                        last_call_ended_at:
                          type: string
                          format: date-time
                          nullable: true
                        contacted_rank:
                          type: integer
                          nullable: true
                          example: 1
                        won_rank:
                          type: integer
                          nullable: true
                          example: 1
                        conversion_rank:
                          type: integer
                          nullable: true
                          example: 1
                        tasks_rank:
                          type: integer
                          nullable: true
                          example: 1
                  averages:
                    type: object
                  status_summary:
                    type: object
        '401':
          description: unauthorized
        '404':
          description: playbook not found or playbook_id missing
        '422':
          description: date range exceeds limit
  "/dashboard/overview":
    get:
      summary: Retrieves dashboard overview stats
      tags:
      - Dashboard
      security:
      - api_key: []
      description: |
        Returns aggregated KPI metrics for a given playbook and time period.
        Each metric includes current value, previous period value, and the difference.
      parameters:
      - name: playbook_id
        in: query
        required: true
        description: ID of the playbook to filter by
        schema:
          type: string
        example: 507f1f77bcf86cd799439011
      - name: period
        in: query
        required: false
        description: Time period (e.g. this_week, this_month, last_week, last_month,
          last_two_months, last_7_days, last_14_days, last_30_days, custom)
        schema:
          type: string
        example: this_month
      - name: start_date
        in: query
        required: false
        description: Start date for custom period (ISO 8601)
        schema:
          type: string
          format: date
        example: '2024-01-01'
      - name: end_date
        in: query
        required: false
        description: End date for custom period (ISO 8601)
        schema:
          type: string
          format: date
        example: '2024-01-31'
      responses:
        '200':
          description: overview stats returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  new_contacts:
                    "$ref": "#/components/schemas/MetricComparison"
                  active_contacts:
                    "$ref": "#/components/schemas/MetricComparison"
                  won_contacts:
                    "$ref": "#/components/schemas/MetricComparison"
                  lost_contacts:
                    "$ref": "#/components/schemas/MetricComparison"
                  stale_contacts:
                    "$ref": "#/components/schemas/MetricComparison"
        '401':
          description: unauthorized
        '404':
          description: playbook not found or playbook_id missing
        '422':
          description: date range exceeds limit
  "/dashboard/pending_tasks":
    get:
      summary: Retrieves dashboard tasks distribution
      tags:
      - Dashboard
      security:
      - api_key: []
      description: |
        Returns task data for a given playbook, including summary cards,
        hourly distribution, and a breakdown by user and task type.
        Each breakdown entry includes both pending and completed counts.
      parameters:
      - name: playbook_id
        in: query
        required: true
        description: ID of the playbook to filter by
        schema:
          type: string
        example: 507f1f77bcf86cd799439011
      responses:
        '200':
          description: tasks data returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary_cards:
                    type: object
                    properties:
                      total_pending_today:
                        type: integer
                        example: 10
                      active_now:
                        type: integer
                        example: 3
                      scheduled_today:
                        type: integer
                        example: 5
                      priority_1_total:
                        type: integer
                        example: 2
                      total_completed:
                        type: integer
                        example: 0
                  hourly_distribution:
                    type: array
                    items:
                      type: object
                      properties:
                        hour:
                          type: string
                          example: '09:00'
                        count:
                          type: integer
                          example: 4
                        is_current_hour:
                          type: boolean
                          example: false
                        is_high_activity:
                          type: boolean
                          example: true
                  by_user:
                    type: array
                    items:
                      type: object
                      properties:
                        user_id:
                          type: string
                          example: 507f1f77bcf86cd799439011
                        user_name:
                          type: string
                          nullable: true
                          example: Ana García
                        user_initials:
                          type: string
                          nullable: true
                          example: AG
                        total_pending:
                          type: integer
                          example: 7
                        total_completed:
                          type: integer
                          example: 3
                        task_types:
                          type: array
                          items:
                            type: object
                            properties:
                              task_template_id:
                                type: string
                                example: 507f1f77bcf86cd799439012
                              task_template_identifier:
                                type: string
                                example: Follow up
                              priority:
                                type: integer
                                example: 1
                              pending_count:
                                type: integer
                                example: 7
                              completed_count:
                                type: integer
                                example: 3
                  by_task_type:
                    type: array
                    items:
                      type: object
                      properties:
                        task_template_id:
                          type: string
                          example: 507f1f77bcf86cd799439012
                        task_template_identifier:
                          type: string
                          example: Follow up
                        priority:
                          type: integer
                          example: 1
                        total_pending:
                          type: integer
                          example: 7
                        total_completed:
                          type: integer
                          example: 3
                        users:
                          type: array
                          items:
                            type: object
                            properties:
                              user_id:
                                type: string
                                example: 507f1f77bcf86cd799439011
                              user_name:
                                type: string
                                nullable: true
                                example: Ana García
                              user_initials:
                                type: string
                                nullable: true
                                example: AG
                              pending_count:
                                type: integer
                                example: 7
                              completed_count:
                                type: integer
                                example: 3
        '401':
          description: unauthorized
        '404':
          description: playbook not found or playbook_id missing
  "/dashboard/statuses":
    get:
      summary: Retrieves dashboard flow step transitions
      tags:
      - Dashboard
      security:
      - api_key: []
      description: |
        Returns contact transitions between flow steps (estados) for a given playbook and time period.
        Transitions are stored as daily totals. The period picks whole days (relative periods such as today are
        worked out in the account's time zone); transitions near midnight can fall on the adjacent day.
        Each entry shows the source state, destination state, number of transitions, and current contacts in destination.
      parameters:
      - name: playbook_id
        in: query
        required: true
        description: ID of the playbook to filter by
        schema:
          type: string
        example: 507f1f77bcf86cd799439011
      - name: period
        in: query
        required: false
        description: Time period. custom requires start_date and end_date; other periods
          ignore the dates. If omitted, it becomes custom when start_date and/or end_date
          are sent (a missing date becomes today in the account's time zone), otherwise
          today.
        schema:
          type: string
          enum:
          - today
          - yesterday
          - this_week
          - last_week
          - this_month
          - last_month
          - last_two_months
          - last_7_days
          - last_14_days
          - last_30_days
          - last_60_days
          - custom
        example: today
      - name: start_date
        in: query
        required: false
        description: Start date (ISO 8601). Required when period is custom, ignored
          by other periods. Must be on or before end_date when both are sent.
        schema:
          type: string
          format: date
        example: '2024-01-01'
      - name: end_date
        in: query
        required: false
        description: End date (ISO 8601). Required when period is custom, ignored
          by other periods. Must be on or after start_date when both are sent.
        schema:
          type: string
          format: date
        example: '2024-01-31'
      responses:
        '200':
          description: statuses transitions returned
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    estado_origen:
                      type: string
                      example: Lead
                    estado_destino:
                      type: string
                      example: Contactado
                    transiciones:
                      type: integer
                      example: 15
                    contactos:
                      type: integer
                      example: 42
        '401':
          description: unauthorized
        '404':
          description: playbook not found or playbook_id missing
        '422':
          description: invalid period or date range
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
  "/dashboard/playbook_value":
    get:
      summary: Retrieves all playbook value dashboard data in one request
      tags:
      - Dashboard
      security:
      - api_key: []
      description: |
        Returns playbook value dashboard data in a single request: salesperson rows with flow step
        breakdown, global totals, and flow step metadata ordered by position.
        All views (table, scatter, bar chart) are derived client-side from this response.
      parameters:
      - name: playbook_id
        in: query
        required: true
        description: ID of the playbook to filter by
        schema:
          type: string
        example: 507f1f77bcf86cd799439011
      responses:
        '200':
          description: playbook value data returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  rows:
                    type: array
                    items:
                      type: object
                      properties:
                        user:
                          type: object
                          properties:
                            id:
                              type: string
                            full_name:
                              type: string
                            email:
                              type: string
                            initials:
                              type: string
                        total_contacts:
                          type: integer
                        total_amount:
                          type: number
                        average_ticket:
                          type: number
                        flow_steps:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              won:
                                type: boolean
                              lost:
                                type: boolean
                              contacts:
                                type: integer
                              amount:
                                type: number
                  totals:
                    type: object
                    properties:
                      total_contacts:
                        type: integer
                      open_contacts:
                        type: integer
                      won_contacts:
                        type: integer
                      total_amount:
                        type: number
                      average_ticket:
                        type: number
                      won_this_month_amount:
                        type: number
                  flow_steps:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        won:
                          type: boolean
                        lost:
                          type: boolean
                        position:
                          type: integer
                        contacts:
                          type: integer
                        amount:
                          type: number
                        won_this_month_amount:
                          type: number
                  won_month:
                    type: string
                    format: date
                    example: '2026-06-01'
        '401':
          description: unauthorized
        '404':
          description: playbook not found
  "/deals":
    get:
      summary: Retrieves deals
      tags:
      - Deals
      security:
      - api_key: []
      description: |
        Returns a paginated list of deals. Filter by contact, assignee, status, amount range, or creation/update/close date range.

        Query params that are not supported filters for this endpoint are rejected with a 400 error.

        Use `order_by` and `sort` to control result ordering (default: created_at desc).

        To read a deal's custom attribute values, use `GET /deals/{id}`.
      parameters:
      - name: page
        in: query
        required: false
        description: Page number for pagination
        schema:
          type: integer
          default: 1
          minimum: 1
        example: 1
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 100
        example: 25
      - name: order_by
        in: query
        required: false
        description: Field to order results by
        schema:
          type: string
          default: created_at
        example: created_at
      - name: sort
        in: query
        required: false
        description: Sort direction (asc or desc)
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
        example: desc
      - name: contact_id
        in: query
        required: false
        description: Filter deals by the ID of their contact
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      - name: assignee_id
        in: query
        required: false
        description: Filter deals by the ID of their assigned user
        schema:
          type: string
        example: 64a1b2c3d5e5f678901234ab
      - name: status
        in: query
        required: false
        description: Filter deals by status
        schema:
          type: string
          enum:
          - open
          - won
          - lost
        example: open
      - name: won
        in: query
        required: false
        description: Filter deals by whether they are won
        schema:
          type: boolean
        example: false
      - name: closed
        in: query
        required: false
        description: Filter deals by whether they are closed
        schema:
          type: boolean
        example: false
      - name: amount_min
        in: query
        required: false
        description: Filter deals with an amount greater than or equal to this value
        schema:
          type: number
        example: 1000
      - name: amount_max
        in: query
        required: false
        description: Filter deals with an amount less than or equal to this value
        schema:
          type: number
        example: 5000
      - name: created_at_from
        in: query
        required: false
        description: Filter deals created at or after this date
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00Z'
      - name: created_at_to
        in: query
        required: false
        description: Filter deals created at or before this date
        schema:
          type: string
          format: date-time
        example: '2024-12-31T23:59:59Z'
      - name: updated_at_from
        in: query
        required: false
        description: Filter deals updated at or after this date
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00Z'
      - name: updated_at_to
        in: query
        required: false
        description: Filter deals updated at or before this date
        schema:
          type: string
          format: date-time
        example: '2024-12-31T23:59:59Z'
      - name: close_date_from
        in: query
        required: false
        description: Filter deals with a close date at or after this date
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00Z'
      - name: close_date_to
        in: query
        required: false
        description: Filter deals with a close date at or before this date
        schema:
          type: string
          format: date-time
        example: '2024-12-31T23:59:59Z'
      responses:
        '200':
          description: deals found
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                          nullable: true
                        description:
                          type: string
                          nullable: true
                        status:
                          type: string
                          enum:
                          - open
                          - won
                          - lost
                        won:
                          type: boolean
                        closed:
                          type: boolean
                        amount:
                          type: number
                          nullable: true
                        close_date:
                          type: string
                          format: date-time
                          nullable: true
                        contact_id:
                          type: string
                        assignee_id:
                          type: string
                          nullable: true
                        closer_id:
                          type: string
                          nullable: true
                        external_reference_id:
                          type: string
                          nullable: true
                        closed_won_reason:
                          type: string
                          nullable: true
                        closed_lost_reason:
                          type: string
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  page_info:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        nullable: true
                      limit:
                        type: integer
                        nullable: true
        '400':
          description: unsupported filter param
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      base:
                        type: string
                      unsupported_params:
                        type: array
                        items:
                          type: string
                        description: Query params that are not supported filters
                    required:
                    - base
                required:
                - errors
        '401':
          description: unauthorized
    post:
      summary: Creates a new deal
      tags:
      - Deals
      security:
      - api_key: []
      description: |
        Creates a new deal linked to a contact.

        A deal tracks a sales opportunity with an optional amount and description.

        `contact_id` accepts either the Vixiees contact ID or the contact's `external_reference_id`.

        Use `external_reference_id` to link the deal to its record in an external system (e.g. your CRM).
        It must be unique per account: creating a second deal with the same `external_reference_id`
        returns a 422 error, and the deal can later be retrieved or updated using that value in place of its ID.
      parameters: []
      responses:
        '200':
          description: deal created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the created deal
        '401':
          description: unauthorized
        '422':
          description: unprocessable entity
        '404':
          description: contact not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: Software License Deal
                description:
                  type: string
                  example: Annual license renewal for 50 seats
                amount:
                  type: number
                  example: 25000.0
                contact_id:
                  type: string
                  example: 64a1b2c3d4e5f678901234ab
                  description: Vixiees contact ID or the contact external_reference_id
                assignee_id:
                  type: string
                  example: 64a1b2c3d5e5f678901234ab
                external_reference_id:
                  type: string
                  example: EXT-12345
                  description: External system reference ID, unique per account
                custom_attributes:
                  type: array
                  items:
                    type: object
                    properties:
                      field_name:
                        type: string
                        example: industry
                      value:
                        type: string
                        example: Technology
                  nullable: true
                  description: Custom attribute values. Each field_name must match
                    a deal custom attribute defined in the account.
              required:
              - contact_id
  "/deals/{id}":
    get:
      summary: Retrieves a deal
      tags:
      - Deals
      security:
      - api_key: []
      description: |
        Returns a single deal with all fields, including its custom attributes.

        You can use either the internal ID or the `external_reference_id` to retrieve the deal,
        which makes this endpoint suitable for checking whether a deal from an external system already exists.
      parameters:
      - name: id
        in: path
        required: true
        description: The ID or external_reference_id of the deal to retrieve
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      responses:
        '200':
          description: deal found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  title:
                    type: string
                    nullable: true
                  description:
                    type: string
                    nullable: true
                  status:
                    type: string
                    enum:
                    - open
                    - won
                    - lost
                  won:
                    type: boolean
                  closed:
                    type: boolean
                  amount:
                    type: number
                    nullable: true
                  close_date:
                    type: string
                    format: date-time
                    nullable: true
                  contact_id:
                    type: string
                  assignee_id:
                    type: string
                    nullable: true
                  closer_id:
                    type: string
                    nullable: true
                  external_reference_id:
                    type: string
                    nullable: true
                  closed_won_reason:
                    type: string
                    nullable: true
                  closed_lost_reason:
                    type: string
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                  custom_attributes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        field_name:
                          type: string
                          example: industry
                        humanized_name:
                          type: string
                          nullable: true
                          example: Industry
                        field_type:
                          type: string
                          example: string
                        string_value:
                          type: string
                          nullable: true
                          example: Technology
                        integer_value:
                          type: integer
                          nullable: true
                        float_value:
                          type: number
                          nullable: true
                        date_value:
                          type: string
                          format: date-time
                          nullable: true
                        boolean_value:
                          type: boolean
                          nullable: true
                        array_value:
                          type: array
                          items:
                            type: string
                          nullable: true
                        editable:
                          type: boolean
                        nullable:
                          type: boolean
                          nullable: true
                    description: The value is stored in the *_value field matching
                      field_type (e.g. string_value for string attributes).
        '401':
          description: unauthorized
        '404':
          description: deal not found
    put:
      summary: Updates a deal
      tags:
      - Deals
      security:
      - api_key: []
      description: |
        Updates a deal's amount, status, close date, or other fields.

        Only provided fields are modified; omitted fields remain unchanged.

        You can use either the internal ID or the `external_reference_id` to identify the deal.
      parameters:
      - name: id
        in: path
        required: true
        description: The ID or external_reference_id of the deal to update
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      responses:
        '200':
          description: deal updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  title:
                    type: string
                    nullable: true
                  description:
                    type: string
                    nullable: true
                  status:
                    type: string
                    enum:
                    - open
                    - won
                    - lost
                  won:
                    type: boolean
                  closed:
                    type: boolean
                  amount:
                    type: number
                    nullable: true
                  close_date:
                    type: string
                    format: date-time
                    nullable: true
                  contact_id:
                    type: string
                  assignee_id:
                    type: string
                    nullable: true
                  closer_id:
                    type: string
                    nullable: true
                  external_reference_id:
                    type: string
                    nullable: true
                  closed_won_reason:
                    type: string
                    nullable: true
                  closed_lost_reason:
                    type: string
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '401':
          description: unauthorized
        '404':
          description: deal not found
        '422':
          description: unprocessable entity
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: Updated Deal Title
                description:
                  type: string
                  example: Annual license renewal for 50 seats
                status:
                  type: string
                  enum:
                  - open
                  - won
                  - lost
                  example: won
                amount:
                  type: number
                  example: 30000.0
                close_date:
                  type: string
                  format: date-time
                  example: '2024-12-31T23:59:59Z'
                assignee_id:
                  type: string
                  example: 64a1b2c3d5e5f678901234ab
                external_reference_id:
                  type: string
                  example: EXT-12345
                  description: External system reference ID, unique per account
                custom_attributes:
                  type: array
                  items:
                    type: object
                    properties:
                      field_name:
                        type: string
                        example: industry
                      value:
                        type: string
                        example: Technology
                  nullable: true
                  description: Custom attribute values. Each field_name must match
                    a deal custom attribute defined in the account.
    delete:
      summary: Deletes a deal
      tags:
      - Deals
      security:
      - api_key: []
      description: Deletes a deal. You can use either the internal ID or the `external_reference_id`
        to identify the deal.
      parameters:
      - name: id
        in: path
        required: true
        description: The ID or external_reference_id of the deal to delete
        schema:
          type: string
      responses:
        '200':
          description: deal deleted
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '401':
          description: unauthorized
        '404':
          description: deal not found
  "/playbooks/{playbook_id}/flow_steps":
    get:
      summary: Retrieves flow steps for a playbook
      tags:
      - Flow Steps
      security:
      - api_key: []
      description: |
        Returns all stages (flow steps) within a playbook.

        Flow steps represent the progression stages for contacts (e.g., "New Lead", "Qualified", "Negotiating").
        Use flow step IDs when updating a contact's current position in the sales workflow.
      parameters:
      - name: playbook_id
        in: path
        required: true
        description: The ID of the playbook to retrieve flow steps for
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      responses:
        '200':
          description: flow steps found
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        name:
                          type: string
                          nullable: true
                        order:
                          type: integer
                          nullable: true
                        flow_type:
                          type: string
                          nullable: true
                        playbook_id:
                          type: string
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
        '401':
          description: unauthorized
        '404':
          description: playbook not found
  "/playbooks":
    get:
      summary: Retrieves all playbooks
      tags:
      - Playbooks
      security:
      - api_key: []
      description: |
        Returns all playbooks (sales workflows) for the account.

        Playbooks define the stages (flow steps) that contacts progress through.
        Use the playbook ID when assigning contacts to a workflow.
      responses:
        '200':
          description: playbooks found
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    _id:
                      type: string
                    name:
                      type: string
                      nullable: true
                    created_at:
                      type: string
                      format: date-time
                      nullable: true
                    updated_at:
                      type: string
                      format: date-time
                      nullable: true
        '401':
          description: unauthorized
  "/sales_dashboard/performance":
    get:
      summary: Retrieves sales dashboard performance data for a single agent
      tags:
      - Sales Dashboard
      security:
      - api_key: []
      description: |
        Returns performance data for one agent on a playbook: KPI cards (won, conversion_rate,
        tasks, contacted) with team tier badge for the given time period, and a 30-day daily
        chart for all metrics. Unlike the team dashboard endpoints, this is always scoped to a
        single agent.
      parameters:
      - name: playbook_id
        in: query
        required: true
        description: ID of the playbook to filter by
        schema:
          type: string
        example: 507f1f77bcf86cd799439011
      - name: user_id
        in: query
        required: true
        description: ID of the agent whose performance to return
        schema:
          type: string
        example: 507f1f77bcf86cd799439012
      - name: period
        in: query
        required: true
        description: Time period (e.g. this_week, this_month, last_week, last_month,
          last_two_months, last_7_days, last_14_days, last_30_days, custom)
        schema:
          type: string
        example: this_week
      - name: start_date
        in: query
        required: false
        description: Start date for custom period (ISO 8601)
        schema:
          type: string
          format: date
        example: '2024-01-01'
      - name: end_date
        in: query
        required: false
        description: End date for custom period (ISO 8601)
        schema:
          type: string
          format: date
        example: '2024-01-31'
      responses:
        '200':
          description: performance data returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  kpis:
                    type: array
                    items:
                      type: object
                      properties:
                        metric:
                          type: string
                          example: won
                        value:
                          type: number
                        tier:
                          type: string
                          nullable: true
                  chart:
                    type: array
                    items:
                      type: object
                      properties:
                        metric:
                          type: string
                        mean:
                          type: number
                        data:
                          type: array
                          items:
                            type: object
                            properties:
                              date:
                                type: string
                              value:
                                type: number
                        empty:
                          type: boolean
        '401':
          description: unauthorized
        '404':
          description: playbook or user not found
        '422':
          description: date range exceeds limit
  "/sales_dashboard/sales_goals":
    get:
      summary: Retrieves daily sales goals and their goal/actual records
      tags:
      - Sales Dashboard
      security:
      - api_key: []
      description: |
        Returns the playbook's daily sales goals (target per metric: new_leads, won_deals)
        and the daily goal/actual records for those metrics within the given date range.
      parameters:
      - name: playbook_id
        in: query
        required: true
        description: ID of the playbook to filter by
        schema:
          type: string
        example: 507f1f77bcf86cd799439011
      - name: start_date
        in: query
        required: true
        description: Start date for goal/actual records (ISO 8601)
        schema:
          type: string
          format: date
        example: '2024-01-01'
      - name: end_date
        in: query
        required: true
        description: End date for goal/actual records (ISO 8601)
        schema:
          type: string
          format: date
        example: '2024-01-31'
      responses:
        '200':
          description: sales goals data returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  goals:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        metric:
                          type: string
                          example: new_leads
                        target_value:
                          type: integer
                          example: 10
                  records:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        metric:
                          type: string
                          example: new_leads
                        date:
                          type: string
                          format: date
                        goal_value:
                          type: integer
                          example: 10
                        actual_value:
                          type: integer
                          example: 4
        '401':
          description: unauthorized
        '404':
          description: playbook not found
        '422':
          description: start_date or end_date missing
  "/submitted_forms":
    get:
      summary: Retrieves submitted forms
      tags:
      - Submitted Forms
      security:
      - api_key: []
      description: |
        Returns a paginated list of submitted lead capture forms.

        Forms can come from multiple sources: web forms, Meta (Facebook) lead ads, TikTok lead ads, or Typeform.
        Each form includes the raw responses and the associated contact.
      parameters:
      - name: page
        in: query
        required: false
        description: Page number for pagination
        schema:
          type: integer
          default: 1
          minimum: 1
        example: 1
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 100
        example: 25
      - name: order_by
        in: query
        required: false
        description: Field to order results by
        schema:
          type: string
          default: created_at
        example: created_at
      - name: sort
        in: query
        required: false
        description: Sort direction (asc or desc)
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
        example: desc
      - name: source
        in: query
        required: false
        description: Filter by form source
        schema:
          type: string
          enum:
          - web
          - meta
          - typeform
          - tiktok
        example: web
      - name: form_id
        in: query
        required: false
        description: Filter by form ID
        schema:
          type: string
        example: form-123
      - name: contact_id
        in: query
        required: false
        description: Filter by contact ID
        schema:
          type: string
        example: 507f1f77bcf86cd799439011
      - name: created_at_from
        in: query
        required: false
        description: Filter forms created from this date
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00Z'
      - name: created_at_to
        in: query
        required: false
        description: Filter forms created until this date
        schema:
          type: string
          format: date-time
        example: '2024-12-31T23:59:59Z'
      - name: updated_at_from
        in: query
        required: false
        description: Filter forms updated from this date
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00Z'
      - name: updated_at_to
        in: query
        required: false
        description: Filter forms updated until this date
        schema:
          type: string
          format: date-time
        example: '2024-12-31T23:59:59Z'
      responses:
        '200':
          description: submitted forms found
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        form_id:
                          type: string
                          nullable: true
                        form_name:
                          type: string
                          nullable: true
                        source:
                          type: string
                          nullable: true
                        field_errors:
                          type: array
                          nullable: true
                        typeform_response:
                          type: object
                          nullable: true
                        meta_response:
                          type: object
                          nullable: true
                        tiktok_response:
                          type: object
                          nullable: true
                        meta_webhook_change:
                          type: object
                          nullable: true
                        web_response:
                          type: object
                          nullable: true
                        meta_leadgen_id:
                          type: string
                          nullable: true
                        meta_page_id:
                          type: string
                          nullable: true
                        meta_page_name:
                          type: string
                          nullable: true
                        meta_ad_id:
                          type: string
                          nullable: true
                        meta_ad_name:
                          type: string
                          nullable: true
                        meta_adgroup_id:
                          type: string
                          nullable: true
                        meta_adgroup_name:
                          type: string
                          nullable: true
                        contact_id:
                          type: string
                        responses:
                          type: array
                          items:
                            type: object
                            properties:
                              _id:
                                type: string
                              input_id:
                                type: string
                              label:
                                type: string
                              field_string_value:
                                type: string
                                nullable: true
                              field_date_value:
                                type: string
                                format: date-time
                                nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  page_info:
                    type: object
                    properties:
                      current_page:
                        type: string
                        nullable: true
                      limit:
                        type: string
                        nullable: true
        '401':
          description: unauthorized
  "/submitted_forms/{id}":
    get:
      summary: Retrieves a submitted form
      tags:
      - Submitted Forms
      security:
      - api_key: []
      description: Returns a single submitted form with all responses and metadata.
      parameters:
      - name: id
        in: path
        description: Submitted form ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: submitted form found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  form_id:
                    type: string
                    nullable: true
                  form_name:
                    type: string
                    nullable: true
                  source:
                    type: string
                    nullable: true
                  field_errors:
                    type: array
                    nullable: true
                  typeform_response:
                    type: object
                    nullable: true
                  meta_response:
                    type: object
                    nullable: true
                  tiktok_response:
                    type: object
                    nullable: true
                  meta_webhook_change:
                    type: object
                    nullable: true
                  web_response:
                    type: object
                    nullable: true
                  meta_leadgen_id:
                    type: string
                    nullable: true
                  meta_page_id:
                    type: string
                    nullable: true
                  meta_page_name:
                    type: string
                    nullable: true
                  meta_ad_id:
                    type: string
                    nullable: true
                  meta_ad_name:
                    type: string
                    nullable: true
                  meta_adgroup_id:
                    type: string
                    nullable: true
                  meta_adgroup_name:
                    type: string
                    nullable: true
                  contact_id:
                    type: string
                  responses:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        input_id:
                          type: string
                        label:
                          type: string
                        field_string_value:
                          type: string
                          nullable: true
                        field_date_value:
                          type: string
                          format: date-time
                          nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: submitted form not found
        '401':
          description: unauthorized
  "/task_templates":
    get:
      summary: Retrieves task templates
      tags:
      - Task Templates
      security:
      - api_key: []
      description: |
        Returns all task templates defined for the account.

        Task templates define the types of follow-up actions (e.g., "First Call", "Demo Meeting").
        Use template IDs when creating tasks via the API.
      responses:
        '200':
          description: task templates found
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        title:
                          type: string
                          nullable: true
                        description:
                          type: string
                          nullable: true
                        playbook_id:
                          type: string
                          nullable: true
                        flow_step_id:
                          type: string
                          nullable: true
                        account_id:
                          type: string
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
        '401':
          description: unauthorized
  "/tasks":
    get:
      summary: Retrieves tasks
      tags:
      - Tasks
      security:
      - api_key: []
      description: |
        Returns a paginated list of tasks. Filter by assignee, contact, or status.

        Tasks represent follow-up actions for contacts (calls, meetings, etc.).
      parameters:
      - name: page
        in: query
        required: false
        description: Page number for pagination
        schema:
          type: integer
          default: 1
          minimum: 1
        example: 1
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 100
        example: 25
      - name: order_by
        in: query
        required: false
        description: Field to order results by
        schema:
          type: string
          default: created_at
          enum:
          - created_at
          - updated_at
          - completed_at
          - started_at
          - active_on
          - identifier
          - internal_identifier
          - identifier_priority
          - priority
          - attempts
          - status
          - subject_type
          - skills
          - created_outside_working_hours
          - has_skills
          - predictive_call
          - progressive_call
          - transferable
          - _id
          - account_id
          - assignee_id
          - contact_id
          - subject_id
          - playbook_id
          - task_team_id
          - task_template_id
        example: created_at
      - name: sort
        in: query
        required: false
        description: Sort direction (asc or desc)
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
        example: desc
      responses:
        '200':
          description: tasks found
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        identifier:
                          type: string
                          nullable: true
                        status:
                          type: string
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  page_info:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        nullable: true
                      limit:
                        type: integer
                        nullable: true
        '400':
          description: field is not sortable
        '401':
          description: unauthorized
    post:
      summary: Creates a new task
      tags:
      - Tasks
      security:
      - api_key: []
      description: |
        Creates a new task for contact follow-up.

        Tasks are based on task templates which define the type of follow-up action.
        Optionally schedule the task for a specific date using `active_on`.
      parameters: []
      responses:
        '200':
          description: task created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        '401':
          description: unauthorized
        '422':
          description: unprocessable entity
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                task_subject_id:
                  type: string
                  example: 64a1b2c3d4e5f678901234ab
                task_subject_type:
                  type: string
                  example: Contact
                task_template_id:
                  type: string
                  example: 64a1b2c3d4e5f678901235fe
                comment:
                  type: string
                  example: Some comment
                active_on:
                  type: string
                  format: date-time
                  example: '2024-12-31T23:59:59Z'
                assignee_id:
                  type: string
                  example: 64a1b2c3d4e5f678901235fe
              required:
              - task_subject_id
              - task_subject_type
              - task_template_id
  "/tasks/{id}/cancel":
    post:
      summary: Cancels a task
      tags:
      - Tasks
      security:
      - api_key: []
      description: Marks a task as cancelled. The task will no longer appear in the
        task queue.
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the task to cancel
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      responses:
        '200':
          description: task cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
        '401':
          description: unauthorized
        '404':
          description: task not found
  "/tasks/{id}/complete":
    post:
      summary: Completes a task
      tags:
      - Tasks
      security:
      - api_key: []
      description: Marks a task as completed. Records the completion time and removes
        it from the task queue.
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the task to complete
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      responses:
        '200':
          description: task completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
        '401':
          description: unauthorized
        '404':
          description: task not found
  "/whatsapp_templates":
    get:
      summary: Retrieves WhatsApp templates
      tags:
      - WhatsApp Templates
      security:
      - api_key: []
      description: |
        Returns all approved WhatsApp Business templates for the account.

        Only templates with `status: approved` can be used to send messages.
        Templates are required to initiate conversations outside the 24-hour window.
      responses:
        '200':
          description: whatsapp templates found
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        name:
                          type: string
                          nullable: true
                        status:
                          type: string
                          nullable: true
                        content:
                          type: string
                          nullable: true
                        category:
                          type: string
                          nullable: true
                        language:
                          type: string
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
        '401':
          description: unauthorized
  "/whatsapp_templates/{id}/send_message":
    post:
      summary: Sends a WhatsApp template message
      tags:
      - WhatsApp Templates
      security:
      - api_key: []
      description: |
        Sends a WhatsApp template message to a contact.

        Use `body_parameters` to fill the template's body variables (`{{1}}`, `{{2}}`, ...). It is
        positional — the first element fills `{{1}}`, the second `{{2}}`, and so on — and each element
        must be `{ "type": "text", "text": "..." }` (no `name`/`value`). The number of elements should
        match the number of variables in the template.
        For templates with media headers, use `header_parameters` with document/image/video links.
        For templates with URL buttons, use `buttons_parameters` to set the dynamic URL suffix.
        Use `from_phone_number` to choose which of the account's WhatsApp numbers sends the message.
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the WhatsApp template to send
        schema:
          type: string
        example: 64a1b2c3d4e5f678901234ab
      responses:
        '200':
          description: message sent with buttons parameters
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        '401':
          description: unauthorized
        '404':
          description: template not found
        '503':
          description: WhatsApp connection failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      base:
                        type: array
                        items:
                          type: string
        '422':
          description: unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    nullable: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                contact_id:
                  type: string
                  example: 64a1b2c3d4e5f678901234cd
                from_phone_number:
                  type: string
                  example: "+1234567890"
                body_parameters:
                  type: array
                  description: 'Positional: the first element fills {{1}}, the second
                    {{2}}, etc. Count must match the template.'
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        example: text
                      text:
                        type: string
                        example: John
                    required:
                    - type
                header_parameters:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        example: document
                      document:
                        type: object
                        properties:
                          link:
                            type: string
                            example: https://example.com/document.pdf
                    required:
                    - type
                buttons_parameters:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        example: button
                      sub_type:
                        type: string
                        example: url
                      index:
                        type: integer
                        example: 0
                      parameters:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              example: text
                            text:
                              type: string
                              example: '12'
                    required:
                    - type
                    - sub_type
                    - index
              required:
              - contact_id
servers:
- url: "{HOST}/api/{API_VERSION}"
  description: Vixiees API Server
  variables:
    HOST:
      default: https://api.vixiees.com
      description: API Host
    API_VERSION:
      default: v1
      description: API Version
tags:
- name: Contacts
  description: Manage contacts (leads and clients)
- name: Deals
  description: Track sales opportunities
- name: Tasks
  description: Manage follow-up tasks
- name: Task Templates
  description: Task template definitions
- name: Playbooks
  description: Sales workflow definitions
- name: Flow Steps
  description: Stages within playbooks
- name: Contracts
  description: Contract documents
- name: Submitted Forms
  description: Lead capture forms
- name: Call Recordings
  description: Access call recordings
- name: WhatsApp Templates
  description: Send WhatsApp messages
- name: Webhooks
  description: Receive real-time events
- name: Dashboard
  description: Analytics dashboard data export
- name: Sales Dashboard
  description: Per-agent sales dashboard data export
