Our API was created so you can integrate your app directly with PerkZilla to help virally grow your userbase and save upwards of thousands of dollars in lead generation as well as costs of customer acquisition.

The API allows you to interconnect the signups from the PerkZilla signup widget to your application in a two directional form of communication, allowing for continuity in user management, and the ability to utilize PerkZilla’s viral sharing aspects anywhere within your app or website.

We’ve have users that use the API to show the number of referrals directly in their app’s settings panel or admin dashboard and AUTOMATICALLY unlock rewards when they hit a referral tier. Referral links can be placed anywhere across the site and quotas or limits can be removed just by referring friends. Perkzilla helps you place your App’s marketing efforts on AUTOPILOT.

Important: API Version Update

We have released a new, enhanced API version (v4). All new integrations should use this endpoint. The original API is now considered Legacy/Deprecated.

New v4 API Endpoint (Recommended)

The new API is available at the following base endpoint, which offers stability, pagination, and clearer data structures:

• Endpoint: POST https://app.perkzilla.com/api/v4/integration

• Key Requirement: Requests to v4 must use the Content-Type: multipart/form-data.

Legacy/Deprecated API Endpoint

Integrations using the original endpoint are deprecated and should be migrated to V4 as soon as possible.

• Legacy Endpoint: POST https://app.perkzilla.com/apiauth.php

To access your API Key:

1. Login to PerkZilla
2. Click on your name in the top right.
3. A drop down will open. Select “Profile Settings“.
4. Click PROFILE in the sub-menu and you’ll be able to show and copy your “API Key”.

Note: The API is action-based. Every request includes your api_key and an action parameter that tells the system what operation to perform.

This section details the structure required for submitting requests to the PerkZilla API.

Deprecated Legacy API Details

This information pertains to the older, deprecated endpoint (/apiauth.php). Please migrate to the V4 API.

New V4 API Standard (Recommended)

All new integrations must use the following endpoint and request structure.

Request Requirements

Every request sent to either endpoint must include the following parameters in the body:

• api_key: Your unique API key.

• action: The specific operation to perform (e.g., get_campaigns, subscribe_user).

This action retrieves the campaigns associated with your authenticated PerkZilla account.

New V4 API Standard (Recommended)

This is the recommended structure and response format for V4 integrations.

cURL Example (V4)

Note the new endpoint and the Content-Type: multipart/form-data assumed by the --form flag.

curl --location 'https://app.perkzilla.com/api/v4/integration' \
--form 'action="get_campaigns"' \
--form 'api_key="YOUR_API_KEY"'

Example Response (V4)

The campaign name field is now simplified to name.

[
 {
  "id": "8636ef0a-89d4-4c2f-9be9-5f1fdfe9a034",
  "name": "Holiday Giveaway"
 },
 {
  "id": "0bbadbb8-8db7-4a54-ad37-e76088d13b20",
  "name": "Product Launch Contest"
 }
]

Status: 200 OK

Deprecated Legacy API Details

This information pertains to the older, deprecated endpoint (/apiauth.php).

In order to get “Campaign ID” you need to use the Legacy Endpoint and POST method in a cURL request.

cURL Example (Legacy)

curl --location 'https://app.perkzilla.com/apiauth.php' \
--data 'api_key=YOUR_API_KEY&action=get_campaigns'

Sample Response (Legacy)

The campaign name field is campaign_name in the legacy response.

[
 {
  "id":"k2zZ9PhIrbm3bumoQfgS8huNzi9azISM93UwQ4SztA8ou25jr5SclqK5boyqomOdZY%2F24W7V0cV3MSbLSPKj%2FgnnePRmHNvrER4TXc9jPlFBoiZjOvsohSEzUufN03hi",
  "campaign_name":"Campaign1"
 },
 {
  "id":"Ex14oNYRdZvjLArIuz4TdVmuR%2BviIaSvB%2BDJw4MSog14kRQbs3OjMufDq3OKyxVt0vyzvWw%2FdCEaFl%2FTYhKF130O3hkDOcRq9xeR%2BdgSFE9b0Pbbm6Dnk6o1l9QZHDJG",
  "campaign_name":"Campaign2"
 }
]

This action retrieves a list of subscribers for a specified campaign.

New V4 API Standard (Recommended)

The V4 API introduces pagination for efficient retrieval of large subscriber lists.

