Punchh Business Admin Users API

openapi: 3.2.0
info:
  title: Platform Functions Business Admin Users 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: Business Admin Users
paths:
  /api2/dashboard/roles:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    role_id:
                      type: integer
                      description: Unique ID assigned by Punchh to a role created by an admin from the Punchh platform
                    name:
                      type: string
                      description: Name of a role created by an admin from the Punchh platform
              examples:
                default:
                  value:
                  - role_id: 214
                    name: Business Owner
                  - role_id: 215
                    name: Business Manager
                  - role_id: 216
                    name: Site Admin
                  - role_id: 511
                    name: Limited Site Admin
        '401':
          $ref: '#/components/responses/401-unauthorized'
      summary: Get Admin Roles List
      description: Returns the list of roles created in a business
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      operationId: dashboard_get_admin_roles_list
      tags:
      - Business Admin Users
      x-stoplight:
        id: baf04e66e4da3
  /api2/dashboard/business_admins:
    post:
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    description: Email address of the business admin
                  first_name:
                    type: string
                    description: First name of the business admin
                  last_name:
                    type: string
                    description: Last name of the business admin
                  timezone:
                    type: string
                    description: Time zone displayed (e.g., "America/Los_Angeles") when the business admin views stats and events in the Punchh platform
                  role_id:
                    type: integer
                    description: Unique ID of the role assigned to the business admin. This ID is generated by Punchh.
                  business_admin_id:
                    type: integer
                    description: Unique ID assigned to the business admin
                  read_only:
                    type: boolean
                    description: Whether the business admin is read-only or not
                  suspend:
                    type: boolean
                    description: Whether the business admin has been suspended or not
                  franchisee_id:
                    type: integer
                    description: Unique franchisee ID associated with the business admin (enabled for the franchisee model only)
                  locations:
                    type: array
                    description: Locations that the business admin can access in the Punchh platform
                    items:
                      type: object
                      properties:
                        location_id:
                          type: integer
                          description: ID of the location that the business admin can access
                        store_number:
                          type: string
                          description: Store number of the location that the business admin can access
                  location_groups:
                    type: array
                    description: Location groups that the business admin can access in the Punchh platform
                    items:
                      type: object
                      properties:
                        location_group_id:
                          type: integer
                          description: ID of the location group that the business admin can access
                        name:
                          type: string
                          description: Name of the location group that the business admin can access
              examples:
                default:
                  value:
                    email: test@example.com
                    first_name: FIRST_NAME_GOES_HERE
                    last_name: LAST_NAME_GOES_HERE
                    timezone: America/Los_Angeles
                    role_id: 214
                    business_admin_id: 5399
                    read_only: false
                    suspend: false
                    franchisee_id: 12
                    locations:
                    - location_id: 310969
                      store_number: ' 68'
                    - location_id: 310971
                      store_number: ' 70'
                    location_groups:
                    - location_group_id: 1619
                      name: Location Group 1
                    - location_group_id: 2086
                      name: Location Group 2
        '401':
          $ref: '#/components/responses/401-unauthorized'
      summary: Create Business Admin
      description: Creates a business admin in the Punchh platform
      operationId: dashboard_create_business_admin
      tags:
      - Business Admin Users
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/content-type'
      x-stoplight:
        id: 3f287a66ea2d0
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                business_admin:
                  type: object
                  properties:
                    email:
                      type: string
                      description: Email address of the business admin
                    first_name:
                      type: string
                      description: 'First name of the business admin

                        '
                    last_name:
                      type: string
                      description: 'Last name of business admin

                        '
                    timezone:
                      type: string
                      description: "Time zone displayed (e.g., \"America/Los_Angeles\") when the business admin views data in the Punchh platform \n"
                    location_ids:
                      type: array
                      description: 'Location IDs to which the business admin will be granted access. Preference is given to `store_numbers` if both `location_ids` and `store_numbers` are provided.

                        '
                      items:
                        type: integer
                    store_numbers:
                      type: array
                      description: 'Store numbers of the locations to which the business admin will be granted access. Preference is given to `store_numbers` if both `location_ids` and `store_numbers` are provided.

                        '
                      items:
                        type: integer
                    role_id:
                      type: integer
                      description: Fetch from the response of the [Get Admin Roles List](/docs/dev-portal-platform-functions/b3A6NTAyODA0Nzc-get-admin-roles-list) API
                    location_group_ids:
                      type: array
                      description: 'Location group IDs to which the business admin will be granted access

                        '
                      items:
                        type: integer
                    read_only:
                      type: boolean
                      description: 'Makes the business admin read-only

                        '
                    suspend:
                      type: boolean
                      description: 'Suspends the business admin

                        '
                    franchisee_id:
                      type: integer
                      description: 'Unique franchisee ID associated with the business admin (enabled for the franchisee model only)

                        '
                    skip_notifications:
                      type: boolean
                      description: Send this parameter with a value of "true" if you want to skip any notifications to be sent to the business admin for this event
            examples:
              business_admin:
                value:
                  email: test@example.com
                  first_name: FIRST_NAME_GOES_HERE
                  last_name: LAST_NAME_GOES_HERE
                  timezone: America/Los_Angeles
                  location_ids:
                  - 310969
                  - 310971
                  store_numbers:
                  - 68
                  - 70
                  role_id: 214
                  location_group_ids:
                  - 2086
                  - 1619
                  read_only: false
                  suspend: false
                  franchisee_id: 12
    patch:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    description: Email address of the business admin
                  first_name:
                    type: string
                    description: First name of the business admin
                  last_name:
                    type: string
                    description: Last name of the business admin
                  timezone:
                    type: string
                    description: Time zone displayed (e.g., "America/Los_Angeles") when the business admin views stats and events in the Punchh platform
                  role_id:
                    type: integer
                    description: Unique ID of the role assigned to the business admin. This ID is generated by Punchh.
                  business_admin_id:
                    type: integer
                    description: Unique ID assigned to the business admin
                  read_only:
                    type: boolean
                    description: Whether the business admin is read-only or not
                  suspend:
                    type: boolean
                    description: Whether the business admin has been suspended or not
                  franchisee_id:
                    type: integer
                    description: Unique franchisee ID associated with the business admin (enabled for the franchisee model only)
                  locations:
                    type: array
                    description: Locations that the business admin can access in the Punchh platform
                    items:
                      type: object
                      properties:
                        location_id:
                          type: integer
                          description: ID of the location that the business admin can access
                        store_number:
                          type: string
                          description: Store number of the location that the business admin can access
                  location_groups:
                    type: array
                    description: Location groups that the business admin can access in the Punchh platform
                    items:
                      type: object
                      properties:
                        location_group_id:
                          type: integer
                          description: ID of the location group that the business admin can access
                        name:
                          type: string
                          description: Name of the location group that the business admin can access
              examples:
                default:
                  value:
                    email: test@example.com
                    first_name: FIRST_NAME_GOES_HERE
                    last_name: LAST_NAME_GOES_HERE
                    timezone: America/Los_Angeles
                    role_id: 11
                    business_admin_id: 30803
                    read_only: false
                    suspend: false
                    franchisee_id: 12
                    locations:
                    - location_id: 9
                      store_number: '21'
                    - location_id: 10
                      store_number: '10'
                    location_groups:
                    - location_group_id: 1
                      name: New Business Location group
        '401':
          $ref: '#/components/responses/401-unauthorized'
      summary: Update Business Admin
      operationId: dashboard_update_business_admin
      tags:
      - Business Admin Users
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/content-type'
      x-stoplight:
        id: e3392b2acaf40
      description: Updates a business admin in the Punchh platform
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                business_admin_id:
                  type: string
                  description: ID of the business admin to be updated
                business_admin:
                  type: object
                  properties:
                    email:
                      type: string
                      description: Email address of the business admin
                    first_name:
                      type: string
                      description: First name of the business admin
                    last_name:
                      type: string
                      description: Last name of the business admin
                    timezone:
                      type: string
                      description: Time zone displayed (e.g., "America/Los_Angeles") when the business admin views data in the Punchh platform
                    role_id:
                      type: integer
                      description: Unique ID of the role assigned to the business admin. This ID is generated by Punchh.
                    location_ids:
                      type: array
                      description: Location IDs to which the business admin will be granted access. Preference is given to `store_numbers` if both `location_ids` and `store_numbers` are provided.
                      items:
                        type: integer
                    store_numbers:
                      type: array
                      description: Store numbers of the locations to which the business admin will be granted access. Preference is given to `store_numbers` if both `location_ids` and `store_numbers` are provided.
                      items:
                        type: string
                    location_group_ids:
                      type: array
                      description: Location group IDs to which the business admin will be granted access
                      items:
                        type: string
                    read_only:
                      type: boolean
                      description: Makes the business admin read-only
                    suspend:
                      type: boolean
                      description: Suspends the business admin
                    franchisee_id:
                      type: integer
                      description: Unique franchisee ID associated with the business admin (enabled for the franchisee model only)
            examples:
              default:
                value:
                  business_admin_id: '30803'
                  business_admin:
                    email: test@example.com
                    first_name: FIRST_NAME_GOES_HERE
                    last_name: LAST_NAME_GOES_HERE
                    timezone: America/Los_Angeles
                    role_id: 11
                    location_ids:
                    - 9
                    - 10
                    store_numbers:
                    - '21'
                    - '10'
                    location_group_ids:
                    - '1'
                    read_only: false
                    suspend: false
                    franchisee_id: 12
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    description: Email address of the business admin
                  first_name:
                    type: string
                    description: First name of the business admin
                  last_name:
                    type: string
                    description: Last name of the business admin
                  timezone:
                    type: string
                    description: Time zone displayed (e.g., "America/Los_Angeles") when the business admin views stats and events in the Punchh platform
                  role_id:
                    type: integer
                    description: Unique ID of the role assigned to the business admin. This ID is generated by Punchh.
                  business_admin_id:
                    type: integer
                    description: Unique ID assigned to the business admin
                  franchisee_id:
                    type: integer
                    description: Unique franchisee ID associated with the business admin (enabled for the franchisee model only)
                  locations:
                    type: array
                    description: Locations that the business admin can access in the Punchh platform
                    items:
                      type: object
                      properties:
                        location_id:
                          type: integer
                          description: ID of the location that the business admin can access
                        store_number:
                          type: string
                          description: Store number of the location that the business admin can access
                  location_groups:
                    type: array
                    description: Location groups that the business admin can access in the Punchh platform
                    items:
                      type: object
                      properties:
                        location_group_id:
                          type: integer
                          description: ID of the location group that the business admin can access
                        name:
                          type: string
                          description: Name of the location group that the business admin can access
              examples:
                default:
                  value:
                    email: test@example.com
                    first_name: FIRST_NAME_GOES_HERE
                    last_name: LAST_NAME_GOES_HERE
                    timezone: America/Los_Angeles
                    role_id: 11
                    business_admin_id: 30803
                    franchisee_id: 12
                    locations:
                    - location_id: 9
                      store_number: '21'
                    - location_id: 10
                      store_number: '10'
                    location_groups:
                    - location_group_id: 1
                      name: New Business Location group
        '401':
          $ref: '#/components/responses/401-unauthorized'
      summary: Show Business Admin
      operationId: dashboard_show_business_admin
      tags:
      - Business Admin Users
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/content-type'
      x-stoplight:
        id: 84d3dba781bcd
      description: Gets the details of a business admin in the Punchh platform
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                business_admin_id:
                  type: string
                  description: ID of the business admin whose details you want to fetch
            examples:
              default:
                value:
                  business_admin_id: '30803'
    delete:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '401':
          $ref: '#/components/responses/401-unauthorized'
      summary: Delete Business Admin
      operationId: dashboard_delete_business_admin
      tags:
      - Business Admin Users
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/content-type'
      x-stoplight:
        id: d0849f41e3c4c
      description: Deletes a business admin from the Punchh platform
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                business_admin_id:
                  type: string
                  description: ID of the business admin to be deleted
            examples:
              default:
                value:
                  business_admin_id: '30803'
  /api2/dashboard/business_admins/invite:
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    description: Email address of the business admin
                  first_name:
                    type: string
                    description: First name of the business admin
                  last_name:
                    type: string
                    description: Last name of the business admin
                  timezone:
                    type: string
                    description: Time zone displayed (e.g., "America/Los_Angeles") when the business admin views stats and events in the Punchh platform
                  role_id:
                    type: integer
                    description: Unique ID of the role assigned to the business admin. This ID is generated by Punchh.
                  business_admin_id:
                    type: integer
                    description: Unique ID assigned to the business admin
                  read_only:
                    type: boolean
                    description: Whether the business admin is read-only or not
                  suspend:
                    type: boolean
                    description: Whether the business admin has been suspended or not
                  franchisee_id:
                    type: integer
                    description: Unique franchisee ID associated with the business admin (enabled for the franchisee model only)
                  wants_notify_for_campaign_approval_email:
                    type: boolean
                    description: Allows the business admin to receive notifications for campaign approval emails. The business admin must have Workflow Management permission. Otherwise, the business admin will be notified but will not have access to campaigns that are pending approval.
                  locations:
                    type: array
                    description: Locations that the business admin can access in the Punchh platform
                    items:
                      type: object
                      properties:
                        location_id:
                          type: integer
                          description: ID of the location that the business admin can access
                        store_number:
                          type: string
                          description: Store number of the location that the business admin can access
                  location_groups:
                    type: array
                    description: Location groups that the business admin can access in the Punchh platform
                    items:
                      type: object
                      properties:
                        location_group_id:
                          type: integer
                          description: ID of the location group that the business admin can access
                        name:
                          type: string
                          description: Name of the location group that the business admin can access
              examples:
                default:
                  value:
                    email: test@example.com
                    first_name: FIRST_NAME_GOES_HERE
                    last_name: LAST_NAME_GOES_HERE
                    timezone: America/Los_Angeles
                    role_id: 214
                    business_admin_id: 5399
                    read_only: false
                    suspend: false
                    franchisee_id: 11
                    wants_notify_for_campaign_approval_email: true
                    locations:
                    - location_id: 310969
                      store_number: ' 68'
                    - location_id: 310971
                      store_number: ' 70'
                    location_groups:
                    - location_group_id: 1619
                      name: Location Group 1
                    - location_group_id: 2086
                      name: Location Group 2
        '401':
          $ref: '#/components/responses/401-unauthorized'
      summary: Invite Business Admin
      description: Invites a business admin to use the Punchh platform
      operationId: dashboard_invite_business_admin
      tags:
      - Business Admin Users
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/content-type'
      x-stoplight:
        id: af32eb740fd58
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                business_admin:
                  type: object
                  properties:
                    email:
                      type: string
                      description: Email address of the business admin
                    first_name:
                      type: string
                      description: First name of the business admin
                    last_name:
                      type: string
                      description: Last name of the business admin
                    timezone:
                      type: string
                      description: Time zone displayed (e.g., "America/Los_Angeles") when the business admin views data in the Punchh platform
                    location_ids:
                      type: array
                      description: Location IDs to which the business admin will be granted access. Preference is given to `store_numbers` if both `location_ids` and `store_numbers` are provided.
                      items:
                        type: integer
                    store_numbers:
                      type: array
                      description: Store numbers of the locations to which the business admin will be granted access. Preference is given to `store_numbers` if both `location_ids` and `store_numbers` are provided.
                      items:
                        type: integer
                    role_id:
                      type: integer
                      description: Unique ID of the role assigned to the business admin. This ID is generated by Punchh.
                    location_group_ids:
                      type: array
                      description: Location group IDs to which the business admin will be granted access
                      items:
                        type: integer
                    read_only:
                      type: boolean
                      description: Makes the business admin read-only
                    suspend:
                      type: boolean
                      description: Suspends the business admin
                    franchisee_id:
                      type: integer
                      description: Unique franchisee ID associated with the business admin (enabled for the franchisee model only)
                    wants_notify_for_campaign_approval_email:
                      type: boolean
                      description: Allows the business admin to receive notifications for campaign approval emails. The business admin must have Workflow Management permission. Otherwise, the business admin will be notified but will not have access to campaigns that are pending approval.
            examples:
              business_admin:
                value:
                  email: test@example.com
                  first_name: FIRST_NAME_GOES_HERE
                  last_name: LAST_NAME_GOES_HERE
                  timezone: America/Los_Angeles
                  location_ids:
                  - 310969
                  - 310971
                  store_numbers:
                  - 68
                  - 70
                  role_id: 214
                  location_group_ids:
                  - 2086
                  - 1619
                  read_only: false
                  suspend: false
                  franchisee_id: 11
                  wants_notify_for_campaign_approval_email: true
components:
  parameters:
    accept:
      schema:
        type: string
        default: application/json
      in: header
      name: Accept
      description: Advertises which content types the client is able to understand
      required: true
    authorization-header:
      schema:
        type: string
        default: Bearer BUSINESS_ADMIN_KEY_GOES_HERE
      name: Authorization
      in: header
      description: 'Bearer token for admin authorization, who is making a call on behalf of the customer. Send the API key in the following format: "Authorization: Bearer BUSINESS_ADMIN_KEY_GOES_HERE".'
      required: true
    content-type:
      schema:
        type: string
        default: application/json
      name: Content-Type
      in: header
      description: Set this header to <b>application/json</b>.
      required: true
  responses:
    401-unauthorized:
      description: 'A business admin key is missing or invalid. A request header in the following format is needed to make the request:


        `Authorization: Bearer BUSINESS_ADMIN_KEY_GOES_HERE`'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
          examples:
            default:
              value:
                error: You need to sign in or sign up before continuing.
x-stoplight:
  id: 9820bbd2e8ee1
x-ext-urls: {}