CreateSchedulingConversationInput

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/popp/main/json-schema/popp-create-scheduling-conversation-input-schema.json",
  "title": "CreateSchedulingConversationInput",
  "description": "Request body for creating an auto-schedule conversation. Requires a campaign (campaignId or externalCampaignId), a way to reach the candidate (phoneNumber or emailAddress), the meeting participants, and the meeting configuration.",
  "x-generated": "2026-10-14",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/popp-api-openapi.yml#/components/schemas/CreateSchedulingConversationInput",
  "type": "object",
  "properties": {
    "phoneNumber": {
      "type": "string",
      "pattern": "^\\+[1-9]\\d{1,14}$",
      "title": "Phone Number",
      "description": "The phone number of the candidate, in E.164 format. Either phoneNumber or emailAddress is required. For SMS and WHATSAPP campaigns a usable phone number is required unless the campaign's email fallback resolves to enabled (emailChannelFallbackEnabled on the campaign, inheriting the organization setting when unset) and an emailAddress is provided, in which case email is used as a fallback when the phone number cannot be parsed."
    },
    "countryCode": {
      "type": "string",
      "title": "Country Code",
      "description": "The country code in ISO 3166-1 alpha-2 format. This is used to format the phone number if it is not in E.164 format."
    },
    "firstName": {
      "type": "string",
      "title": "First Name",
      "description": "The first name of the candidate."
    },
    "lastName": {
      "type": "string",
      "title": "Last Name",
      "description": "The last name of the candidate."
    },
    "emailAddress": {
      "type": "string",
      "format": "email",
      "title": "Email Address",
      "description": "The email address of the candidate. Either phoneNumber or emailAddress is required. For SMS and WHATSAPP campaigns, a request with no usable phone number is accepted only when the campaign's email fallback resolves to enabled; otherwise it is rejected with 400."
    },
    "campaignId": {
      "type": "string",
      "title": "Campaign ID",
      "description": "The unique identifier for the campaign. Either campaignId or externalCampaignId is required."
    },
    "externalCampaignId": {
      "type": "string",
      "title": "External Campaign ID",
      "description": "The unique identifier for the campaign in the external system. Either campaignId or externalCampaignId is required."
    },
    "externalId": {
      "type": "string",
      "title": "External ID",
      "description": "The unique identifier for the conversation in the external system."
    },
    "skipDuplicationCheck": {
      "type": "boolean",
      "title": "Skip Duplication Check",
      "description": "If true, skips the check for existing conversations with the same phone number/email and campaign."
    },
    "shouldSendDuringBusinessHours": {
      "type": "boolean",
      "title": "Should Send During Business Hours",
      "description": "If true, the initial message will be scheduled to send during business hours. The timezone is inferred from the phone number."
    },
    "meetingParticipants": {
      "type": "array",
      "title": "Meeting Participants",
      "description": "List of participants for the meeting. Exactly one participant must be marked as organizer — this endpoint always schedules a collective meeting, where every participant must be able to attend. Each participant must be able to supply availability one of three ways: a connected calendar (isCalendarConnected true), pre-defined availability.timeSlots, or autoCollectAvailability. Any combination of the three across the panel is allowed.",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "isOrganizer": {
            "type": "boolean",
            "title": "Is Organizer",
            "description": "Whether this participant is the meeting organizer. Exactly one participant should be marked as organizer."
          },
          "isCalendarConnected": {
            "type": "boolean",
            "title": "Is Calendar Connected",
            "description": "Whether this participant has a connected calendar in Popp."
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "The full name of the participant."
          },
          "email": {
            "type": "string",
            "format": "email",
            "title": "Email",
            "description": "The email address of the participant."
          },
          "autoCollectAvailability": {
            "type": "boolean",
            "title": "Auto Collect Availability",
            "description": "If true, Popp emails this participant to ask for their availability instead of reading a calendar. Requires isCalendarConnected to be false. Any number of participants can have this enabled — Popp collects from each of them and books a slot that works for the whole panel."
          },
          "availabilityOutreachSettings": {
            "type": "object",
            "title": "Availability Outreach Settings",
            "description": "Per-participant availability outreach settings. This endpoint has no template-level equivalent — settings are per participant, and any field omitted falls back to the system default.",
            "properties": {
              "requiredHours": {
                "type": "integer",
                "description": "Hours of availability to ask this participant for. Default: 6. A target the agent nudges toward, not a minimum that gates booking — Popp will book inside a shorter overlap if that is all it has.",
                "minimum": 1,
                "maximum": 168
              },
              "periodDays": {
                "type": "integer",
                "description": "The window this participant is asked to offer availability within, in days, and the window their reply is read against. Default: 14.",
                "minimum": 7,
                "maximum": 60
              },
              "customTemplatedSubjectLine": {
                "type": "string",
                "description": "Custom email subject line for the outreach email to this participant. Supports placeholders: {{INTERVIEWER_NAME}}, {{CANDIDATE_FIRST_NAME}}, {{AGENT_NAME}}, {{ORGANIZATION_NAME}}, {{CAMPAIGN_OWNER_NAME}}, {{MEETING_AVAILABILITY_TEXT}}."
              },
              "customTemplatedMessage": {
                "type": "string",
                "description": "Custom email body for the outreach email to this participant. Supports the same placeholders as customTemplatedSubjectLine. {{MEETING_AVAILABILITY_TEXT}} expands to the concrete ask (window, hours, timezone) derived from requiredHours and periodDays; it is optional and not validated, so a message that omits it is accepted and the participant receives no concrete availability request."
              },
              "nudgeSettings": {
                "type": "array",
                "description": "Follow-up nudge configuration. Each entry represents one nudge with a delayHours field. Array length determines total nudges. Empty array disables nudging.",
                "items": {
                  "type": "object",
                  "properties": {
                    "delayHours": {
                      "type": "integer",
                      "description": "Hours to wait since the previous message before sending this nudge.",
                      "minimum": 1
                    }
                  },
                  "required": [
                    "delayHours"
                  ]
                },
                "maxItems": 10
              },
              "additionalRecipients": {
                "type": "array",
                "description": "Email addresses CC'd on all outreach communications (initial email, reply-backs, nudges, cancellation).",
                "items": {
                  "type": "string",
                  "format": "email"
                }
              }
            }
          },
          "availability": {
            "type": "object",
            "title": "Availability",
            "description": "Pre-defined availability time slots for the participant. Only applicable when isCalendarConnected is false.",
            "properties": {
              "timezone": {
                "type": "string",
                "title": "Timezone",
                "description": "IANA timezone string (e.g., 'America/New_York', 'Europe/London')."
              },
              "timeSlots": {
                "type": "array",
                "title": "Time Slots",
                "description": "Array of available time windows. All time slots must be in the future.",
                "minItems": 1,
                "items": {
                  "type": "object",
                  "properties": {
                    "date": {
                      "type": "string",
                      "pattern": "^\\d{4}-([0][1-9]|1[0-2])-([0][1-9]|[12]\\d|3[01])$",
                      "title": "Date",
                      "description": "The date in YYYY-MM-DD format (e.g., '2025-01-15')."
                    },
                    "startTime": {
                      "type": "string",
                      "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$",
                      "title": "Start Time",
                      "description": "The start time in HH:mm format (e.g., '09:00')."
                    },
                    "endTime": {
                      "type": "string",
                      "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$",
                      "title": "End Time",
                      "description": "The end time in HH:mm format (e.g., '17:00')."
                    }
                  },
                  "required": [
                    "date",
                    "startTime",
                    "endTime"
                  ]
                }
              }
            },
            "required": [
              "timezone",
              "timeSlots"
            ]
          }
        },
        "required": [
          "isOrganizer",
          "isCalendarConnected",
          "name",
          "email"
        ]
      }
    },
    "meetingConfiguration": {
      "type": "object",
      "title": "Meeting Configuration",
      "description": "Configuration for the meeting to be scheduled.",
      "properties": {
        "title": {
          "type": "string",
          "title": "Title",
          "description": "The title of the meeting."
        },
        "description": {
          "type": "string",
          "title": "Description",
          "description": "A description for the meeting that will be included in the calendar invite."
        },
        "openHours": {
          "type": "array",
          "title": "Open Hours",
          "description": "Available time windows for scheduling the meeting.",
          "minItems": 1,
          "items": {
            "type": "object",
            "properties": {
              "days": {
                "type": "array",
                "title": "Days",
                "description": "Array of day numbers (0=Sunday, 1=Monday, ..., 6=Saturday).",
                "items": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 6
                },
                "minItems": 1
              },
              "start": {
                "type": "string",
                "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$",
                "title": "Start Time",
                "description": "The start time in HH:mm format (e.g., '09:00')."
              },
              "end": {
                "type": "string",
                "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$",
                "title": "End Time",
                "description": "The end time in HH:mm format (e.g., '17:00')."
              }
            },
            "required": [
              "days",
              "start",
              "end"
            ]
          }
        },
        "timezone": {
          "type": "string",
          "title": "Timezone",
          "description": "IANA timezone string for the meeting (e.g., 'America/New_York')."
        },
        "duration": {
          "type": "integer",
          "title": "Duration",
          "description": "The duration of the meeting in minutes.",
          "minimum": 1
        },
        "videoConferencing": {
          "type": "boolean",
          "title": "Video Conferencing",
          "description": "Whether to include video conferencing for the meeting. If true, location is not allowed. If false, location is required."
        },
        "videoConferencingProvider": {
          "type": "string",
          "title": "Video Conferencing Provider",
          "description": "The video conferencing provider to use.",
          "enum": [
            "Google Meet",
            "Microsoft Teams"
          ]
        },
        "location": {
          "type": "string",
          "title": "Location",
          "description": "The physical location for the meeting. Required when videoConferencing is false; must contain at least one non-space character and is trimmed. Not allowed when videoConferencing is true."
        }
      },
      "required": [
        "title",
        "openHours",
        "timezone",
        "duration",
        "videoConferencing"
      ]
    }
  },
  "required": [
    "firstName",
    "meetingParticipants",
    "meetingConfiguration"
  ],
  "oneOf": [
    {
      "title": "Campaign ID Required",
      "description": "Either campaignId or externalCampaignId is required.",
      "required": [
        "campaignId"
      ]
    },
    {
      "title": "External Campaign ID Required",
      "description": "Either campaignId or externalCampaignId is required.",
      "required": [
        "externalCampaignId"
      ]
    }
  ],
  "additionalProperties": false
}