# API keys
Source: https://docs.unblockedbrands.com/api-reference/api-keys

Learn how API keys work with the Passport API

API keys allow you to access your Passport account programmatically and integrate wallet passes into your applications.

Each API key inherits the permissions of the user who created it, giving access to all of that user's resources.

## Creating an API key

You can create an API key by following these steps:

<Steps>
  <Step title="Go to settings">
    Go to **Settings** > **API keys**.

    <img alt="Settings page with API tab highlighted" />
  </Step>

  <Step title="Create an API key">
    Click **"Create API key"** and give it a descriptive name.

    <img alt="Create API key form" />
  </Step>

  <Step title="Store your API key">
    Once your API key is created, make sure to copy and store it in a safe place. You won't be able to see it again for security reasons. If it gets lost, you can create a new one.

    <img alt="Generated API key with copy button highlighted" />

    <Warning>
      Your API key grants full access to your Passport account. Keep it secure and never share it publicly.
    </Warning>
  </Step>

  <Step title="Use your API key">
    Now that you have your API key, you can use it to access your account's resources programmatically via any API request using the api-key header.

    ```bash theme={null}
    api-key: ub_live_xxxx
    ```
  </Step>
</Steps>

## Example Usage

Include your API key in the `api-key` header:

```bash theme={null}
curl -X GET 'https://api.ubpass.co/v1/wallet-pass' \
  -H 'api-key: YOUR_API_KEY_HERE'
```

### Example with a Real Request

```bash theme={null}
curl -X GET 'https://api.ubpass.co/v1/wallet-pass' \
  -H 'api-key: ub_live_abc123xyz456...' \
  -H 'Content-Type: application/json'
```

## Authentication Errors

If your API key is missing, invalid, or malformed, you'll receive authentication errors:

<AccordionGroup>
  <Accordion title="Missing API Key (401 Unauthorized)">
    When no API key is provided in the request headers, you'll receive a 401 Unauthorized response indicating that authentication is required.

    ```json theme={null}
    {
      "txId": "req-xxx",
      "timestamp": "2025-01-17T10:30:00Z",
      "errorCode": "UNAUTHORIZED", 
      "errorMessage": "Authentication required"
    }
    ```

    <Note>The exact error message may vary depending on the endpoint.</Note>
  </Accordion>

  <Accordion title="Invalid API Key (403 Forbidden)">
    When an invalid or malformed API key is provided, you'll receive a 403 Forbidden response indicating that access is denied.

    ```json theme={null}
    {
      "txId": "req-xxx",
      "timestamp": "2025-01-17T10:30:00Z",
      "errorCode": "FORBIDDEN",
      "errorMessage": "Access denied"
    }
    ```

    <Note>The exact error message may vary depending on the endpoint.</Note>
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup>
  <Card title="Secure Storage" icon="lock">
    * Use environment variables in production
    * Never commit API keys to version control
    * Use different keys for development and production
    * Rotate keys regularly for security
  </Card>

  <Card title="Rate Limiting" icon="gauge">
    * API requests are rate limited to prevent abuse
    * Include proper error handling for `429` responses
    * Implement exponential backoff for retries
    * Cache responses when possible
  </Card>
</CardGroup>

