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. When a business integrates its back-end with the Punchh server, the Punchh APIs become instrumental in executing loyalty programs for enrolled customers, primarily via business-branded mobile apps and websites tailored by Punchh.


    To establish integration with the Punchh APIs, you need to understand how they are invoked and what responses are returned by the Punchh server. You can call APIs using any suitable API test client, such as Postman. Thus, the response to every API call made in Postman under a chosen environment (in app and/or platform) is reflected in the app and/or platform.'
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:
    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
    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
    Accept:
      schema:
        type: string
        default: application/json
      name: Accept
      in: header
      description: Advertises which content types the client is able to understand
      required: true
    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
  schemas:
    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
    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
x-stoplight:
  id: bf6eddb435209
x-ext-urls: {}