Punchh Invitations API

openapi: 3.2.0
info:
  title: Mobile Invitations API
  version: '1.0'
  contact:
    name: Punchh Dev Support
    url: https://developers.punchh.com
  description: Punchh provides a robust platform for offering loyalty programs to customers.
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: Invitations
paths:
  /api2/mobile/invitations:
    get:
      summary: Get Invitations
      description: Returns the list of pending invitations of a user
      operationId: mobile_get_invitations
      tags:
      - Invitations
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/User-Agent'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    invitation_id:
                      type: integer
                      description: Unique ID of the invitation assigned by Punchh
                    invitation_type:
                      type: string
                      description: Type of the invitation for gift card transfer. Invitation types can be "email", "phone", or "claim_token".
                    invitation_date:
                      type: string
                      description: Date/time when the invitation was created
                      enum:
                      - YYYY-MM-DDThh:mm:ssZ
                      format: date-time
                    status:
                      type: string
                      description: Status of the invitation. The status can be "pending" or "cancelled".
                    amount:
                      type: integer
                      description: Amount of the gift card for which the invitation is created
                    gift_card:
                      $ref: '#/components/schemas/Gift-Card-Object'
              examples:
                default:
                  value:
                  - invitation_id: 221
                    invitation_type: claim_token
                    invitation_date: '2017-03-29T23:48:00+05:30'
                    status: pending
                    amount: 25
                    gift_card:
                      card_background_image: IMAGE_URL_GOES_HERE
                      design_id: 4
                      name: My First Card
                      preferred: false
                      usb_scannable_card_number: CARD_NUMBER_GOES_HERE
                      users:
                      - state: owner
                        email: test@example.com
                        first_name: FIRST_NAME_GOES_HERE
                        last_name: LAST_NAME_GOES_HERE
                        avatar_remote_url: null
                        fb_uid: FB_UID_GOES_HERE
                        user_id: 111111111
                      gift_card_id: ID_GOES_HERE
                      card_number: CARD_NUMBER_GOES_HERE
                      created_at: '2016-12-08T20:18:41+05:30'
                      epin: EPIN_GOES_HERE
                      last_fetched_amount: 25
                      last_fetched_at: '2016-12-20T01:00:19+05:30'
                      status: active
                      updated_at: '2016-12-20T01:00:19+05:30'
                      uuid: ID_GOES_HERE
      x-stoplight:
        id: eb521de5ed65f
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  x-stoplight:
                    id: y3t01icl1hr46
                  description: OAuth client ID provided by the business
              required:
              - client
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
        description: ''
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  invitation_id:
                    type: integer
                    description: Unique ID of the invitation assigned by Punchh
                  invitation_type:
                    type: string
                    description: Type of the invitation for gift card transfer. Invitation types can be "email", "phone", or "claim_token".
                  invitation_date:
                    type: string
                    description: Date/time when the invitation was created
                    enum:
                    - YYYY-MM-DDThh:mm:ssZ
                    format: date-time
                  claim_token:
                    type: string
                    description: Claim token for the gift card that has to be transferred. This is generated by Punchh.
                  status:
                    type: string
                    description: Status of the invitation. The status can be "pending" or "cancelled".
                  amount:
                    type: integer
                    description: Amount of the gift card for which the invitation is created
                  gift_card:
                    $ref: '#/components/schemas/Gift-Card-Object'
              examples:
                default:
                  value:
                    invitation_id: 222
                    invitation_type: claim_token
                    invitation_date: '2017-03-30T00:08:49+05:30'
                    claim_token: TOKEN_GOES_HERE
                    status: pending
                    amount: 25
                    gift_card:
                      card_background_image: IMAGE_URL_GOES_HERE
                      design_id: 4
                      name: My first card
                      preferred: false
                      usb_scannable_card_number: CARD_NUMBER_GOES_HERE
                      users:
                      - state: owner
                        email: test@example.com
                        first_name: FIRST_NAME_GOES_HERE
                        last_name: LAST_NAME_GOES_HERE
                        avatar_remote_url: null
                        fb_uid: FB_UID_GOES_HERE
                        user_id: 111111111
                      gift_card_id: ID_GOES_HERE
                      card_number: CARD_NUMBER_GOES_HERE
                      created_at: '2016-12-08T20:18:41+05:30'
                      epin: EPIN_GOES_HERE
                      last_fetched_amount: 25
                      last_fetched_at: '2016-12-20T01:00:19+05:30'
                      status: active
                      updated_at: '2016-12-20T01:00:19+05:30'
                      uuid: ID_GOES_HERE
      summary: Create Gift Card Claim Token
      operationId: Mobile_Create_Gift_Card_Claim_Token
      tags:
      - Invitations
      description: Creates a claim token for a gift card that has to be transferred
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Accept'
      x-stoplight:
        id: 38631116dcddd
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                uuid:
                  type: string
                  description: UUID of the gift card for which the claim token needs to be created
                client:
                  type: string
                  x-stoplight:
                    id: 76dopnrcgo5tt
                  description: OAuth client ID provided by the business
              required:
              - uuid
              - client
            examples:
              default:
                value:
                  uuid: ID_GOES_HERE
                  client: CLIENT_GOES_HERE
        description: ''
  /api2/mobile/invitations/check_status:
    get:
      responses:
        '200':
          description: ''
          content:
            text/plain:
              examples:
                default:
                  value:
                  - This is a valid claim token and can be used in the app to claim the associated Gift Card.
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
              examples:
                default:
                  value:
                    errors:
                    - This is a invalid/cancelled/used claim token
      summary: Check Status of the Claim Token
      description: Returns the status of a claim token to determine if the claim token is valid
      operationId: mobile_Check_Status_of_the_claim_token
      tags:
      - Invitations
      parameters:
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/User-Agent'
      x-stoplight:
        id: d335302f42dc6
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  x-stoplight:
                    id: 5etxbz9m5021r
                  description: OAuth client ID provided by the business
                claim_token:
                  type: string
                  x-stoplight:
                    id: fv8goz65r2zmn
                  description: The claim token generated by the [Create Gift Card Claim Token](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1invitations/post) API
              required:
              - client
              - claim_token
        description: ''
  /api2/mobile/invitations/{id}:
    parameters:
    - schema:
        type: string
      name: id
      in: path
      required: true
    delete:
      responses:
        '200':
          description: ''
          content:
            text/plain:
              examples:
                default:
                  value: "[\n  \"Invitation to use this gift card has been successfully cancelled.\"\n]"
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
              examples:
                default:
                  value:
                    errors:
                    - Invitation to use this gift card can't be cancelled.
      summary: Delete an Invitation Claim Token
      description: Deletes the invitation ID and corresponding claim token to transfer a gift card
      operationId: Mobile_delete_an_invitation_claim_token
      tags:
      - Invitations
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/signature'
      - schema:
          type: string
        in: path
        name: id
        required: true
        description: 'Invitation ID that will be deleted

          '
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      x-stoplight:
        id: eb9967812969f
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  x-stoplight:
                    id: jjh64onw64ath
                  description: OAuth client ID provided by the business
              required:
              - client
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
  /api2/mobile/invitations/transfer:
    patch:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gift-Card-Object'
              examples:
                default:
                  value:
                    card_background_image: IMAGE_URL_GOES_HERE
                    design_id: 4
                    name: null
                    preferred: false
                    usb_scannable_card_number: CARD_NUMBER_GOES_HERE
                    users:
                    - state: owner
                      email: test@example.com
                      first_name: FIRST_NAME_GOES_HERE
                      last_name: LAST_NAME_GOES_HERE
                      avatar_remote_url: null
                      fb_uid: null
                      user_id: 111111111
                    gift_card_id: ID_GOES_HERE
                    card_number: CARD_NUMBER_GOES_HERE
                    created_at: '2016-12-08T20:18:41+05:30'
                    epin: EPIN_GOES_HERE
                    last_fetched_amount: 25
                    last_fetched_at: '2016-12-20T01:00:19+05:30'
                    status: active
                    updated_at: '2016-12-20T01:00:19+05:30'
                    uuid: ID_GOES_HERE
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
              examples:
                default:
                  value:
                    errors:
                    - This gift card can't be transferred, Please contact support
      summary: Transfer a Gift Card Using Invitation Claim Token
      description: Transfers a gift card to a user using the corresponding claim token
      operationId: mobile_transfer_a_gift_card_using_invitation_claim_token
      tags:
      - Invitations
      parameters:
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      x-stoplight:
        id: 8ca4a75f4019b
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  x-stoplight:
                    id: ofimr4m4m3nep
                  description: OAuth client ID provided by the business
                claim_token:
                  type: string
                  x-stoplight:
                    id: hta6rt379xt9m
                  description: The claim token generated by the [Create Gift Card Claim Token](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1invitations/post) API
              required:
              - client
              - claim_token
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
                  claim_token: CLAIM_TOKEN_GOES_HERE
