Tripleseat API

openapi: 3.1.0
info:
  title: Tripleseat API
  description: >-
    The Tripleseat REST API provides programmatic access to the event and
    catering sales lifecycle for restaurants, hotels, and unique venues. It
    exposes leads, events, accounts, contacts, locations, sites, and users, plus
    a public lead form endpoint for capturing inquiries directly into
    Tripleseat. The API is served from api.tripleseat.com under the v1 path,
    returns JSON or XML, paginates with the page query parameter (50 records per
    page), and uses OAuth 2.0 for authentication. Webhooks (documented in the
    companion AsyncAPI/description) emit lead and booking lifecycle events signed
    with a SHA256-HMAC X-Signature header.
  version: v1
  contact:
    name: Kin Lane
    email: kin@apievangelist.com
  license:
    name: Proprietary
    url: https://tripleseat.com/terms-of-service/
  termsOfService: https://tripleseat.com/terms-of-service/
externalDocs:
  description: Tripleseat API Overview
  url: https://support.tripleseat.com/hc/en-us/articles/205162108-API-Overview
servers:
- url: https://api.tripleseat.com
  description: Tripleseat Production API
tags:
- name: Leads
  description: Capture and retrieve leads, including the public lead form.
- name: Events
  description: Retrieve events and their bookings.
- name: Accounts
  description: Retrieve and update accounts.
- name: Contacts
  description: Create and associate contacts with accounts.
- name: Locations
  description: Retrieve locations within a site.
- name: Sites
  description: Retrieve sites that group locations.
- name: Users
  description: Retrieve Tripleseat users.