### Environment Setup Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  // .env file
  PASSPORT_API_KEY=ub_live_your_api_key_here

  // app.js
  const API_KEY = process.env.PASSPORT_API_KEY;

  const response = await fetch('https://api.ubpass.co/v1/wallet-pass', {
    headers: {
      'api-key': API_KEY,
      'Content-Type': 'application/json'
    }
  });
  ```

  ```python Python theme={null}
  # .env file  
  PASSPORT_API_KEY=ub_live_your_api_key_here

  import os
  import requests

  API_KEY = os.getenv('PASSPORT_API_KEY')

  response = requests.get(
      'https://api.ubpass.co/v1/wallet-pass',
      headers={
          'api-key': API_KEY,
          'Content-Type': 'application/json'
      }
  )
  ```
</CodeGroup>

<Note>
  When you remove a user from your organization (or they leave your organization), all API keys associated with that user will stop working as well. Keep this in mind when managing users.
</Note>


# Introduction
Source: https://docs.unblockedbrands.com/api-reference/introduction

Welcome to the Unblocked Brands API Documentation

This API platform enables you to integrate with our two core products: **Pique** for social content syndication and **Passport** for digital wallet pass management.

## What you can do

### With Pique

Pique is our social boosting and content syndication platform that helps brands amplify their reach through creator networks. We offer two distinct services:

**Boosted Post** - Organically boost views for Instagram Reels. Our network drives authentic engagement to amplify your existing content and increase visibility without paid ads.

**Syndicated Content** - We remix and distribute your content to be posted by micro-influencers on TikTok and Instagram. This service transforms your brand content into creator-led posts for authentic reach.

The Pique API allows you to access comprehensive analytics for campaigns you run with us, including engagement metrics, video performance data, and strategic insights.

### With Passport

Passport enables you to create and manage digital passes for Apple Wallet and Google Wallet. The Passport API allows you to:

* **Send push notifications** - Deliver timely updates and offers directly to pass holders
* **Create digital passes** - Design and distribute branded passes to your customers
* **Set up location-based notifications** - Configure geofenced areas to trigger notifications when users are nearby
* **Manage locations** - Add and update physical locations associated with your passes

## Getting started

To get started:

1. **Get your API key** - Create an API key from your Passport dashboard
2. **Make your first request** - Try the endpoints in the interactive playground below
3. **Build your integration** - Check out our guides for creating different pass types

## Base URL

All API requests should be made to:

```
https://api.ubpass.co/v1/
```

## Authentication

All requests require authentication using an API key in the api-key header:

```bash theme={null}
api-key: ub_live_your_api_key_here
```

Learn more about [API keys](/api-reference/api-keys) and how to create them.

## Rate limits

API requests are rate limited to ensure fair usage and system stability. If you exceed the rate limit, you'll receive a `429 Too Many Requests` response.

## Support

Need help? Reach out to our support team or check out our comprehensive documentation for guides and examples.


# Create a wallet pass location
Source: https://docs.unblockedbrands.com/api-reference/passport--locations/create-a-wallet-pass-location

api-reference/openapi.json post /wallet-pass-location
Create a new location for a specific wallet pass.




# Delete a wallet pass location
Source: https://docs.unblockedbrands.com/api-reference/passport--locations/delete-a-wallet-pass-location

api-reference/openapi.json delete /wallet-pass-location/{locationId}
Delete a wallet pass location by ID.




# Get a wallet pass location
Source: https://docs.unblockedbrands.com/api-reference/passport--locations/get-a-wallet-pass-location

api-reference/openapi.json get /wallet-pass-location/{locationId}
Get a wallet pass location by its ID.




# Search and filter Wallet Pass Locations
Source: https://docs.unblockedbrands.com/api-reference/passport--locations/search-and-filter-wallet-pass-locations

api-reference/openapi.json get /wallet-pass-location
Search and retrieve Wallet Pass Locations with optional filtering and pagination.

**Features:**
- Search locations by name using keyword query (case-insensitive)
- Filter by specific location ID or name
- Filter by wallet pass serial numbers
- Pagination support with cursor-based navigation

**Pagination:**
- Use `cursor` parameter for next page navigation
- `limit` controls page size (default: 20, max: 20)
- Response includes `items` array, `cursor`, and `hasMore` fields




# Update a wallet pass location
Source: https://docs.unblockedbrands.com/api-reference/passport--locations/update-a-wallet-pass-location

api-reference/openapi.json put /wallet-pass-location/{locationId}
Update an existing wallet pass location by ID.




# Create a wallet pass
Source: https://docs.unblockedbrands.com/api-reference/passport--passes/create-a-wallet-pass

api-reference/openapi.json post /wallet-pass
Create a new wallet pass for both Apple and Google platforms.




# Create a wallet pass asynchronously
Source: https://docs.unblockedbrands.com/api-reference/passport--passes/create-a-wallet-pass-asynchronously

api-reference/openapi.json post /wallet-pass/async
Create a new wallet pass for both Apple and Google platforms asynchronously.
This operation will queue the pass creation for background processing.




# Get wallet pass
Source: https://docs.unblockedbrands.com/api-reference/passport--passes/get-wallet-pass

api-reference/openapi.json get /wallet-pass/{id}
Get Wallet pass by id.




# Search and filter Wallet Passes
Source: https://docs.unblockedbrands.com/api-reference/passport--passes/search-and-filter-wallet-passes

api-reference/openapi.json get /wallet-pass
Search and retrieve Wallet Passes with optional filtering and pagination.

**Features:**
- Search passes by name using keyword query (case-insensitive)
- Filter by pass status (Draft, Published)
- Filter by specific pass ID or pass name
- Pagination support with cursor-based navigation
- Option to include pass assets (images) in response
- Option to return summary-only information

**Pagination:**
- Use `cursor` parameter for next page navigation
- `limit` controls page size (default: 20, max: 20)
- Response includes `items` array, `cursor`, and `hasMore` fields




# Update Wallet Pass
Source: https://docs.unblockedbrands.com/api-reference/passport--passes/update-wallet-pass

api-reference/openapi.json patch /wallet-pass/{id}
Update an existing wallet pass by ID. This will update both Apple and Google wallet passes.




# Create a notification for a wallet pass
Source: https://docs.unblockedbrands.com/api-reference/passport--push-notifications/create-a-notification-for-a-wallet-pass

api-reference/openapi.json post /wallet-pass/notifications
Create a notification for a wallet pass. The notification can be sent immediately or scheduled for a later time.

**Notification Status Options:**
- `Draft`: Notification created but not yet ready for delivery
- `Processing`: Notification will be sent immediately upon creation
- `Scheduled`: Notification will be sent at the specified scheduled time

**Scheduling:**
- For immediate delivery, use `Processing` status
- For scheduled delivery, use `Scheduled` status with a `scheduledTime`
- Scheduled notifications are processed every 15 minutes, so delivery may occur within 15 minutes of the scheduled time




# Delete wallet pass notification
Source: https://docs.unblockedbrands.com/api-reference/passport--push-notifications/delete-wallet-pass-notification

api-reference/openapi.json delete /wallet-pass/notifications/{id}
Delete wallet pass notification by ID. Only Draft or Scheduled notifications can be deleted.

**Deletion Rules:**
- `Draft` notifications can always be deleted
- `Scheduled` notifications can be deleted before they are processed
- `Processing`, `Published`, or `Failed` notifications cannot be deleted




# Get notification statistics
Source: https://docs.unblockedbrands.com/api-reference/passport--push-notifications/get-notification-statistics

api-reference/openapi.json get /wallet-pass/notifications/{id}/stats
Retrieve detailed statistics for a specific wallet pass notification including delivery metrics,
click tracking, and engagement data.

**Statistics Include:**
- Delivery status and timestamps
- Click-through rates for notification links
- User engagement metrics
- Error tracking and failure reasons

**Pagination:**
- Use `cursor` parameter for next page navigation
- `limit` controls page size (default: 20, max: 20)




# Get wallet pass notification by ID
Source: https://docs.unblockedbrands.com/api-reference/passport--push-notifications/get-wallet-pass-notification-by-id

api-reference/openapi.json get /wallet-pass/notifications/{id}
Retrieve a specific wallet pass notification by its unique identifier.
Optionally include notification statistics and click tracking data.




# Search and filter wallet pass notifications
Source: https://docs.unblockedbrands.com/api-reference/passport--push-notifications/search-and-filter-wallet-pass-notifications

api-reference/openapi.json get /wallet-pass/notifications
Search and retrieve wallet pass notifications with optional filtering and pagination.

**Features:**
- Search notifications by name using keyword query (case-insensitive)
- Filter by notification status (Draft, Scheduled, Processing, Published, Failed)
- Filter by specific wallet pass serial numbers
- Pagination support with cursor-based navigation
- Option to include pass template data in response
- Option to include link click statistics

**Pagination:**
- Use `cursor` parameter for next page navigation
- `limit` controls page size (default: 20, max: 20)
- Response includes `items` array, `cursor`, and `hasMore` fields

**Status Values:**
- `Draft`: Notification created but not yet ready for delivery
- `Scheduled`: Notification scheduled for future delivery (processed every 15 minutes)
- `Processing`: Notification currently being sent or sent immediately upon creation
- `Published`: Notification successfully delivered to all recipients
- `Failed`: Notification delivery failed due to errors




# Update wallet pass notification
Source: https://docs.unblockedbrands.com/api-reference/passport--push-notifications/update-wallet-pass-notification

api-reference/openapi.json patch /wallet-pass/notifications/{id}
Update wallet pass notification. Only Draft or Scheduled notifications can be updated.

**Status Changes:**
- Change from `Draft` to `Processing` for immediate delivery
- Change from `Draft` to `Scheduled` for future delivery
- Update `Scheduled` notifications to change delivery time or content

**Scheduling Notes:**
- Scheduled notifications are processed every 15 minutes
- Delivery may occur within 15 minutes of the scheduled time
- Once a notification is `Processing` or `Published`, it cannot be updated




# Create Pique Campaign
Source: https://docs.unblockedbrands.com/api-reference/pique/create-pique-campaign

api-reference/openapi.json post /pique-campaign
Create a new Pique Campaign with the provided details.




# Get Pique Campaign by ID
Source: https://docs.unblockedbrands.com/api-reference/pique/get-pique-campaign-by-id

api-reference/openapi.json get /pique-campaign/{id}
Retrieve a specific Pique Campaign by its unique identifier.




# Get Pique Campaign video performance data
Source: https://docs.unblockedbrands.com/api-reference/pique/get-pique-campaign-video-performance-data

api-reference/openapi.json get /pique-campaign/{id}/video-performance
Retrieve video performance metrics for a specific Pique Campaign.




# Search and filter Pique Campaigns
Source: https://docs.unblockedbrands.com/api-reference/pique/search-and-filter-pique-campaigns

api-reference/openapi.json get /pique-campaign
Search and retrieve Pique Campaigns with optional filtering and pagination.

**Features:**
- Search campaigns by name using keyword query
- Filter by campaign status (Prepping, InProgress, Completed, Paused, NotStarted, Cancelled)
- Filter by campaign type (BoostedPost, SyndicatedContent)
- Pagination support with cursor-based navigation
- Returns only published campaigns for branded users

**Pagination:**
- Use `cursor` parameter for next page navigation
- `limit` controls page size (default: 20)
- Response includes `items` array, `cursor`, and `hasMore` fields




# Update Pique Campaign
Source: https://docs.unblockedbrands.com/api-reference/pique/update-pique-campaign

api-reference/openapi.json patch /pique-campaign/{id}
Update an existing Pique Campaign with the provided details.




# Finalize the S3 copy operation
Source: https://docs.unblockedbrands.com/api-reference/upload-apis/finalize-the-s3-copy-operation

api-reference/openapi.json post /uploads/finalize/s3-copy
Finalize the S3 copy operation using the key and extension of the object



# Get a pre-signed URL to upload a file to S3
Source: https://docs.unblockedbrands.com/api-reference/upload-apis/get-a-pre-signed-url-to-upload-a-file-to-s3

api-reference/openapi.json get /uploads/s3-url
Get a pre-signed URL to upload a file to S3



# Upload a file to S3
Source: https://docs.unblockedbrands.com/api-reference/upload-apis/upload-a-file-to-s3

api-reference/openapi.json post /uploads/s3
Upload a file to S3 by providing the file data as a form-data parameter and the bucket name



# Upload a file to the server
Source: https://docs.unblockedbrands.com/api-reference/upload-apis/upload-a-file-to-the-server

api-reference/openapi.json post /uploads
Upload a file to the server by providing the file data as a form-data parameter