API Reference

Response Fields

Key Management

To revoke or delete an API key:

• Dashboard: Navigate to Settings → API Keys and click "Revoke" next to the key you want to delete
• API: Use DELETE /v1/api-keys/{id} (requires authentication with a different key)

Revoked keys immediately stop working. Any requests using a revoked key will return 401 Unauthorized.

Usage Notes

Consider creating multiple API keys for:

• Environment separation: Different keys for development, staging, and production
• Service isolation: Separate keys for different services or microservices
• Access control: Keys with different permission levels or scopes
• Key rotation: Maintain multiple keys to enable zero-downtime rotation

Response Structure

The response includes pagination metadata:

Pagination

To paginate through results, use the offset parameter:

Response Fields

The response includes the complete pass object with the following fields:

Error Scenarios

Validation Example

Use Cases

• Verify pass details before updating
• Retrieve wallet URLs to display to users
• Check pass status before sending notifications
• Display pass information in your application

Error Responses

Partial Update Behavior

Only send the fields you want to update. Fields not included in the request remain unchanged. For example, to update only points:

Field Mutability

The following fields cannot be updated:

• id - Immutable identifier
• member_name - Cannot be changed after creation
• brand_id - Cannot be changed after creation
• created_at - System-managed timestamp

Validation

The same validation rules apply as in Create Pass. Invalid values will return 400 Bad Request.

Soft Delete Explained

When you delete a pass, it's marked as deleted (soft delete) rather than permanently removed:

• The pass is removed from active listings and cannot be retrieved via Get Pass
• The pass becomes unusable in the user's wallet
• Historical data is retained for analytics and audit purposes
• The pass ID cannot be reused

Irreversibility

Deleted passes cannot be restored through the API. If you need to restore a pass, you'll need to:

• Create a new pass with the same member information
• Contact support if you need to recover historical data

Cascading Effects

Deleting a pass has the following effects:

• Scheduled notifications: All pending/scheduled notifications for this pass are cancelled
• Active notifications: Already sent notifications remain in the system but cannot be resent
• Location triggers: The pass will no longer trigger location-based notifications

Response

On successful deletion, the API returns 204 No Content with an empty response body. If the pass doesn't exist, you'll receive 404 Not Found.

Notification Status Values

Notifications progress through the following statuses:

Delivery Guarantees

Notification delivery operates on a best-effort basis:

• Notifications are queued and sent as quickly as possible (typically within seconds)
• Delivery depends on device connectivity and push notification service availability
• Users may have notifications disabled or the app uninstalled
• Failed notifications are not automatically retried (use the API to resend if needed)
• Delivery status updates may take a few minutes to reflect accurately

Notification Limits

• Rate limit: 100 notifications per minute per API key
• Title length: Maximum 100 characters
• Body length: Maximum 500 characters
• Scheduled notifications: Can be scheduled up to 30 days in advance

Error Handling

Notification Statistics Response

The stats endpoint returns detailed delivery metrics:

How Geofencing Works

When a pass holder's device enters the geofence (circular area defined by latitude, longitude, and radius):

• The device detects proximity using GPS and location services
• A notification is automatically sent to the pass holder
• The notification uses the location's default message (if provided) or a custom message
• Notifications are sent once per entry (re-entry after leaving triggers again)

GPS Accuracy Considerations

GPS accuracy varies based on several factors:

• Outdoor accuracy: Typically 5-10 meters under clear sky conditions
• Indoor accuracy: Can be 20-50 meters or worse, depending on building materials
• Urban canyons: Tall buildings can reduce accuracy to 15-30 meters
• Device quality: Newer devices generally have better GPS chips

Recommendation: Use a radius of at least 50 meters to account for GPS inaccuracy. For indoor locations, consider 100-200 meters.

Best Practices

• Minimum radius: Use at least 50 meters to account for GPS inaccuracy
• Maximum radius: Keep under 500 meters for most use cases to avoid false triggers
• Battery impact: Larger radii and more locations increase battery drain. Balance coverage with efficiency
• Location density: Avoid overlapping geofences with similar radii to prevent duplicate notifications
• Testing: Test geofences in real-world conditions before deploying to production
• User permissions: Ensure users have granted location permissions for their wallet app

Location Object Structure

The Get Location endpoint returns a complete location object:

Update Location Response

The Update Location endpoint (PUT) returns the complete updated location object, similar to the Get Location response. Only include fields you want to update in the request body.

Field Documentation

Status Enum Values

Date Format

All timestamps use ISO-8601 format in UTC timezone:

Format: YYYY-MM-DDTHH:mm:ssZ. The Z indicates UTC timezone.

Field Relationships

• wallet_urls and barcode_url are generated automatically when a pass is created
• status must be active for notifications to be delivered
• points_value and points_label work together to display points on the pass
• brand_id determines which brand's styling and configuration is used