components:
  parameters:
    Authorization:
      schema:
        type: string
        default: Bearer ACCESS_TOKEN_GOES_HERE
      name: Authorization
      in: header
      description: Used to authorize the request with access_token. It should be supplied as `Bearer ACCESS_TOKEN_GOES_HERE`.
      required: true
    Accept:
      schema:
        type: string
        default: application/json
      name: Accept
      in: header
      description: Advertises which content types the client is able to understand
      required: true
    User-Agent:
      schema:
        type: string
        default: AppName/AppVersion/BuildNumber (OS; Model; MANUFACTURER; MODEL; OS Version)
      in: header
      name: User-Agent
      description: Used to identify the software, device, and application initiating the request, providing information about the client to the server. For details, see [User Agent](/docs/dev-portal-mobile/additional-topics/user-agent).
      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
    signature:
      schema:
        type: string
        default: '{{$$.env.signature}}'
      name: x-pch-digest
      in: header
      description: The [signature](/docs/dev-portal-mobile/additional-topics/signature-sha256) for the API call
      required: true
  schemas:
    profile_field_answers:
      title: Profile Field Answers (Object)
      x-stoplight:
        id: lme68mm8va3zz
      type: object
      properties:
        upf0:
          type: string
          description: Each profile field (upf0 - upf24) corresponds to a line from the configuration in the Punchh platform.
        upf1:
          type: string
          description: Each profile field (upf0 - upf24) corresponds to a line from the configuration in the Punchh platform.
        upf2:
          type: string
          description: Each profile field (upf0 - upf24) corresponds to a line from the configuration in the Punchh platform.
      description: Answers given by the user while filling in the user profile. The user submits answers to profile field questions that are configured in the Punchh platform. A total of 25 answers can be submitted. The keys range from 'upf0' to 'upf24'. If questions have multiple answers, the values should be separated by a | character (pipe).
    Gift-Card-Object:
      type: object
      title: Gift Card (Object)
      x-stoplight:
        id: 2eff352e87b8c
      properties:
        card_background_image:
          type: string
          description: URL of the image that is displayed as the gift card background in the app of a business
        card_number:
          type: string
          description: Unique gift card number as issued by the gift card processor (e.g., Aloha, Vantiv, Valutec, etc.) used by the business
        epin:
          type: string
          description: Security PIN associated with a gift card. A "null" value indicates that no epin is associated with the gift card.
        usb_scannable_card_number:
          type: string
          description: Easily scannable form of a gift card's number by adding ~ and ^ as prefix and suffix, respectively, to the gift card number. This is done to avoid issues at certain POS systems while scanning the QR code.
        created_at:
          type: string
          description: Date/time when the gift card was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
          enum:
          - YYYY-MM-DDThh:mm:ssZ
          format: date-time
        design_id:
          type: integer
          description: Identification of a particular gift card design selected by the user while purchasing a gift card
        preferred:
          type: boolean
          description: A "true" value for a gift card indicates that a user has selected it to be the preferred gift card for payment.
        name:
          description: Name of the card that has been assigned by the user. In case of purchase of a gift card from an app, users cannot add a name to the card. A "null" value indicates that a name has not been added to the card. A name can be added later using the [Update Gift Cards](/docs/dev-portal-mobile/5a6da59e09732-update-gift-cards) API.
          x-nullable: true
        last_fetched_amount:
          type: number
          description: The balance amount of a gift card last fetched from the gift card processor
          format: float
        last_fetched_at:
          type: string
          enum:
          - YYYY-MM-DDThh:mm:ssZ
          format: date-time
          description: The last time the balance amount of a gift card was fetched from the gift card processor. This indicates when it was cached.
        status:
          type: string
          description: The status of a gift card. The only value exposed to a gift card in the app is "active". Other statuses are maintained for internal tracking.
        updated_at:
          type: string
          enum:
          - YYYY-MM-DDThh:mm:ssZ
          format: date-time
          description: Date/time when the gift card was updated in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
        users:
          $ref: '#/components/schemas/User-object'
        uuid:
          type: string
          description: Unique ID of the gift card issued by and maintained in the Punchh system
        gift_card_id:
          type: integer
          description: Unique ID assigned to each gift card by the Punchh system. This ID will be passed in the push notification payload to app clients in the key `gc`. By mapping this, the app client can fetch the updated balance of a particular gift card.
        auto_reload_enabled:
          type: boolean
          description: Whether auto-reload is enabled for a gift card or not
        gc_user_auto_reload_threshold_amount:
          type: number
          format: float
          description: Threshold amount below which a gift card becomes eligible for auto-reload
        gc_user_auto_reload_default_amount:
          type: number
          format: float
          description: Default amount with which a gift card would be auto-reloaded
        gc_user_auto_reload_preferred_payment:
          type: string
          x-stoplight:
            id: vi0chaw55927t
          description: UUID of the preferred payment card, which is used for making payments when auto-reloading the gift card
    User-object:
      type: object
      description: Includes details about the users who are registered on a particular business
      x-examples:
        json/application:
          address: ''
          anniversary: '2013-02-16'
          avatar_remote_url: null
          birthday: '1999-01-01'
          city: ''
          communicable_email: test@example.com
          created_at: '2019-01-11T09:08:25Z'
          email: test@example.com
          email_verified: false
          facebook_signup: null
          apple_signup: null
          apple_uid: null
          favourite_location_ids: 306082,333070,304374
          favourite_store_numbers: 12345,0604,1234
          fb_uid: null
          first_name: FIRST_NAME_GOES_HERE
          gender: ''
          has_generated_fb_email: false
          last_name: LAST_NAME_GOES_HERE
          marketing_email_subscription: true
          marketing_pn_subscription: true
          migrate_status: false
          passcode_configured_for_giftcards: false
          phone: '1111111111'
          profile_field_answers:
            test1: Option 1
          referral_code: REFERRAL_CODE_GOES_HERE
          referral_path: URL_GOES_HERE
          secondary_email: ''
          state: ''
          superuser: false
          terms_and_conditions: true
          title: ''
          updated_at: '2020-04-29T04:18:24Z'
          user_as_qrcode: QR_CODE_GOES_HERE
          user_code: P11111111
          user_id: 111111111
          preferred_locale: en
          user_relations: []
          zip_code: null
          verification_mode: null
          sms_subscription: true
          apple_pass_url: APPLE_PASS_URL_GOES_HERE
          google_pass_url: GOOGLE_PASS_URL_GOES_HERE
          user_joined_at: '2019-01-11T09:08:25Z'
      title: User (Object)
      x-stoplight:
        id: 447c4c510a499
      properties:
        address:
          type: string
          description: Address of the user
        avatar_remote_url:
          type: string
          description: URL of the user's profile image uploaded to an online file storage system. This will be used for users who signed up using email.
          x-nullable: true
        birthday:
          type: string
          description: Date of birth of the user, in YYYY-MM-DD format
          enum:
          - YYYY-MM-DD
          format: date-time
        communicable_email:
          type: string
          description: Email address used for communication with the user
        city:
          type: string
          description: City where the user lives
        created_at:
          type: string
          enum:
          - YYYY-MM-DDThh:mm:ssZ
          format: date-time
          description: Date/time when the user was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
        email:
          type: string
          description: Unique email address used to identify the user
        email_verified:
          type: boolean
          description: Whether the email address of the user has been verified or not
        facebook_signup:
          type: boolean
          description: Indicates whether the user signed up using Facebook. This parameter returns true the first time a user signs up in the mobile app using Facebook. For all subsequent logins, it returns a null value.
        favourite_locations:
          type: string
          description: List of the user's favorite locations
        favourite_store_numbers:
          type: string
          description: List of store numbers of the user's favorite locations
        fb_uid:
          type: string
          description: Facebook ID that identifies the user
          x-nullable: true
        first_name:
          type: string
          description: First name of the user
        gender:
          type: string
          description: Gender of the user
        last_name:
          type: string
          description: Last name of the user
        marketing_email_subscription:
          type: boolean
          description: Whether the user has subscribed to receive marketing emails or not
        marketing_pn_subscription:
          type: boolean
          description: Whether the user has subscribed to marketing push notifications or not
        migrate_status:
          type: boolean
          description: Whether the user has a migrate status or not
        passcode_configured_for_giftcards:
          type: boolean
          description: Whether the user has configured a passcode for gift cards or not
        phone:
          type: string
          description: Phone number of the user
        profile_field_answers:
          $ref: '#/components/schemas/profile_field_answers'
        referral_code:
          type: string
          description: Referral code of the user. A user can refer others to join the business loyalty program by sharing this referral code. When a referred user signs up and enters the shared referral code in the mobile app, this `referral_code` must be passed in the `invite_code` request parameter when calling the Sign up / Register API.
        referral_path:
          type: string
          description: Referral URL of the user
        secondary_email:
          type: string
          description: The secondary email address of the user is configured when a user signs up with Facebook/Apple but does not share the email address. The app asks for an alternate email address, which is kept as the `secondary_email`.
        state:
          type: string
          description: State where the user lives
        superuser:
          type: boolean
          description: Whether multiple check-ins are allowed for a user. This is used mostly for testing purposes by developers.
        terms_and_conditions:
          type: boolean
          description: Whether the terms and conditions of a business have been accepted by a user or not
        title:
          type: string
          description: Salutation as selected by the user
          x-nullable: true
        updated_at:
          type: string
          description: Date/time when the user was updated in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
          enum:
          - YYYY-MM-DDThh:mm:ssZ
          format: date-time
        user_as_barcode:
          type: string
          description: Barcode that identifies the user
        user_as_qrcode:
          type: string
          description: QR code that identifies the user
        user_code:
          type: string
          description: A unique ID that identifies the user. This smaller code can be converted to a QR code in the app and scanned at some POS systems that do not support longer codes. Alternatively, a user could give this to the POS operator if the POS does not have a scanner.
        user_id:
          type: integer
          description: ID that identifies the user
        user_relations:
          type: array
          description: Relatives of the user. Valid values are "kid" and "spouse".
          items:
            type: string
            enum:
            - kid
            - spouse
        zip_code:
          type: string
          description: Zip code where the user lives
        anniversary:
          type: string
          description: Anniversary date of the user, in YYYY-MM-DD format
        verification_mode:
          description: Mode of verification (available only for a user in awaiting migration state)
          x-nullable: true
        apple_signup:
          type: boolean
          description: Whether the user has an Apple sign-up or not. This will return true for the first time sign-up.
        apple_uid:
          type: string
          description: Unique ID generated by Apple
        has_generated_fb_email:
          type: boolean
          description: Whether the user has generated a Facebook email or not
        sms_subscription:
          type: boolean
          description: Whether the user has subscribed to SMS services or not
        apple_pass_url:
          type: string
          format: uri
          description: URL that a user can use to download the user's associated loyalty Apple pass
        google_pass_url:
          type: string
          format: uri
          description: URL that a user can use to download the user's associated loyalty Google pass
        age_verified_status:
          type: boolean
          x-stoplight:
            id: ougfjyb55y0rf
          description: 'Whether or not the user has undergone age verification by Koupon Media. Possible Values: true, false. The value is set to true if the user''s age is verified by Koupon Media; otherwise, it is set to false. The response returns this parameter in sign-in, sign-up, and user update APIs if Koupon Media is selected as the age verification adapter for the business in the Punchh platform. Contact your Punchh representative to update this configuration.'
        account_created_at:
          type: string
          x-stoplight:
            id: o07dhmip4epo0
          format: date-time
          description: 'This value is set when a guest account is created on the Punchh Platform and varies depending on business configurations. For example:

            * If an eClub account is created with a historical registration date, that specific date is returned in this parameter.

            * If guest data is migrated from a previous platform and includes a registration date, the system creates the guest account with this registration date from the prior system, and the API returns that date in this parameter.'
        user_joined_at:
          type: string
          x-stoplight:
            id: kbj7omjru7mry
          format: date-time
          description: Date and time when the user became a loyalty member
x-stoplight:
  id: bf6eddb435209
x-ext-urls: {}