Apptoto Events API

openapi: 3.2.0
info:
  title: api-settings Events API
  version: '1.0'
servers:
- url: https://api.apptoto.com
security:
- sec0: []
- sec1: []
tags:
- name: Events
paths:
  /v1/events:
    get:
      summary: /v1/events
      description: 'Fetch a range of "events".


        Please note that you can also use this API to fetch one event by id or external_id (for legacy reasons). The new proper way to fetch one event is to use the /v1/event (singular) API.'
      operationId: v1events
      parameters:
      - name: begin
        in: query
        description: Only events starting at or after this date/time will be included.  (ISO8601)
        schema:
          type: string
          format: date
      - name: end
        in: query
        description: Only events starting at or before this Date/Time will be included. (ISO8601)
        schema:
          type: string
          format: date
      - name: q
        in: query
        description: (OPTIONAL) Search-language query string. Restricts results to events that match the query. A bare term (no operator) searches the event's title, location and content plus each participant's name, email and phone. Supports field-specific terms (e.g. `name:fred`, `event.title="Haircut with Fred"`, `event.location:portland`), custom event fields (e.g. `event.custom.service_type:haircut`), boolean operators (`and`, `or`, parens, `!` / `-` for negation), comparison operators (`>`, `>=`, `<`, `<=`, `=`, `!=`), wildcards (`*`) and the `empty` keyword. Multiple bare terms are ANDed; quote a phrase to match it exactly. See https://www.apptoto.com/apptoto-manual/article/appointments-tab/appointment-search-syntax/ for the full syntax reference.
        schema:
          type: string
      - name: calendar_id
        in: query
        description: (OPTIONAL) Restrict results to events on this calendar.
        schema:
          type: integer
          format: int32
      - name: phone_number
        in: query
        description: Only events who have a participant with the given phone number will be included. The phone number will be normalized based on the Apptoto user's default country setting.  If the phone number you are filtering on is in a different country then include the fully normalized phone number (e.g. +66234234234).
        schema:
          type: string
      - name: email_address
        in: query
        description: Only events who have a participant with the specified email address will be incluced
        schema:
          type: string
      - name: participant_id
        in: query
        description: (OPTIONAL) Only events that include this participant will be returned. As with phone_number and email_address, each returned event lists only the matching participant.
        schema:
          type: integer
          format: int32
      - name: page_size
        in: query
        description: The number of events to return
        schema:
          type: integer
          format: int32
          default: 30
      - name: page
        in: query
        description: The page to fetch (1 based)
        schema:
          type: integer
          format: int32
          default: 1
      - name: include_total
        in: query
        description: '(OPTIONAL) When true, the response includes `total`: the number of events matching the request across all pages. Off by default -- computing it costs an extra count over the whole matched range, so only ask for it when you need it.'
        schema:
          type: boolean
          default: false
      - name: include_deleted
        in: query
        description: Include deleted events
        schema:
          type: boolean
          default: false
      - name: include_conversations
        in: query
        description: If true, then Apptoto will include any conversations sent about the event.  The conversations will be an array on each participant with the key "conversations".
        schema:
          type: boolean
          default: false
      deprecated: false
      security:
      - sec0: []
      - sec1:
        - events:read
      tags:
      - Events
    post:
      summary: /v1/events
      description: 'Create events in Apptoto. Apptoto''s auto messages will be sent for the events created if Auto Messages are turned on. Otherwise, be sure to include #auto in the event information in order to tell Apptoto to send the Auto Messages configured for the account.'
      operationId: v1events-1
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - events
              properties:
                events:
                  type: array
                  description: Array of events to add
                prevent_calendar_creation:
                  type: boolean
                  description: Apptoto will create new calendars for you if you reference a calendar in the events array that does not exist.  Set this parameter to true to prevent this from happening.
                  default: false
      deprecated: false
      security:
      - sec0: []
      - sec1:
        - events:write
      tags:
      - Events
    delete:
      summary: /v1/events
      description: 'Deletes one event using an id. Either id or external_id param.


        This halts any messages being sent on behalf of the event and removes it from the UI in the Apptoto system.'
      operationId: v1events-2
      parameters:
      - name: id
        in: query
        description: The Apptoto id for the event
        required: true
        schema:
          type: integer
          format: int32
      - name: external_id
        in: query
        description: Your unique external id for the event.  REQUIRED if you do not specify an id
        schema:
          type: string
      deprecated: false
      security:
      - sec0: []
      - sec1:
        - events:write
      tags:
      - Events
    put:
      summary: /v1/events
      description: 'Create or update events in Apptoto. Apptoto''s auto messages will be sent for the events created if Auto Messages are turned on. Otherwise, be sure to include #auto in the event information in order to tell Apptoto to send the Auto Messages configured for the account.


        To update existing events, be sure to provide either an external_id or id, otherwise a new event will be created. For the event properties, this API acts like a patch... meaning that only the events fields you specify will be updated.


        However, if you provide a value for the "participants" or "custom_data" field, then provide all of the data. Meaning, it does not act as a patch for custom_data or individual participants.


        Please note that participants will not be removed from an event if messages have already started going out to that participant. This "feature" can be turned off, so ask support@apptoto.com if you need it turned off.


        Also, please note that we do not support moving an appointment from one calendar to another at this time. If you need this, please contact support@apptoto.com .'
      operationId: v1events-3
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - events
              properties:
                events:
                  type: array
                  description: Array of events to add
                prevent_calendar_creation:
                  type: boolean
                  description: Apptoto will create new calendars for you if you reference a calendar in the events array that does not exist.  Set this parameter to true to prevent this from happening.
                  default: false
      deprecated: false
      security:
      - sec0: []
      - sec1:
        - events:write
      tags:
      - Events
