API introduction

Welcome to the 2perks API! Our simple REST API allows you to manage perks and categories for your business programmatically.

Base URL

All API requests should be made to:

https://api.2perks.com/api/v1

Authentication

The API uses API keys for authentication. Generate your API key from your dashboard.

Using your API key

Include your API key in the X-2PERKS-API-KEY header:

curl -H "X-2PERKS-API-KEY: YOUR_API_KEY" \
     https://api.2perks.com/api/v1/categories

Getting your API key

1. Log in to your 2perks dashboard
2. Go to Profile → API Keys
3. Click Create API Key
4. Copy and store your key securely

⚠️ Important: Keep your API key secure and never expose it in client-side code.

Request format

• Use HTTPS for all requests
• Include Content-Type: application/json header for POST/PUT requests
• Send data as JSON in the request body

Response format

All responses are JSON with this structure:

Success response

{
  "success": true,
  "data": [
    {
      "id": "1",
      "name": "Food & Dining",
      "slug": "food_dining"
    }
  ]
}

Error response

{
  "success": false,
  "message": "Access denied. No API key provided. Include your API key in the 'X-2PERKS-API-KEY' header."
}

Available endpoints

Get categories

Get all available perk categories.

GET /v1/categories

Example:

curl -H "X-2PERKS-API-KEY: YOUR_API_KEY" \
     https://api.2perks.com/api/v1/categories

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "SaaS",
      "slug": "saas"
    },
    {
      "id": 2,
      "name": "Fintech",
      "slug": "fintech"
    },
    {
      "id": 3,
      "name": "E-commerce",
      "slug": "e-commerce"
    },
    {
      "id": 4,
      "name": "Marketing & Advertising",
      "slug": "marketing-advertising"
    },
    {
      "id": 5,
      "name": "Developer Tools",
      "slug": "developer-tools"
    }
  ],
  "total": 38
}

Get perks by listing

Get all perks for a specific organization's perk listing.

GET /v1/orgs/{orgId}/listings/{perkListingId}/perks

Path parameters:

• orgId - The organization ID
• perkListingId - The perk listing ID

Example:

curl -H "X-2PERKS-API-KEY: YOUR_API_KEY" \
     https://api.2perks.com/api/v1/orgs/org123/listings/listing456/perks

Response:

{
  "success": true,
  "data": [
    {
      "id": "perk123",
      "title": "15% Off Business Class Flights",
      "description": "Save 15% on Business Class tickets for international flights with Air France",
      "type": "discount",
      "value": "15%",
      "redemptionMethod": "code",
      "code": "BUSINESS15",
      "redemptionInstructions": "Enter code at checkout",
      "tags": ["travel", "business", "international"],
      "ctaButtonLabel": "Book Flight",
      "org": {
        "name": "Air France",
        "logo": "https://api.2perks.com/api/files/logo123",
        "website": "https://airfrance.com",
        "category": "travel-hospitality"
      }
    }
  ]
}

Error codes

Common errors

Missing API key

{
  "success": false,
  "message": "Access denied. No API key provided. Include your API key in the 'X-2PERKS-API-KEY' header."
}

Invalid API key

{
  "success": false,
  "message": "Invalid API key"
}

Resource not found

{
  "success": false,
  "message": "Perk listing not found"
}

Rate limits

The API has rate limits to ensure service quality. When you exceed the limit, you'll get a 429 Too Many Requests response.

Usage tracking

Your API key usage is automatically tracked:

• Usage count: Number of API calls made
• Last used: Timestamp of the most recent API call
• Active status: Whether the key is currently active

You can monitor your usage through the dashboard or by calling the API key management endpoints.

Ready to start? Get your API key and explore your first categories!