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 application/json. 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: {}