cURL Example (V4)

curl --location 'https://app.perkzilla.com/api/v4/integration' \
--form 'action="get_subscribers"' \
--form 'api_key="YOUR_API_KEY"' \
--form 'campaign_id="c8d12c18-f478-4c0a-9280-3e4a1fbe40f0"' \
--form 'page="1"' \
--form 'limit="25"'

Example Response (V4)

The response is now an object that includes the paginated subscriber data and pagination metadata.

{
  "subscribers": [
    {
      "id": 10294,
      "email": "[email protected]",
      "status": "active",
      "subscribed_at": "2025-12-11T10:00:00Z",
      "referral_count": 5
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 387
  }
}

Status: 200 OK

Deprecated Legacy API Details

This information pertains to the older, deprecated endpoint (/apiauth.php). This version retrieves all subscribers at once and has no pagination.

In order to get “Campaign Subscribers” you need to use the Legacy Endpoint and POST method in a cURL request.

cURL Example (Legacy)

curl --location 'https://app.perkzilla.com/apiauth.php' \
--data 'api_key=YOUR_API_KEY&action=get_subscribers&campaign_id=123'

Sample Response (Legacy)

The response is a flat array of subscriber objects.

[
  {
    "id": "11",
    "name": "John Doe",
    "email": "[email protected]",
    "total_referrals": "0",
    "referral_code": "4d",
    "first_name": "John",
    "last_name": "Doe"
    // ... other fields
  },
  {
    "id": "12",
    "name": "Jack Daniel Doe",
    "email": "[email protected]"
    // ... other fields
  }
]

New V4 API Standard (Recommended)

Important Migration Note: The V4 API only supports retrieving subscriber details using the refID (referral code). Lookup by email has been removed.

cURL Example (V4)

curl --location 'https://app.perkzilla.com/api/v4/integration' \
--form 'action="get_subscriber_details"' \
--form 'api_key="YOUR_API_KEY"' \
--form 'refID="db8"'

Example Response (V4)

The response uses cleaner fields for stats and organizes referral information under a dedicated object.

{
  "id": 10294,
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "ip": "203.0.113.52",
  "referral": {
    "code": "db8",
    "link": "https://mylp.perkzilla.com/p9a?ref=db8",
    "referred_by": "0"
  },
  "stats": {
    "referrals": 12,
    "shares": 18,
    "views": 142,
    "actions": 3,
    "points": 280
  },
  "custom_fields": {}
}

Status: 200 OK

Deprecated Legacy API Details

To get “Campaign Subscriber Details” by refID or email you need to use the Legacy Endpoint and POST method.

Legacy Lookup by refID

cURL Example (Legacy – By refID)

curl --location 'https://app.perkzilla.com/apiauth.php' \
--data 'api_key=YOUR_API_KEY&action=get_subscriber_details&refID=4d'

Legacy Lookup by email (Not supported in V4)

cURL Example (Legacy – By email)

curl --location 'https://app.perkzilla.com/apiauth.php' \
--data 'api_key=YOUR_API_KEY&action=get_subscriber_details&[email protected]'

Sample Response (Legacy)

The response fields are directly nested in the object (e.g., total_referrals, referral_code).

[{ 
  "id": "12", 
  "name": "Jane Doe", 
  // ... custom fields
  "email": "[email protected]", 
  "total_referrals": "0",
  "total_views": "0",
  "referral_code": "4d"
  // ... other fields
}]

This action retrieves all subscribers who were referred by a specific subscriber.

New V4 API Standard (Recommended)

cURL Example (V4)

curl --location 'https://app.perkzilla.com/api/v4/integration' \
--form 'action="get_subscriber_referrals"' \
--form 'api_key="YOUR_API_KEY"' \
--form 'refID="db8"'

Example Response (V4)

[
  {
    "id": 29201,
    "email": "[email protected]",
    "first_name": "Charlie",
    "last_name": "Smith",
    "referral": {
      "code": "e3k",
      "by": "db8"
    },
    "subscribed_at": "2025-10-01T14:22:00Z"
  }
]

Status: 200 OK

Deprecated Legacy API Details

This information pertains to the older, deprecated endpoint (/apiauth.php).

In order to get “Campaign Subscriber Referrals” you need to use the Legacy Endpoint and POST method in a cURL request.

cURL Example (Legacy)

curl --location 'https://app.perkzilla.com/apiauth.php' \
--data 'api_key=YOUR_API_KEY&action=get_subscriber_referrals&refID=4f2'

Sample Response (Legacy)

[
{
"id": "11",
"name": "John Doe",
"custom_1": "Sample Custom Tag",
"custom_2": "Sample Custom Tag",
"custom_3": "Sample Custom Tag",
"email": "[email protected]",
"total_referrals": "0",
"total_shares": "0",
"total_views": "0",
"total_points": "0",
"referred_by": "12",
"user_ip": "115.111.111.222",
"referral_code": "4d",
"referral_link": "https://perk3.com?ref=4d",
"first_name": "John",
"middle_name": "",
"last_name": "Doe"
},
{
"id": "12",
"name": "Jane Daniel Doe",
"custom_1": "Sample Custom Tag",
"custom_2": "Sample Custom Tag",
"custom_3": "Sample Custom Tag",
"email": "[email protected]",
"total_referrals": "0",
"total_shares": "0",
"total_views": "0",
"total_points": "0",
"referred_by": "12",
"user_ip": "115.111.111.333",
"referral_code": "4d",
"referral_link": "https://perk3.com?ref=5d",
"first_name": "Jane",
"middle_name": "Daniel",
"last_name": "Doe"
}
]

This action creates a new subscriber in a campaign.

New V4 API Standard (Recommended)

Important V4 Change: The subscriber parameters no longer use the variables[...] array but instead use the subscriber[...] array with new, consistent field keys (e.g., pkemail).

cURL Example (V4)

curl --location 'https://app.perkzilla.com/api/v4/integration' \
--form 'action="subscribe_user"' \
--form 'api_key="YOUR_API_KEY"' \
--form 'campaign_id="c8d12c18-f478-4c0a-9280-3e4a1fbe40f0"' \
--form 'subscriber[pkemail]="[email protected]"' \
--form 'subscriber[pkfirstname]="Jane"' \
--form 'subscriber[pklastname]="Doe"'

Example Response (V4)

V4 Change: A successful subscription now returns the full subscriber object (Status: 201 Created), not just a success message.

{
  "id": 12944,
  "email": "[email protected]",
  "name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "ip": "203.0.113.52",
  "referral": {
    "code": "ab9x",
    "link": "https://mylp.perkzilla.com/p9a?ref=ab9x",
    "referred_by": null
  },
  "stats": {
    "referrals": 0,
    "shares": 0,
    "views": 0,
    "actions": 0,
    "points": 0
  },
  "custom_fields": {}
}

Status: 201 Created

Deprecated Legacy API Details

This information pertains to the older, deprecated endpoint (/apiauth.php).

In order to Add “New Subscriber to campaign” you need to use the Legacy Endpoint and POST method.

cURL Example (Legacy)

curl --location 'https://app.perkzilla.com/apiauth.php' \
--data 'api_key=YOUR_API_KEY&action=subscribe_user&campaign_id=123&variables[subscriber_name]=John%20Doe&variables[subscriber_email][email protected]'

Sample Response (Legacy)

{
  "message":"User Subscribed Successfully"
}

{
  "message":"Subscriber Email Already Exist"
}

{
  "message":"Invalid campaign"
}

Every API action uses standard HTTP codes:

Error Example (with payload)

{
 "error": "Campaign ID is required"
}

Error Example (null body)

Some security-sensitive failures intentionally return no JSON body. Always check the HTTP status code instead of relying solely on the response body.

Status: 401 Unauthorized Body: null

Rate Limiting

Rate limits depend on your subscription.

Rate Limit Exceeded Response

{
  "error": "Rate limit exceeded",
  "retry_after": 3600,
  "limit": 1000,
  "remaining": 0
}

Status: 429 Too Many Requests

Security Guidelines

• Never expose your API key in client-side code.
• Only call the API from secure server-side applications.
• Always use HTTPS.
• Rotate your API key immediately if exposed.

Migration Highlights: Legacy API to V4

The V4 API introduces several structural improvements. Use this guide to update your integration code quickly and efficiently.

Key Action Required

The most critical change is the Endpoint and the mandatory use of multipart/form-data for all V4 requests. Ensure your HTTP client library is configured correctly.