components:
  securitySchemes:
    sec0:
      type: http
      scheme: basic
    sec1:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.apptoto.com/oauth/authorize
          tokenUrl: https://api.apptoto.com/oauth/token
          refreshUrl: https://api.apptoto.com/oauth/token
          scopes:
            calendars:read: View calendars
            address_books:read: View address books
            contacts:read: View contacts
            contacts:write: Create, update, and delete contacts
            events:read: View calendar events
            events:write: Create, update, and delete events; mark event statuses
            bookings:read: View booking page availability and existing bookings
            bookings:write: Create bookings on booking pages
            imports:read: Check the status of imports
            imports:write: Upload imports (CSV / ICS / XML) that bulk-create data
            lists:read: View opt-in and opt-out lists
            lists:write: Modify opt-in and opt-out lists
            messaging:read: View conversations and message history
            messaging:send: Send SMS or email messages on the user's behalf
            webhooks:read: View webhooks
            webhooks:write: Create, update, and delete webhooks that send account activity to other services
x-readme-fauxas: true
x-provenance:
  method: searched
  source: https://apidocs.apptoto.com/reference
  harvested: '2026-10-28'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://apidocs.apptoto.com/reference/import-upload.md
  - https://apidocs.apptoto.com/reference/v1address_books.md
  - https://apidocs.apptoto.com/reference/v1availability.md
  - https://apidocs.apptoto.com/reference/v1book_now-1.md
  - https://apidocs.apptoto.com/reference/v1booking_pages.md
  - https://apidocs.apptoto.com/reference/v1bookings.md
  - https://apidocs.apptoto.com/reference/v1calendars-1.md
  - https://apidocs.apptoto.com/reference/v1contact.md
  - https://apidocs.apptoto.com/reference/v1contacts-1.md
  - https://apidocs.apptoto.com/reference/v1contacts-2.md
  - https://apidocs.apptoto.com/reference/v1contacts-3.md
  - https://apidocs.apptoto.com/reference/v1contacts.md
  - https://apidocs.apptoto.com/reference/v1contactstag.md
  - https://apidocs.apptoto.com/reference/v1conversation_messages.md
  - https://apidocs.apptoto.com/reference/v1conversation_reply.md
  - https://apidocs.apptoto.com/reference/v1conversation_templates.md
  - https://apidocs.apptoto.com/reference/v1conversations.md
  - https://apidocs.apptoto.com/reference/v1event.md
  - https://apidocs.apptoto.com/reference/v1eventmark.md
  - https://apidocs.apptoto.com/reference/v1events-1.md
  - https://apidocs.apptoto.com/reference/v1events-2.md
  - https://apidocs.apptoto.com/reference/v1events-3.md
  - https://apidocs.apptoto.com/reference/v1events.md
  - https://apidocs.apptoto.com/reference/v1eventtag.md
  - https://apidocs.apptoto.com/reference/v1import.md
  - https://apidocs.apptoto.com/reference/v1lists-1.md
  - https://apidocs.apptoto.com/reference/v1lists-2.md
  - https://apidocs.apptoto.com/reference/v1lists-3.md
  - https://apidocs.apptoto.com/reference/v1lists.md
  - https://apidocs.apptoto.com/reference/v1participantmark.md
  - https://apidocs.apptoto.com/reference/v1participants-1.md
  - https://apidocs.apptoto.com/reference/v1participants-2.md
  - https://apidocs.apptoto.com/reference/v1participants-3.md
  - https://apidocs.apptoto.com/reference/v1participants.md
  - https://apidocs.apptoto.com/reference/v1participants_auto_messages-1.md
  - https://apidocs.apptoto.com/reference/v1participants_auto_messages.md
  - https://apidocs.apptoto.com/reference/v1participanttag.md
  - https://apidocs.apptoto.com/reference/v1start_conversation.md
  - https://apidocs.apptoto.com/reference/v1userinfo.md
  - https://apidocs.apptoto.com/reference/v1webhooks-1.md
  - https://apidocs.apptoto.com/reference/v1webhooks-2.md
  - https://apidocs.apptoto.com/reference/v1webhooks-3.md
  - https://apidocs.apptoto.com/reference/v1webhooks.md
  merge:
    pages: 43
    deduped: 84
    conflicts_kept_first: 0