Create Business Migration User

Creates a business migration user in the system, including all relevant details such as personal information, loyalty program data, and migration-specific attributes.

When Does Data Move into the Migration Record?

At Ingestion Time (Preloading):

When you invoke POST /api2/dashboard/migration_users or bulk upload, the user data immediately moves into Punchh as a migration record in the "Awaiting Migration" state.
At this stage, no active loyalty account exists yet.

At Sign-up / Activation Time (Conversion):

When the guest signs up (e.g., via POST /api2/mobile/users or web iframe), Punchh matches their look-up identifier (email, phone, or card number) against the preloaded migration records.
Punchh creates the active guest profile and merges the preloaded points/rewards.
The migration record's status in the Punchh platform transitions from "Awaiting Migration" to "Migrated" for audit and historical tracking.

Phone Number Behavior During Migration

Automatic Merge vs. Phone Numbers: While parameters like birthday, preferred_location, and initial_points automatically transfer from the awaiting migration record to the guest profile upon sign-up, phone numbers do not automatically transfer on their own.

An awaiting migration record represents a legacy guest who exists in Punchh's database with their historical balance and metadata, but has not yet activated/registered their account on the new Punchh app or web portal.
Sign-up Payload Requirement: To merge a phone number onto a migrated guest's active loyalty profile, the integration must pass a phone number in the sign-up payload (e.g., via (POST /api2/mobile/users) or web iframe sign-up).
User Profile: The Punchh platform migrated guest view (Guests > Migrated) displays original_phone from the migration record, but the guest's actual editable loyalty profile will remain blank if no phone number was submitted during the sign-up call. If phone-based migration look-up is enabled for the business and a guest’s active loyalty profile is not updated with their phone number, several key loyalty features and workflows will fail, including POS and in-store phone look-up, phone-based or OTP login, and SMS marketing and notifications. Contact your Punchh representative to update this Punchh platform configuration.

Headers

Authorization
Type: string
required

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".
Accept
Type: string
required

Advertises which content types the client is able to understand
Content-Type
Type: string
required

Set this header to application/json.

Body

application/json

address_line1
Type: string

Address of the user
birthday
Type: stringFormat: date

Date of birth of the user, in YYYY-MM-DD format
challenge_progress
Type: array of object
Properties: 2
city
Type: string

City where the user lives
email
Type: string

Email address of the user that will be added to the migration data. Migration can be based on this value as well.
fb_uid
Type: string

Facebook ID that identifies the user
first_name
Type: string

First name of the user
gift_cards
Type: array of object
Properties: 3
initial_points
Type: integerFormat: int32

Number of points that will be used to determine a guest’s membership tier during migration. Contact your Punchh representative for more information.
last_name
Type: string

Last name of the user
loyalty_cards
Type:

Details of the loyalty cards migrated for the user

Properties: 3
marketing_email_subscription
Type: boolean

Whether the user has subscribed to receive marketing emails or not

Responses

application/json
application/json

post/api2/dashboard/migration_users

curl https://SERVER_NAME_GOES_HERE.punchh.com/api2/dashboard/migration_users \
  --request POST \
  --header 'Authorization: Bearer BUSINESS_ADMIN_KEY_GOES_HERE' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Incumbent Loyalty Program",
  "birthday": "1999-01-01",
  "phone": "1111111111",
  "email": "test@example.com",
  "original_membership_no": 123456789,
  "registration_date": "2008-10-26T23:59:59-07:00",
  "first_name": "FIRST_NAME_GOES_HERE",
  "last_name": "LAST_NAME_GOES_HERE",
  "original_phone": "1111111111",
  "original_points": 97,
  "fb_uid": "",
  "initial_points": 3,
  "migrated_rewards": 10.9,
  "migrated_rewards_expiration_date": "2020-01-31",
  "marketing_pn_subscription": true,
  "marketing_email_subscription": false,
  "address_line1": "ADDRESS_GOES_HERE",
  "city": "Mountain View",
  "state": "California",
  "zip_code": "94040",
  "preferred_location": "311031",
  "migrated_redeemables": [
    {
      "redeemable_id": 2329,
      "rewards_count": 2
    }
  ],
  "user_relations": [
    {
      "name": "FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE",
      "relation": "spouse",
      "birthday": "1999-01-01"
    },
    {
      "name": "FIRST_NAME_GOES_HERE",
      "relation": "kid",
      "birthday": "1999-01-01"
    }
  ],
  "gift_cards": [
    {
      "card_number": "CARD_NUMBER_GOES_HERE",
      "card_design_id": "2",
      "epin": "EPIN_GOES_HERE"
    },
    {
      "card_number": "CARD_NUMBER_GOES_HERE",
      "card_design_id": "2",
      "epin": "EPIN_GOES_HERE"
    }
  ],
  "challenge_progress": [
    {
      "challenge_campaign_id": 21571,
      "progress_count": 2
    }
  ],
  "rate_of_conversion": 1,
  "loyalty_cards": [
    {
      "card_number": "CARD_NUMBER_GOES_HERE",
      "status": "ACTIVE",
      "card_signup_date": "2021-05-03"
    },
    {
      "card_number": "CARD_NUMBER_GOES_HERE",
      "status": "SUSPENDED",
      "card_signup_date": "2021-03-03"
    }
  ]
}'

Show Schema

{
  "address_line1": "ADDRESS_GOES_HERE",
  "birthday": "1999-01-01",
  "city": "Mountain View",
  "email": "test@example.com",
  "first_name": "FIRST_NAME_GOES_HERE",
  "gifted_value": 97,
  "initial_points": 3,
  "last_name": "LAST_NAME_GOES_HERE",
  "marketing_email_subscription": false,
  "marketing_pn_subscription": true,
  "migrated_redeemables": [
    {
      "redeemable_id": 2329,
      "rewards_count": 2
    }
  ],
  "migrated_rewards": 10.9,
  "migrated_rewards_expiration_date": "2020-01-31",
  "name": "Incumbent Loyalty Program",
  "original_membership_no": 123456789,
  "original_phone": "1111111111",
  "original_points": 97,
  "phone": "1111111111",
  "preferred_location": 311031,
  "registration_date": "2008-10-26T23:59:59-07:00",
  "state": "California",
  "street_address": "ADDRESS_GOES_HERE",
  "user_relations": [
    {
      "name": "FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE",
      "relation": "spouse",
      "birthday": "1999-01-01"
    },
    {
      "name": "FIRST_NAME_GOES_HERE",
      "relation": "kid",
      "birthday": "1999-01-01"
    }
  ],
  "zip_code": "94040",
  "gift_cards": [
    {
      "card_number": "CARD_NUMBER_GOES_HERE",
      "card_design_id": "2",
      "epin": "EPIN_GOES_HERE"
    },
    {
      "card_number": "CARD_NUMBER_GOES_HERE",
      "card_design_id": "2",
      "epin": "EPIN_GOES_HERE"
    }
  ],
  "challenge_progress": [
    {
      "challenge_campaign_id": 21571,
      "progress_count": 2
    }
  ],
  "loyalty_cards": [
    {
      "card_number": "CARD_NUMBER_GOES_HERE",
      "status": "ACTIVE",
      "card_signup_date": "2021-05-03"
    },
    {
      "card_number": "CARD_NUMBER_GOES_HERE",
      "status": "SUSPENDED",
      "card_signup_date": "2021-03-03"
    }
  ],
  "migration_user_id": 12345678,
  "fb_uid": ""
}

Business Migration Users

Update Business Migration User