paths:
  /v1/leads.json:
    get:
      operationId: listLeads
      summary: List Leads
      description: >-
        Retrieve a paginated list of leads. Returns 50 records per page; use the
        page query parameter to page through results.
      tags:
      - Leads
      parameters:
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of leads.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Lead'
              examples:
                ListLeads200Example:
                  summary: Default listLeads 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - id: 500123
                      first_name: Mark
                      last_name: Lawrence
                      email_address: contact@example.com
                      phone_number: +1-555-867-5309
                      company: Acme Events Co.
                      event_description: Evening reception with plated dinner.
                      event_date: '2026-07-15'
                      start_time: '18:00'
                      end_time: '22:00'
                      guest_count: 75
                      additional_information: Evening reception with plated dinner.
                      location_id: 500123
                      status: definite
                      created_at: '2026-06-03T14:30:00Z'
                      updated_at: '2026-06-03T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/leads/{lead_id}.json:
    get:
      operationId: getLead
      summary: Get Lead
      description: Retrieve information for a single lead by its identifier.
      tags:
      - Leads
      parameters:
      - $ref: '#/components/parameters/LeadId'
      responses:
        '200':
          description: The requested lead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
              examples:
                GetLead200Example:
                  summary: Default getLead 200 response
                  x-microcks-default: true
                  value:
                    id: 500123
                    first_name: Mark
                    last_name: Lawrence
                    email_address: contact@example.com
                    phone_number: +1-555-867-5309
                    company: Acme Events Co.
                    event_description: Evening reception with plated dinner.
                    event_date: '2026-07-15'
                    start_time: '18:00'
                    end_time: '22:00'
                    guest_count: 75
                    additional_information: Evening reception with plated dinner.
                    location_id: 500123
                    status: definite
                    created_at: '2026-06-03T14:30:00Z'
                    updated_at: '2026-06-03T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/leads/search.json:
    get:
      operationId: searchLeads
      summary: Search Leads
      description: Retrieve leads matching the supplied query parameters.
      tags:
      - Leads
      parameters:
      - $ref: '#/components/parameters/Page'
      - name: updated_after
        in: query
        description: Return leads updated after this timestamp.
        required: false
        schema:
          type: string
          format: date-time
        example: '2026-06-03T14:30:00Z'
      responses:
        '200':
          description: A paginated list of matching leads.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Lead'
              examples:
                SearchLeads200Example:
                  summary: Default searchLeads 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - id: 500123
                      first_name: Mark
                      last_name: Lawrence
                      email_address: contact@example.com
                      phone_number: +1-555-867-5309
                      company: Acme Events Co.
                      event_description: Evening reception with plated dinner.
                      event_date: '2026-07-15'
                      start_time: '18:00'
                      end_time: '22:00'
                      guest_count: 75
                      additional_information: Evening reception with plated dinner.
                      location_id: 500123
                      status: definite
                      created_at: '2026-06-03T14:30:00Z'
                      updated_at: '2026-06-03T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/leads/create.json:
    post:
      operationId: createLead
      summary: Create Lead
      description: >-
        Create a lead from a public lead form using a public key. The request
        body wraps lead fields in a lead object. If the site has more than one
        location, location_id must be supplied in the body or as a query
        parameter.
      tags:
      - Leads
      parameters:
      - name: public_key
        in: query
        description: The public key for the lead form site or location.
        required: true
        schema:
          type: string
        example: example
      - name: location_id
        in: query
        description: >-
          The location the lead is intended for. Required when the site has
          more than one location and not supplied in the body.
        required: false
        schema:
          type: integer
        example: 500123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                lead:
                  $ref: '#/components/schemas/LeadCreate'
              required:
              - lead
            examples:
              CreateLeadRequestExample:
                summary: Default createLead request
                x-microcks-default: true
                value:
                  lead:
                    first_name: Mark
                    last_name: Lawrence
                    email_address: contact@example.com
                    phone_number: +1-555-867-5309
                    company: Acme Events Co.
                    event_description: Evening reception with plated dinner.
                    event_date: '2026-07-15'
                    start_time: '18:00'
                    end_time: '22:00'
                    guest_count: 75
                    additional_information: Evening reception with plated dinner.
                    location_id: 500123
      responses:
        '201':
          description: The lead was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
              examples:
                CreateLead201Example:
                  summary: Default createLead 201 response
                  x-microcks-default: true
                  value:
                    id: 500123
                    first_name: Mark
                    last_name: Lawrence
                    email_address: contact@example.com
                    phone_number: +1-555-867-5309
                    company: Acme Events Co.
                    event_description: Evening reception with plated dinner.
                    event_date: '2026-07-15'
                    start_time: '18:00'
                    end_time: '22:00'
                    guest_count: 75
                    additional_information: Evening reception with plated dinner.
                    location_id: 500123
                    status: definite
                    created_at: '2026-06-03T14:30:00Z'
                    updated_at: '2026-06-03T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/events.json:
    get:
      operationId: listEvents
      summary: List Events
      description: >-
        Retrieve a paginated list of events. Returns 50 records per page; use
        the page query parameter to page through results.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/Page'
      - name: order
        in: query
        description: Field to order results by (for example, event_start).
        required: false
        schema:
          type: string
        example: example
      - name: sort_direction
        in: query
        description: Sort direction for the ordered field.
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
        example: asc
      responses:
        '200':
          description: A paginated list of events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
              examples:
                ListEvents200Example:
                  summary: Default listEvents 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - id: 500123
                      name: Spring Gala Dinner
                      event_date: '2026-07-15'
                      start_time: '18:00'
                      end_time: '22:00'
                      status: definite
                      guest_count: 75
                      location_id: 500123
                      account_id: 500123
                      created_at: '2026-06-03T14:30:00Z'
                      updated_at: '2026-06-03T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/events/{event_id}.json:
    get:
      operationId: getEvent
      summary: Get Event
      description: Retrieve information for a single event by its identifier.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/EventId'
      responses:
        '200':
          description: The requested event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
              examples:
                GetEvent200Example:
                  summary: Default getEvent 200 response
                  x-microcks-default: true
                  value:
                    id: 500123
                    name: Spring Gala Dinner
                    event_date: '2026-07-15'
                    start_time: '18:00'
                    end_time: '22:00'
                    status: definite
                    guest_count: 75
                    location_id: 500123
                    account_id: 500123
                    created_at: '2026-06-03T14:30:00Z'
                    updated_at: '2026-06-03T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/events/search.json:
    get:
      operationId: searchEvents
      summary: Search Events
      description: Retrieve events matching the supplied query parameters.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/Page'
      - name: updated_after
        in: query
        description: Return events updated after this timestamp.
        required: false
        schema:
          type: string
          format: date-time
        example: '2026-06-03T14:30:00Z'
      responses:
        '200':
          description: A paginated list of matching events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
              examples:
                SearchEvents200Example:
                  summary: Default searchEvents 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - id: 500123
                      name: Spring Gala Dinner
                      event_date: '2026-07-15'
                      start_time: '18:00'
                      end_time: '22:00'
                      status: definite
                      guest_count: 75
                      location_id: 500123
                      account_id: 500123
                      created_at: '2026-06-03T14:30:00Z'
                      updated_at: '2026-06-03T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/accounts.json:
    get:
      operationId: listAccounts
      summary: List Accounts
      description: Retrieve a paginated list of accounts.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
              examples:
                ListAccounts200Example:
                  summary: Default listAccounts 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - id: 500123
                      name: Spring Gala Dinner
                      address: 123 Main Street
                      city: Boston
                      state: MA
                      zip_code: '02108'
                      phone_number: +1-555-867-5309
                      website: https://example.com
                      created_at: '2026-06-03T14:30:00Z'
                      updated_at: '2026-06-03T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/accounts/{account_id}.json:
    get:
      operationId: getAccount
      summary: Get Account
      description: Retrieve information for a single account by its identifier.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: The requested account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
              examples:
                GetAccount200Example:
                  summary: Default getAccount 200 response
                  x-microcks-default: true
                  value:
                    id: 500123
                    name: Spring Gala Dinner
                    address: 123 Main Street
                    city: Boston
                    state: MA
                    zip_code: '02108'
                    phone_number: +1-555-867-5309
                    website: https://example.com
                    created_at: '2026-06-03T14:30:00Z'
                    updated_at: '2026-06-03T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateAccount
      summary: Update Account
      description: Update an existing account by its identifier.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  $ref: '#/components/schemas/AccountUpdate'
              required:
              - account
            examples:
              UpdateAccountRequestExample:
                summary: Default updateAccount request
                x-microcks-default: true
                value:
                  account:
                    name: Spring Gala Dinner
                    address: 123 Main Street
                    city: Boston
                    state: MA
                    zip_code: '02108'
                    phone_number: +1-555-867-5309
                    website: https://example.com
      responses:
        '200':
          description: The updated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
              examples:
                UpdateAccount200Example:
                  summary: Default updateAccount 200 response
                  x-microcks-default: true
                  value:
                    id: 500123
                    name: Spring Gala Dinner
                    address: 123 Main Street
                    city: Boston
                    state: MA
                    zip_code: '02108'
                    phone_number: +1-555-867-5309
                    website: https://example.com
                    created_at: '2026-06-03T14:30:00Z'
                    updated_at: '2026-06-03T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/contacts.json:
    post:
      operationId: createContact
      summary: Create Contact
      description: >-
        Create a contact and associate it with an account. Every contact must
        be associated with an account via account_id.
      tags:
      - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contact:
                  $ref: '#/components/schemas/ContactCreate'
              required:
              - contact
            examples:
              CreateContactRequestExample:
                summary: Default createContact request
                x-microcks-default: true
                value:
                  contact:
                    first_name: Mark
                    last_name: Lawrence
                    email_address: contact@example.com
                    phone_number: +1-555-867-5309
                    account_id: 500123
      responses:
        '201':
          description: The contact was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
              examples:
                CreateContact201Example:
                  summary: Default createContact 201 response
                  x-microcks-default: true
                  value:
                    id: 500123
                    first_name: Mark
                    last_name: Lawrence
                    email_address: contact@example.com
                    phone_number: +1-555-867-5309
                    account_id: 500123
                    created_at: '2026-06-03T14:30:00Z'
                    updated_at: '2026-06-03T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/locations.json:
    get:
      operationId: listLocations
      summary: List Locations
      description: Retrieve all locations housed within a site.
      tags:
      - Locations
      responses:
        '200':
          description: A list of locations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Location'
              examples:
                ListLocations200Example:
                  summary: Default listLocations 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - id: 500123
                      name: Spring Gala Dinner
                      site_id: 500123
                      address: 123 Main Street
                      city: Boston
                      state: MA
                      zip_code: '02108'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/sites.json:
    get:
      operationId: listSites
      summary: List Sites
      description: >-
        Retrieve sites. A site represents a group of venues or locations.
        Creating, updating, or deleting sites via the API is not supported.
      tags:
      - Sites
      responses:
        '200':
          description: A list of sites.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Site'
              examples:
                ListSites200Example:
                  summary: Default listSites 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - id: 500123
                      name: Spring Gala Dinner
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/users.json:
    get:
      operationId: listUsers
      summary: List Users
      description: >-
        Retrieve users who can log into your Tripleseat. Creating, updating, or
        deleting users via the API is not supported.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of users.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
              examples:
                ListUsers200Example:
                  summary: Default listUsers 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - id: 500123
                      first_name: Mark
                      last_name: Lawrence
                      email_address: contact@example.com
                      active: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/users/{user_id}.json:
    get:
      operationId: getUser
      summary: Get User
      description: Retrieve information for a single user by identifier.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: The requested user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                GetUser200Example:
                  summary: Default getUser 200 response
                  x-microcks-default: true
                  value:
                    id: 500123
                    first_name: Mark
                    last_name: Lawrence
                    email_address: contact@example.com
                    active: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: >-
        OAuth 2.0. Access tokens are Bearer tokens that expire after 7200
        seconds (2 hours) and are accompanied by a refresh token. OAuth 1.0 is
        deprecated and discontinued on July 1, 2026.
      flows:
        clientCredentials:
          tokenUrl: https://api.tripleseat.com/oauth/token
          scopes: {}
        authorizationCode:
          authorizationUrl: https://api.tripleseat.com/oauth/authorize
          tokenUrl: https://api.tripleseat.com/oauth/token
          refreshUrl: https://api.tripleseat.com/oauth/token
          scopes: {}
  parameters:
    Page:
      name: page
      in: query
      description: The page of results to return. Each page contains 50 records.
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    LeadId:
      name: lead_id
      in: path
      description: The unique identifier of the lead.
      required: true
      schema:
        type: integer
    EventId:
      name: event_id
      in: path
      description: The unique identifier of the event.
      required: true
      schema:
        type: integer
    AccountId:
      name: account_id
      in: path
      description: The unique identifier of the account.
      required: true
      schema:
        type: integer
    UserId:
      name: user_id
      in: path
      description: The unique identifier of the user.
      required: true
      schema:
        type: integer
  responses:
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials were missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: >-
        The rate limit of 10 requests per second for the leads and events
        endpoints was exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Lead:
      type: object
      description: A potentially interested person or party for outreach.
      properties:
        id:
          type: integer
          description: Unique identifier of the lead.
          example: 500123
        first_name:
          type: string
          description: First name of the lead contact.
          example: Mark
        last_name:
          type: string
          description: Last name of the lead contact.
          example: Lawrence
        email_address:
          type: string
          format: email
          description: Email address of the lead contact.
          example: contact@example.com
        phone_number:
          type: string
          description: Phone number of the lead contact.
          example: +1-555-867-5309
        company:
          type: string
          description: Company associated with the lead.
          example: Acme Events Co.
        event_description:
          type: string
          description: Description of the event the lead is inquiring about.
          example: Evening reception with plated dinner.
        event_date:
          type: string
          format: date
          description: Requested date of the event.
          example: '2026-07-15'
        start_time:
          type: string
          description: Requested start time of the event.
          example: '18:00'
        end_time:
          type: string
          description: Requested end time of the event.
          example: '22:00'
        guest_count:
          type: integer
          description: Estimated number of guests.
          example: 75
        additional_information:
          type: string
          description: Additional free-text information supplied with the lead.
          example: Evening reception with plated dinner.
        location_id:
          type: integer
          description: Identifier of the location the lead is intended for.
          example: 500123
        status:
          type: string
          description: Current status of the lead.
          example: definite
        created_at:
          type: string
          format: date-time
          description: Timestamp when the lead was created.
          example: '2026-06-03T14:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the lead was last updated.
          example: '2026-06-03T14:30:00Z'
    LeadCreate:
      type: object
      description: Fields accepted when creating a lead via the public lead form.
      properties:
        first_name:
          type: string
          example: Mark
        last_name:
          type: string
          example: Lawrence
        email_address:
          type: string
          format: email
          example: contact@example.com
        phone_number:
          type: string
          example: +1-555-867-5309
        company:
          type: string
          example: Acme Events Co.
        event_description:
          type: string
          example: Evening reception with plated dinner.
        event_date:
          type: string
          format: date
          example: '2026-07-15'
        start_time:
          type: string
          example: '18:00'
        end_time:
          type: string
          example: '22:00'
        guest

# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tripleseat/refs/heads/main/openapi/tripleseat-openapi.yml