TableCheck customers API

openapi: 3.0.0
info:
  version: 1.0.0
  title: TableCheck API - V1 availability customers API
  description: The Availability API is used to obtain near real-time table availability for online reservation booking.
  termsOfService: https://tablecheck.atlassian.net/wiki/spaces/API/pages/61571353/TableCheck+API+Terms+of+Service
servers:
- url: https://api.tablecheck.com/api/availability/v1/
  description: Production (uses live data)
security:
- ApiKeyAuth: []
tags:
- name: customers
paths:
  /customers:
    get:
      summary: List all Customers
      operationId: listCustomers
      tags:
      - customers
      parameters:
      - name: ids
        in: query
        description: Array or comma-separated list of specific customer IDs to return.
        required: false
        schema:
          type: string
          format: bson-id
      - name: shop_ids
        in: query
        description: Array or comma-separated list of specific shop IDs.
        required: false
        schema:
          type: string
          format: bson-id
      - name: created_at_min
        in: query
        description: Search lower bound of created_at field (ISO timestamp).
        required: false
        schema:
          type: string
          format: date-time
      - name: created_at_max
        in: query
        description: Search upper bound of created_at field (ISO timestamp).
        required: false
        schema:
          type: string
          format: date-time
      - name: updated_at_min
        in: query
        description: Search lower bound of updated_at field (ISO timestamp).
        required: false
        schema:
          type: string
          format: date-time
      - name: updated_at_max
        in: query
        description: Search upper bound of updated_at field (ISO timestamp).
        required: false
        schema:
          type: string
          format: date-time
      - name: page
        in: query
        description: The zero-based page number. Used for pagination.
        required: false
        schema:
          type: number
          format: integer
          minimum: 0
      - name: per_page
        in: query
        description: Number of items to return at once. Used for pagination.
        required: false
        schema:
          type: number
          format: integer
          default: 100
          minimum: 1
          maximum: 1000
      - $ref: '#/components/parameters/IncludeFields'
      - $ref: '#/components/parameters/ExcludeFields'
      responses:
        '200':
          description: A paged array of customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomersListResponse'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a new customer
      operationId: createCustomer
      tags:
      - customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreateParams'
      responses:
        '200':
          description: Information about the customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerShowResponse'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customers/{customer_id}:
    get:
      summary: Fetch a specific Customer
      operationId: showCustomerById
      tags:
      - customers
      parameters:
      - name: customer_id
        in: path
        required: true
        description: The ID of the Customer to retrieve
        schema:
          type: string
      - $ref: '#/components/parameters/IncludeFields'
      - $ref: '#/components/parameters/ExcludeFields'
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerShowResponse'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Amend the Customer
      operationId: amendCustomer
      tags:
      - customers
      parameters:
      - name: customer_id
        in: path
        required: true
        description: The ID of the Customer to retrieve
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUpdateParams'
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerShowResponse'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Destroy the customer
      operationId: deleteCustomerById
      tags:
      - customers
      parameters:
      - name: customer_id
        in: path
        required: true
        description: The ID of the Customer to delete
        schema:
          type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    default: ok
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customer_search:
    post:
      summary: Search and bulk export customers
      operationId: customerSearch
      tags:
      - customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerSearchParams'
      responses:
        '200':
          description: List of exported customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSearchResponse'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    ExcludeFields:
      name: exclude_fields
      in: query
      description: Comma-separated list of fields to exclude from the response (blacklist). All fields except the given ones will be returned. Supports dot notation for nested fields.
      required: false
      schema:
        type: string
      example: created_at,socials.username
    IncludeFields:
      name: include_fields
      in: query
      description: Comma-separated list of fields to include in the response (whitelist). If specified, only the listed fields will be returned. Supports dot notation for nested fields.
      required: false
      schema:
        type: string
      example: id,name,addresses.city
  schemas:
    MembershipEmbed:
      type: object
      properties:
        id:
          description: The database ID of the Membership.
          type: string
          format: bson-id
        code:
          type: string
        membership_program_id:
          description: The database ID of the Membership Program.
          type: string
          format: bson-id
        membership_program_name:
          type: string
        membership_tier_id:
          description: The database ID of the Membership Tier.
          type: string
          format: bson-id
        membership_tier_name:
          type: string
        status:
          description: The status of the membership.
          type: string
          enum:
          - active
          - pre_enrollment
          - cancelled
        points:
          description: The number of points available on the membership.
          type: number
          format: integer
    ImageEmbed:
      properties:
        id:
          description: The database ID of the Image.
          type: string
          format: bson-id
          example: 65dcd5f935288116d268b45b
        url:
          description: The URL of the image as a large size JPEG.
          type: string
          format: url
          example: https://cdn1.tablecheck.com/images/92a543f5085ea8b1ffbe000a/images/xl/image.jpg
        content_type:
          description: The MIME content type of the image.
          type: string
          example: image/jpeg
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/ImageDimensions'
          example:
          - 200
          - 200
        fingerprint:
          description: The fingerprint of the image used for deduplication.
          type: string
          example: af6515a29e04ac61d4379a3181140647
        image_variants:
          description: A list of image size variants scaled to different sizes.
          type: array
          items:
            $ref: '#/components/schemas/ImageVariants'
        tags:
          description: Not used.
          type: array
          example: []
        created_at:
          type: string
          format: date-time
    Emails:
      description: '[PII] A list of Email objects.'
      type: array
      items:
        $ref: '#/components/schemas/Email'
    ElasticCustomer:
      properties:
        id:
          description: The database ID of the Customer.
          type: string
          format: bson-id
        created_at:
          type: string
        updated_at:
          type: string
        name:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        alt_first_name:
          type: string
        alt_last_name:
          type: string
        company_name:
          type: string
        company_title:
          type: string
        company_division:
          type: string
        gender:
          type: string
          enum:
          - male
          - female
        locale:
          type: string
          enum:
          - en
          - ja
          - ko
          - zh-CN
          - zh-TW
          - de
          - es
          - fr
          - nl
          - it
          - pt
          - tr
          - ru
          - id
          - ms
          - tl
          - th
          - lo
          - km
          - vi
          - ar
          - he
          - hi
        phones:
          type: array
          items:
            type: string
            format: phone-e164
        emails:
          type: array
          items:
            type: string
            format: email
        tags:
          type: array
          items:
            type: string
        likes:
          type: array
          items:
            type: string
        dislikes:
          type: array
          items:
            type: string
        allergies:
          type: array
          items:
            type: string
        is_temporary:
          type: boolean
        allow_marketing:
          type: boolean
        allow_direct_mail:
          type: boolean
        memo:
          type: string
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        memberships:
          type: array
          items:
            $ref: '#/components/schemas/ElasticMembership'
    PaginationData:
      type: object
      properties:
        page:
          type: number
          format: integer
          example: 3
        per_page:
          type: number
          format: integer
          example: 100
    Error:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: not_found
              message:
                type: string
                example: Item not found
    ElasticMembership:
      properties:
        id:
          description: The database ID of the Membership.
          type: string
          format: bson-id
        code:
          type: string
        membership_program_id:
          description: The database ID of the Membership Program.
          type: string
          format: bson-id
        membership_tier_id:
          description: The database ID of the Membership Tier.
          type: string
          format: bson-id
    ImageEmbedDestroy:
      type: object
      example:
        id: 65dcd5f935288116d268b45b
        _destroy: true
      properties:
        id:
          description: The database ID of the Image object.
          type: string
          format: bson-id
          example: 65dcd5f935288116d268b45b
        _destroy:
          description: Destroys the image
          type: boolean
          example: true
    CustomersListResponse:
      type: object
      properties:
        customers:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
        pagination:
          $ref: '#/components/schemas/PaginationData'
    Social:
      type: object
      required:
      - username
      properties:
        id:
          description: The database ID of the Social object.
          type: string
          format: bson-id
        service:
          type: string
          enum:
          - facebook
          - google
          - twitter
          - line
          - kakao
          - naver
          - yahoo
          - mixi
          - ameblo
          - linkedin
          - skype
          - wechat
          - weibo
          - qq
        username:
          description: '[PII] The social media username.'
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ImageDimensions:
      properties:
        large:
          type: array
          items:
            type: number
          example:
          - 1280
          - 704
        medium:
          type: array
          items:
            type: number
          example:
          - 800
          - 440
        small:
          type: array
          items:
            type: number
          example:
          - 256
          - 141
    ImageVariants:
      properties:
        variant:
          type: string
          enum:
          - original
          - large
          - medium
          - small
        url:
          type: string
          format: url
          example: https://cdn1.tablecheck.com/images/92a543f5085ea8b1ffbe000a/images/xl/image.jpg
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/ImageDimensions'
          example:
          - 2000
          - 1500
        content_type:
          description: The MIME content type of the image variant.
          type: string
          example: image/jpeg
    Email:
      type: object
      required:
      - email
      properties:
        id:
          description: The database ID of the Email object.
          type: string
          format: bson-id
        email:
          description: '[PII] The email address.'
          type: string
        tag:
          type: string
          enum:
          - none
          - home
          - work
          - mobile
          - other
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    PhoneNumbersList:
      description: '[PII] A list of phone numbers as strings.'
      type: array
      items:
        type: string
        format: phone-e164
    CustomerSearchParams:
      type: object
      properties:
        scroll_id:
          type: string
          description: Cursor identifier used for query continuation.
        franchise_id:
          type: string
          format: bson-id
          description: Optional identifier for Franchise. The customer search API endpoint is currently limited to exporting one franchise at a time.
        first_name:
          type: string
          description: Search by Customer first name. Can be a partial match.
        last_name:
          type: string
          description: Search by Customer last name. Can be a partial match.
        alt_first_name:
          type: string
          description: Search by Customer alternate first name (e.g. kanji, etc.) Can be a partial match.
        alt_last_name:
          type: string
          description: Search by Customer alternate last name (e.g. kanji, etc.) Can be a partial match.
        company_name:
          type: string
          description: Search by Customer company name. Can be a partial match.
        company_division:
          type: string
          description: Search by Customer corporate division. Can be a partial match.
        company_title:
          type: string
          description: Search by Customer corporate title. Can be a partial match.
        has_phone:
          type: boolean
          description: Filter based on whether Customer has at least one phone number set.
        phone:
          type: string
          format: phone-e164
          description: Search by Customer phone number in E.164 format. Can be a partial match.
        has_email:
          type: boolean
          description: Filter based on whether Customer has at least one email address set.
        email:
          type: string
          description: Search by Customer email address. Can be a partial match.
        memo:
          type: string
          description: Text search within Customer memo. Can be a partial match.
        shop_memos_memo:
          type: string
          description: Text search within Customer shop-specific memos. Can be a partial match.
        shop_memos_shop_ids:
          type: array
          description: Constrains shop memo search match to specific shop IDs. Can be a partial match.
          items:
            type: string
            format: bson-id
        gender:
          type: string
          description: Match Customer based on gender.
          enum:
          - male
          - female
        allow_marketing:
          type: boolean
          description: Filter based on whether Customer allows email direct marketing.
        direct_mail:
          type: boolean
          description: Filter based on whether Customer allows physical mail marketing.
        is_temporary:
          type: boolean
          description: Filter based on whether Customer has "temporary" flag set.
        tags:
          type: array
          description: Filter based on array of Customer tags.
          items:
            type: string
        likes:
          type: array
          description: Filter based on array of Customer like preferences.
          items:
            type: string
        dislikes:
          type: array
          description: Filter based on array of Customer dislikes.
          items:
            type: string
        allergies:
          type: array
          description: Filter based on array of Customer allergies.
          items:
            type: string
        age_ranges:
          type: array
          description: Filter based on array of Customer age range values.
          items:
            type: string
            enum:
            - none
            - 20s
            - 30s
            - 40s
            - 50s
            - 60s
        sales_rep_ids:
          type: array
          description: Filter based on array of Sales Rep IDs.
          items:
            type: string
        assigned_staff_ids:
          type: array
          description: Filter based on array of Assigned Staffs IDs.
          items:
            type: string
        parent_shop_ids:
          type: array
          description: Filter based on array of Parent Shop IDs.
          items:
            type: string
            format: bson-id
        locales:
          type: array
          description: Filter based on array of ISO language identifiers.
          items:
            type: string
            enum:
            - en
            - ja
            - ko
            - zh-CN
            - zh-TW
            - de
            - es
            - fr
            - nl
            - it
            - pt
            - tr
            - ru
            - id
            - ms
            - tl
            - th
            - lo
            - km
            - vi
            - ar
            - he
            - hi
        social_username:
          type: string
        event_date_min:
          type: string
          format: date
        event_date_max:
          type: string
          format: date
        event_tags:
          type: array
          items:
            type: string
        event_months:
          type: array
          items:
            type: string
        created_at_min:
          type: string
          format: date-time
          description: Minimum value for time range search of Customer creation timestamp.
        created_at_max:
          type: string
          format: date-time
          description: Maximum value for time range search of Customer creation timestamp.
        updated_at_min:
          type: string
          format: date-time
          description: Minimum value for time range search of Customer updated timestamp.
        updated_at_max:
          type: string
          format: date-time
          description: Maximum value for time range search of Customer updated timestamp.
        address_postal_code:
          type: string
          description: Search by Customer address postal code.
        address_country:
          type: string
          format: country
          description: Search by Customer address country.
        address_region:
          type: string
          description: Search by Customer region/state/province.
        address_city:
          type: string
          description: Search by Customer city.
        reservation_stages:
          description: For Reservation search parameters, sets a basic scope to query past, future, and/or cancelled reservations.
          type: array
          items:
            type: string
            enum:
            - past
            - future
            - cancelled
            - rejected
        reservation_start_date_min:
          type: string
          format: date
          description: Minimum value for date range search of Reservation start time.
        reservation_start_date_max:
          type: string
          format: date
          description: Maximum value for date range search of Reservation start time.
        reservation_created_date_min:
          type: string
          format: date
          description: Minimum value for date range search of Reservation creation timestamp.
        reservation_created_date_max:
          type: string
          format: date
          description: Maximum value for date range search of Reservation creation timestamp.
        reservation_updated_date_min:
          type: string
          format: date
          description: Minimum value for date range search of Reservation updated timestamp.
        reservation_updated_date_max:
          type: string
          format: date
          description: Maximum value for date range search of Reservation updated timestamp.
        reservation_pax_min:
          type: number
          format: integer
          description: Minimum value for range search of Reservation party size.
        reservation_pax_max:
          type: number
          format: integer
          description: Maximum value for range search of Reservation party size.
        reservation_count_visits_min:
          type: number
          format: integer
          description: Minimum value for range search of total visit count across all venues.
        reservation_count_visits_max:
          type: number
          format: integer
          description: Maximum value for range search of total visit count across all venues.
        reservation_shop_visits_min:
          type: number
          format: integer
          description: Minimum value for range search of visit count at an individual venue.
        reservation_shop_visits_max:
          type: number
          format: integer
          description: Maximum value for range search of visit count at an individual venue.
        reservation_shop_cancels_min:
          type: number
          format: integer
          description: Minimum value for range search of cancellation count.
        reservation_shop_cancels_max:
          type: number
          format: integer
          description: Maximum value for range search of cancellation count.
        reservation_shop_noshows_min:
          type: number
          format: integer
          description: Minimum value for range search of no-show count.
        reservation_shop_noshows_max:
          type: number
          format: integer
          description: Maximum value for range search of no-show count.
        reservation_memo:
          type: string
          description: Text search of Reservation memos.
        reservation_ref:
          type: string
          description: Search by Reservation code or identifier.
        reservation_party_name:
          type: string
          description: Search by Reservation party name.
        reservation_room_name:
          type: string
          description: Search by room number present on Reservation.
        reservation_flag_ids:
          type: array
          items:
            type: string
            format: bson-id
        reservation_statuses:
          type: array
          items:
            type: string
        reservation_status_ids:
          type: array
          items:
            type: string
            format: bson-id
        reservation_objectives:
          type: array
          items:
            type: string
        reservation_shop_ids:
          type: array
          items:
            type: string
            format: bson-id
        reservation_sources:
          type: array
          items:
            type: string
        reservation_channels:
          type: array
          items:
            type: string
        reservation_providers:
          type: array
          items:
            type: string
        membership_program_id:
          type: string
        membership_tier_id:
          type: string
        membership_code:
          type: string
        membership_points_min:
          type: string
        membership_points_max:
          type: string
        membership_start_date_min:
          type: string
          format: date
        membership_start_date_max:
          type: string
          format: date
        membership_expiry_date_min:
          type: string
          format: date
        membership_expiry_date_max:
          type: string
          format: date
        payment_currency:
          type: string
          enum:
          - local
          - USD
          description: Currency applicable for Payment search parameters. Either local currency (default) or USD.
        payment_average_amt_min:
          type: string
          format: float
        payment_average_amt_max:
          type: string
          format: float
        payment_lifetime_amt_min:
          type: string
          format: float
        payment_lifetime_amt_max:
          type: string
          format: float
        payment_last_amt_min:
          type: string
          format: float
        payment_last_amt_max:
          type: string
          format: float
        payment_avg_spend_per_pax_min:
          type: string
          format: float
        payment_avg_spend_per_pax_max:
          type: string
          format: float
        pos_menu_condition:
          type: string
        pos_currency:
          type: string
          description: Currency applicable for POS search parameters. Either local currency (default) or USD.
        pos_average_amt_min:
          type: string
          format: float
        pos_average_amt_max:
          type: string
          format: float
        pos_lifetime_amt_min:
          type: string
          format: float
        pos_lifetime_amt_max:
          type: string
          format: float
        pos_last_amt_min:
          type: string
          format: float
        pos_last_amt_max:
          type: string
          format: float
        pos_avg_spend_per_pax_min:
          type: string
          format: float
        pos_avg_spend_per_pax_max:
          type: string
          format: float
        pos_menu_category_name:
          type: string
        pos_menu_item_name:
          type: string
        pos_price_min:
          type: string
          format: float
        pos_price_max:
          type: string
          format: float
        pos_qty_min:
          type: number
          format: integer
        pos_qty_max:
          type: number
          format: integer
        pos_total_min:
          type: string
          format: float
        pos_total_max:
          type: string
          format: float
        pos_shop_ids:
          type: array
          items:
            type: string
            format: bson-id
        order_currency:
          type: string
          description: Currency applicable for Order search parameters. Either local currency (default) or USD.
        order_menu_category_name:
          type: string
        order_menu_item_name:
          type: string
        order_menu_category_id:
          type: string
          format: bson-id
        order_menu_item_id:
          type: string
          format: bson-id
        order_price_min:
          type: string
          format: float
        order_price_max:
          type: string
          format: float
        order_qty_min:
          type: number
          format: integer
        order_qty_max:
          type: number
          format: integer
        order_total_min:
          type: string
          format: float
        order_total_max:
          type: string
          format: float
    CustomerCreateParams:
      type: object
      required:
      - franchise_id
      properties:
        parent_shop_id:
          description: One of your shop ID
          type: string
          format: bson-id
        name_prefix:
          description: Salutation, e.g. "Mr.", "Mrs." etc.
          type: string
        first_name:
          description: First name
          type: string
        last_name:
          description: Last name
          type: string
        company_name:
          description: Company name
          type: string
        phones:
          description: Phones
          oneOf:
          - $ref: '#/components/schemas/Phones'
          - $ref: '#/components/schemas/PhoneNumbersList'
        overwrite_phones:
          description: If true, sending the "phones" attribute will overwrite all existing Phones on the Customer.
          type: boolean
        emails:
          description: Emails
          oneOf:
          - $ref: '#/components/schemas/Emails'
          - $ref: '#/components/schemas/EmailAddressesList'
        overwrite_emails:
          description: If true, sending the "emails" attribute will overwrite all existing Emails on the Customer.
          type: boolean
        socials:
          description: Social media accounts
          type: array
          items:
            $ref: '#/components/schemas/Social'
        images:
          description: Images
          type: array
          items:
            $ref: '#/components/schemas/ImageEmbedCreate'
        overwrite_socials:
          description: If true, sending the "socials" attribute will overwrite all existing Socials on the Customer.
          type: boolean
        events:
          description: Events
          type: array
          items:
            $ref: '#/components/schemas/Event'
        overwrite_events:
          description: If true, sending the "events" attribute will overwrite all existing Events on the Customer.
          type: boolean
        addresses:
          description: Addresses
          type: array
          items:
            $ref: '#/components/schemas/Address'
        overwrite_addresses:
          description: If true, sending the "address

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