Punchh Custom Segments API

openapi: 3.2.0
info:
  title: Platform Functions Custom Segments API
  version: '1.0'
  description: This API documentation is intended to provide comprehensive information for admin users of the Punchh platform. Many of the settings and available actions depend on an appropriate level of access to Platform Functions APIs.
  contact:
    name: Punchh DevSupport
    url: https://developers.punchh.com
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: Custom Segments
paths:
  /api2/dashboard/custom_segments:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    custom_segment_id:
                      type: integer
                      description: Unique ID of a custom segment. This is generated by Punchh.
                    name:
                      type: string
                      description: Name of the custom segment as given by the admin user when creating the custom segment
                    description:
                      type: string
                      description: Description of the custom segment as given by the admin user when creating the custom segment
                    created_at:
                      type: string
                      description: Date/time when the custom segment was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
                    updated_at:
                      type: string
                      description: Date/time when the custom segment was last updated in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
              examples:
                default:
                  value:
                  - custom_segment_id: 1778
                    name: Example Custom Segment One
                    description: This segment is created as an example of custom segments.
                    created_at: '2015-06-09T13:24:02Z'
                    updated_at: '2015-06-09T14:18:14Z'
                  - custom_segment_id: 2008
                    name: Example Custom Segment two
                    description: This segment is created as second example of custom segments.
                    created_at: '2015-07-27T09:50:40Z'
                    updated_at: '2015-07-27T09:50:40Z'
        '401':
          $ref: '#/components/responses/401-unauthorized'
      summary: List All Custom Segments
      description: Returns a list of all custom segments created by a business
      operationId: dashboard_list_all_custom_segments
      tags:
      - Custom Segments
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/accept'
      - schema:
          type: string
          default: '15402'
        name: ID
        in: path
        required: true
        description: The value of the `custom_segment_id` parameter returned in the response of the [Create a Custom Segment](/docs/dev-portal-platform-functions/1fd466d125efd-create-a-custom-segment) API
      x-stoplight:
        id: 081af5761130d
    post:
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  custom_segment_id:
                    type: integer
                    description: Unique ID of the custom segment. This is generated by Punchh.
                  name:
                    type: string
                    description: Name of the custom segment as given by the admin user when creating the custom segment
                  description:
                    type: string
                    description: Description of the custom segment as given by the admin user when creating the custom segment
                  created_at:
                    type: string
                    description: Date/time when the custom segment was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
                  updated_at:
                    type: string
                    description: Date/time when custom segment was last updated in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
              examples:
                default:
                  value:
                    custom_segment_id: 15376
                    name: Dummy Custom Segment
                    description: Testing Creation of Custom Segment.
                    created_at: '2018-01-10T10:06:39Z'
                    updated_at: '2018-01-10T10:06:39Z'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: array
                    items:
                      type: string
              examples:
                default:
                  value:
                    name:
                    - Name has already been taken
      summary: Create a Custom Segment
      description: Creates an empty custom segment for a business. Users have to be added later to an empty segment.
      operationId: dashboard_create_custom_segment
      tags:
      - Custom Segments
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/accept'
      x-stoplight:
        id: 1fd466d125efd
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the custom segment that will be created
                description:
                  type: string
                  description: Description of the custom segment that will be created
            examples:
              default:
                value:
                  name: Dummy Custom Segment
                  description: Testing Creation of Custom Segment.
    patch:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  custom_segment_id:
                    type: integer
                    description: Unique ID of the custom segment. This is generated by Punchh.
                  name:
                    type: string
                    description: Name of the custom segment as given by the admin user when creating the custom segment
                  description:
                    type: string
                    description: Description of the custom segment as given by the admin user when creating the custom segment
                  created_at:
                    type: string
                    description: Date/time when the custom segment was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
                  updated_at:
                    type: string
                    description: Date/time when the custom segment was last updated in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
              examples:
                default:
                  value:
                    custom_segment_id: 15401
                    name: Updated Name - Dummy Custom Segment
                    description: Updated Description - Request to create dummy custom segment.
                    created_at: '2018-01-10T10:33:14Z'
                    updated_at: '2018-01-10T10:37:21Z'
        '401':
          $ref: '#/components/responses/401-unauthorized'
      summary: Update a Custom Segment
      description: Updates the name and/or description of a custom segment
      operationId: dashboard_update_custom_segment
      tags:
      - Custom Segments
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - schema:
          type: string
        in: query
        name: name
        description: Updated name of the custom segment
      - schema:
          type: string
        in: query
        name: description
        description: Updated description of the custom segment
      - schema:
          type: string
        in: query
        name: custom_segment_id
        description: Unique ID of the custom segment that will be updated. This ID is generated by Punchh when the custom segment is created.
      - $ref: '#/components/parameters/accept'
      x-stoplight:
        id: c70c06b464328
    delete:
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: string
              examples:
                default:
                  value:
                    accepted: Custom Segment Dummy Custom Segment has been marked for deletion
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      not_found:
                        type: string
              examples:
                default:
                  value:
                    errors:
                      not_found: Custom Segment not found.
      summary: Delete a Custom Segment
      description: Deletes a custom segment from the database
      operationId: dashboard_delete_custom_segment
      tags:
      - Custom Segments
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - schema:
          type: string
        in: query
        name: custom_segment_id
        description: Unique ID of the custom segment that will be deleted
      - $ref: '#/components/parameters/accept'
      x-stoplight:
        id: c1c3e6c17e5ab
  /api2/dashboard/custom_segments/members:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    custom_segment_member_id:
                      description: Unique alphanumeric ID assigned to the user when the user becomes a member of a particular custom segment. One user can belong to multiple custom segments. This is not the Punchh identifier.
                      type: string
                    custom_segment_id:
                      type: integer
                      description: Unique ID of the custom segment. This is generated by Punchh.
                    email:
                      type: string
                      description: Email address of the user
                    user_id:
                      type: integer
                      description: Unique ID of the user. This is generated by Punchh.
                    created_at:
                      type: string
                      description: Date/time when the user was added to the custom segment, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
                    updated_at:
                      type: string
                      description: Date/time when the user was last updated as a part of the custom segment, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
              examples:
                default:
                  value:
                  - custom_segment_member_id: 84767860
                    custom_segment_id: 15402
                    email: test@example.com
                    user_id: 111111111
                    created_at: '2018-01-10T11:54:11Z'
                    updated_at: '2018-01-10T11:54:11Z'
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              examples:
                default:
                  value:
                    error: 'Required parameter missing or the value is empty: user_id'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      not_found:
                        type: string
              examples:
                default:
                  value:
                    errors:
                      not_found: Member not found.
      summary: Search If User Exists in a Custom Segment
      description: Determines if a specific user belongs to a custom segment. Either `email` or `user_id` should be provided in the request to search for the user; `user_id` will be preferred if both are provided.
      operationId: dashboard_search_user_in_custom_segment
      tags:
      - Custom Segments
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - schema:
          type: string
        in: query
        name: custom_segment_id
        description: Unique ID of the custom segment
      - schema:
          type: string
        in: query
        name: email
        description: Email address of the user
      - $ref: '#/components/parameters/accept'
      - schema:
          type: integer
          format: int64
        in: query
        name: user_id
        description: Unique ID of the user. This is generated by Punchh.
      x-stoplight:
        id: ccb989674e456
    post:
      responses:
        '201':
          description: User exists in Punchh.
          content:
            application/json:
              schema:
                type: object
                properties:
                  custom_segment_member_id:
                    type: string
                    description: Unique alphanumeric ID assigned to the user when the user becomes a member of a particular custom segment. One user can belong to multiple custom segments. This is not the Punchh identifier.
                  custom_segment_id:
                    type: integer
                    description: Unique ID of the custom segment. This is generated by Punchh.
                  email:
                    type: string
                    description: Email address of the user who was added to the custom segment
                  user_id:
                    type: integer
                    description: Unique ID of the user who was added to the custom segment. This is generated by Punchh.
                  created_at:
                    type: string
                    description: Date/time when the user was added to the custom segment, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
                  updated_at:
                    type: string
                    description: Date/time when the user was last updated as a part of the custom segment, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
              examples:
                default:
                  value:
                    custom_segment_member_id: 84767857
                    custom_segment_id: 15401
                    email: test@example.com
                    user_id: 111111111
                    created_at: '2018-01-10T10:53:43Z'
                    updated_at: '2018-01-10T10:53:43Z'
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              examples:
                default:
                  value:
                    error: 'Required parameter missing or the value is empty: user_id'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      not_found:
                        type: string
              examples:
                default:
                  value:
                    errors:
                      not_found: User does not exist.
      summary: Add User to a Custom Segment
      description: Adds a user to a custom segment. Either `email` or `user_id` should be provided in the request; `user_id` will be preferred if both are provided.
      operationId: dashboard_add_user_to_custom_segment
      tags:
      - Custom Segments
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/accept'
      x-stoplight:
        id: 58a8f70354885
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                custom_segment_id:
                  type: integer
                  description: Unique ID of the custom segment to which the user will be added
                  format: int64
                email:
                  type: string
                  description: Email address of the user
                user_id:
                  type: integer
                  description: Unique ID of the user. This is generated by Punchh.
                  format: int64
            examples:
              default:
                value:
                  custom_segment_id: 15401
                  email: test@example.com
    delete:
      responses:
        '204':
          description: You will receive a 204 blank response.
          content:
            application/json:
              schema:
                type: object
                properties: {}
      summary: Remove User From a Custom Segment
      description: Removes a user from a custom segment. Either `email` or `user_id` should be provided in the request; `user_id` will be preferred if both are provided.
      operationId: dashboard_remove_user_from_custom_segment
      tags:
      - Custom Segments
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - schema:
          type: integer
          format: int64
        in: query
        name: custom_segment_id
        description: Unique ID of the custom segment from which the user will be removed. This is assigned by Punchh.
      - schema:
          type: string
        in: query
        name: email
        description: Email address of the user
      - $ref: '#/components/parameters/accept'
      - schema:
          type: integer
          format: int64
        in: query
        name: user_id
        description: Unique ID of the user. This is generated by Punchh.
      x-stoplight:
        id: 0cc855124a01f
  /api2/dashboard/custom_segments/members/bulk_add:
    post:
      summary: Bulk Add Users to a Custom Segment
      operationId: post-api2-dashboard-custom_segments-members-bulk_add
      responses:
        '200':
          description: OK
        '302':
          description: The user account does not have the required permission to perform this operation.
          content:
            application/json:
              schema:
                type: object
                properties: {}
      description: "This API allows you to add users in bulk to a custom segment by uploading a CSV file that contains a list of users and their details. The uploaded file must be a CSV file. \n\nThe CSV file will have two columns: \"user_id\" and \"email\". The \"user_id\" column contains all user IDs that need to be added to the custom segment. Either email or user ID should be passed in the CSV file. If both email and user ID values are provided in the CSV file, the look-up process for adding user IDs to the custom segment will use both the \"email\" and \"user_id\" fields to identify the guests to be added.\n\nOnce the uploaded CSV file is processed, you will receive a response file on the registered email ID with details of success/failure against each entry, along with validation errors if applicable.\n\nThe changes you request through this API call may not take effect immediately. Instead, they are queued up and processed in the order they were received, depending on the availability of resources to process the requests. All changes made via this API are reflected in the audit logs.\n\nThis API can be triggered only in limited time slots defined by Punchh. The time slot designated by Punchh for this operation is from 9:30 PM EST to 5:30 AM EST. Requests triggered outside of the defined time slot will be rejected.\n\n<b>Permission required</b>: Admin account with Business Manager permission. Accounts without required permission will receive a 302 error response. "
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/authorization-header'
      tags:
      - Custom Segments
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  x-stoplight:
                    id: 3sg2p4czwht6a
                  description: Unique name assigned to this bulk user addition activity
                custom_segment_id:
                  type: integer
                  x-stoplight:
                    id: yqwztdxwoipbw
                  description: Unique ID of the custom segment to which users will be added
                bulk_guest_activity_file:
                  type: string
                  x-stoplight:
                    id: azw6p1pizlp7i
                  description: Local path to the CSV file. The CSV will include the user IDs that will be added to the specified custom segment. Only CSV file format is supported, and the maximum supported file size is 15 MB.
              required:
              - name
              - custom_segment_id
              - bulk_guest_activity_file
            examples:
              default:
                value:
                  name: custom_seg_perf1
                  custom_segment_id: 110443
                  bulk_guest_activity_file: CSV_FILE_PATH_GOES_HERE
        description: "The request for this API endpoint is passed using form data, as shown in the following example.\n```curl\ncurl --request POST \\\n  --url https://server_name_goes_here.punchh.com/api2/dashboard/custom_segments/members/bulk_add \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer BUSINESS_ADMIN_KEY_GOES_HERE' \\\n  --header 'Content-Type: application/json' \\\n  —form 'name=\"custom_seg_perf1\"' \\\n  —form 'custom_segment_id=110443'   \\\n  —form 'bulk_guest_activity_file=@\"CSV_FILE_PATH_GOES_HERE\"'"
  /api2/dashboard/custom_segments/members/bulk_remove:
    delete:
      summary: Bulk Remove Users From a Custom Segment
      operationId: delete-api2-dashboard-custom_segments-members-bulk_remove
      responses:
        '200':
          description: OK
        '302':
          description: The user account does not have the required permission to perform this operation.
          content:
            application/json:
              schema:
                type: object
                properties: {}
      description: 'This API allows you to remove users in bulk from a custom segment by uploading a CSV file that contains a list of users and their details. The uploaded file must be a CSV file.


        The CSV file will have two columns: "user_id" and "email". The "user_id" column contains all user IDs that need to be removed from the custom segment. Either email or user ID should be passed in the CSV file. If both email and user ID values are provided in the CSV file, the look-up process for deleting user IDs from the custom segment will use both the "email" and "user_id" fields to identify the guests to be deleted.


        Once the uploaded CSV file is processed, you will receive a response file on the registered email ID with details of success/failure against each entry, along with validation errors if applicable.


        The changes you request through this API call may not take effect immediately. Instead, they are queued up and processed in the order they were received, depending on the availability of resources to process the requests. All changes made via this API are reflected in the audit logs.


        This API can be triggered only in limited time slots defined by Punchh. The time slot designated by Punchh for this operation is from 9:30 PM EST to 5:30 AM EST. Requests triggered outside of the defined time slot will be rejected.


        <b>Permission required</b>: Admin account with Business Manager permission. Accounts without required permission will receive a 302 error response. '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/authorization-header'
      tags:
      - Custom Segments
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  x-stoplight:
                    id: n5efr1r8vvdeq
                  description: Unique name assigned to this bulk user removal activity
                custom_segment_id:
                  type: integer
                  x-stoplight:
                    id: b1ck8t0joiuab
                  description: Unique ID of the custom segment from which users will be removed
                bulk_guest_activity_file:
                  type: string
                  x-stoplight:
                    id: 29dlqfer0sfhh
                  description: Local path to the CSV file. The CSV will include the user IDs that will be removed from the specified custom segment. Only CSV file format is supported, and the maximum supported file size is 15 MB.
              required:
              - name
              - custom_segment_id
              - bulk_guest_activity_file
            examples:
              default:
                value:
                  name: custom_seg_perf1
                  custom_segment_id: 110444
                  bulk_guest_activity_file: CSV_FILE_PATH_GOES_HERE
        description: "The request for this API endpoint is passed using form data, as shown in the following example.\n```curl\ncurl --request DELETE \\\n  --url https://server_name_goes_here.punchh.com/api2/dashboard/custom_segments/members/bulk_remove \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer BUSINESS_ADMIN_KEY_GOES_HERE' \\\n  --header 'Content-Type: application/json' \\\n  —form 'name=\"custom_seg_perf1\"' \\\n  —form 'custom_segment_id=110444' \\\n  —form 'bulk_guest_activity_file=@\"CSV_FILE_PATH_GOES_HERE\"'"
  /api2/dashboard/custom_segments/members/add_users:
    post:
      summary: Bulk Add Users to a Custom List Segment
      operationId: post-api2-dashboard-custom_segments-members-add_users
      responses:
        '200':
          description: OK - If invalid user identifiers are specified, the response returns the list of these identifiers under 200.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invalid_identifiers:
                    type: array
                    x-stoplight:
                      id: 9leoofytxxxvh
                    items:
                      x-stoplight:
                        id: 0hbrmohoq0lkl
                      type: string
              examples:
                Invalid Identifiers:
                  value:
                    invalid_identifiers:
                    - efsfsef
                    - 78439fer
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    x-stoplight:
                      id: 7xp2465evqhoy
                    properties:
                      limit_exceed:
                        type: string
                        x-stoplight:
                          id: w56zezq9a2o05
              examples:
                Limit exceeded in async mode:
                  value:
                    errors:
                      limit_exceed: Max 1000 users allowed per api call in async mode
      description: 'Adds users in bulk to a custom list segment using their email addresses and IDs. This API supports both sync and async modes. It validates the provided email addresses and IDs, returning a list of invalid identifiers that are neither valid integer IDs nor valid email addresses.


        <b>Async Mode</b><br>

        Async, or asynchronous, mode is the preferred method for using this API. In this mode, the API processes the users'' email addresses and IDs provided in the request in the background. You can specify up to 1,000 user identifiers (email addresses and IDs) per API call.


        <b>Sync Mode</b><br>

        Sync, or synchronous, mode is an alternative method for using this API. In this mode, the API processes the users'' email addresses and IDs provided in the request and immediately attaches them to the segment. This mode is slower and subject to rate limits to ensure system stability and prevent overload. You can include up to 100 user identifiers (email addresses and IDs) per API call.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/authorization-header'
      tags:
      - Custom Segments
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                bulk_method:
                  type: string
                  x-stoplight:
                    id: 8508ice3ap2y6
                  description: 'Method to use for adding users in bulk. Possible values: sync, async. Specify ''sync'' for synchronous processing, where users are created one by one in sequence, or ''async'' for asynchronous processing, where user creation tasks are handled concurrently to improve efficiency. If no value is specified, ''async'' mode is used by default. '
                custom_segment_id:
                  type: integer
                  x-stoplight:
                    id: 03bkhlcxcf8eb
                  description: Unique ID of the custom list segment to which users will be added
                user_identifiers:
                  type: array
                  x-stoplight:
                    id: qb2t4xuqm66f6
                  description: Email addresses and/or IDs of users to be added to the specified custom list segment. You can specify up to 1,000 users per API call in asynchronous mode and up to 100 users per API call in synchronous mode. If both an email address and an ID are provided as identifiers for a single user, they are treated as two separate entries for the purpose of the limit, reducing the maximum count by 2. However, only one user will be added to the segment in the system.
                  items:
                    x-stoplight:
                      id: jjnriv06vb157
                    type: string
              required:
              - custom_segment_id
              - user_identifiers
            examples:
              Adding users in Sync mode:
                value:
                  bulk_method: sync
                  custom_segment_id: 120966
                  user_identifiers:
                  - test@example.com
                  - '76563563'
                  - test1@example.com
                  - '76563564'
              Adding users in Async mode:
                value:
                  bulk_method: async
                  custom_segment_id: 120971
                  user_identifiers:
                  - test@example.com
                  - '76563562'
                  - test1@example.com
                  - '76563561'
        description: ''
components:
  parameters:
    accept:
      schema:
        typ

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