Apptoto Contacts API

openapi: 3.2.0
info:
  title: api-settings Contacts API
  version: '1.0'
servers:
- url: https://api.apptoto.com
security:
- sec0: []
- sec1: []
tags:
- name: Contacts
paths:
  /v1/contacts:
    get:
      summary: /v1/contacts
      description: ''
      operationId: v1contacts
      parameters:
      - name: page
        in: query
        description: The page number to fetch (1 based)
        schema:
          type: integer
          format: int32
          default: 1
      - name: page_size
        in: query
        description: The size of the page to fetch.
        schema:
          type: integer
          format: int32
          default: 30
      - name: address_book_id
        in: query
        description: (OPTIONAL) Restrict results to contacts in this address book.
        schema:
          type: integer
          format: int32
      - name: q
        in: query
        description: (OPTIONAL) Search-language query string. Restricts results to contacts that match the query. Supports field-specific terms (e.g. `name:fred`, `email=fred@example.com`, `phone=+14155551234`), custom fields (e.g. `custom.referral_source:website` or the bare field name if defined under Settings > Field Settings), boolean operators (`AND`, `OR`, parens, `!` / `-` for negation), comparison operators (`>`, `>=`, `<`, `<=`, `:=`), wildcards (`*`), and the `empty` keyword. A bare term (no operator) searches name, email, and phone. See https://www.apptoto.com/apptoto-manual/article/contacts-tab/contact-search-syntax/ for the full syntax reference.
        schema:
          type: string
      deprecated: false
      security:
      - sec0: []
      - sec1:
        - contacts:read
      tags:
      - Contacts
    post:
      summary: /v1/contacts
      description: Create contacts in Apptoto.
      operationId: v1contacts-3
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - contacts
              properties:
                contacts:
                  type: array
                  description: Array of events to add
      deprecated: false
      security:
      - sec0: []
      - sec1:
        - contacts:write
      tags:
      - Contacts
    put:
      summary: /v1/contacts
      description: 'Create or update Contacts in Apptoto.


        To update existing contacts, be sure to provide either an external_id or id, otherwise a new contact will be created. For the contact properties, this API acts like a patch... meaning that only the contact fields you specify will be updated.'
      operationId: v1contacts-1
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - contacts
              properties:
                contacts:
                  type: array
                  description: Array of events to add
      deprecated: false
      security:
      - sec0: []
      - sec1:
        - contacts:write
      tags:
      - Contacts
    delete:
      summary: /v1/contacts
      description: Delete one contact from apptoto.
      operationId: v1contacts-2
      parameters:
      - name: id
        in: query
        description: The id of the contact to remove.
        schema:
          type: integer
          format: int32
      responses:
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: false
      security:
      - sec0: []
      - sec1:
        - contacts:write
      tags:
      - Contacts
  /v1/contacts/tag:
    post:
      summary: /v1/contacts/tag
      description: Add or remove a tag on one contact. The tag is tracked in the contact's tags field.
      operationId: v1contactstag
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - tag
              properties:
                id:
                  type: string
                  description: The Apptoto id for the contact
                external_id:
                  type: string
                  description: Your unique external id for the contact.  REQUIRED if you do not specify an id
                address_book_id:
                  type: string
                  description: Optional. Restrict the lookup to a single address book.
                tag:
                  type: string
                  description: 'The tag to add or remove. A leading # is optional and is added automatically (e.g. "prospect" and "#prospect" are equivalent).'
                remove:
                  type: string
                  description: Set to "true" to remove the tag instead of adding it. Defaults to adding the tag.
      deprecated: false
      security:
      - sec0: []
      - sec1:
        - contacts:write
      tags:
      - Contacts
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