Elune Connections
Request your card

Partner API Documentation

Complete reference for integrating Apple Wallet and Google Wallet notifications

Request your card Guides and tutorials
1

1. Authentication

All API requests must include your API Key in the request header.

Include this header in every request to the API.
Headers
X-API-Key: your_api_key_here
Keep your API Key secure. Do not expose it in front-end code or public repositories.

How to get your API Key

Log in to the Elune dashboard and go to Settings → API. There you will find your key and can regenerate it if necessary.

2

2. Company Registration

Register a new company in the system. This is the first step to start using the API.

POST /register

Create a new company account with the provided details.

Field Type Required Description
namestringYesCompany name
emailstringYesContact email
phonestringNoContact phone number
addressstringNoPhysical address
Example Request
{
  "name": "Mi Empresa SL",
  "email": "info@miempresa.com",
  "phone": "+34 600 000 000"
}
Example Response
{
  "id": "emp_a1b2c3d4",
  "api_key": "ek_live_xxxxxxxxxxxxxxxxxxxx",
  "created_at": "2025-01-15T10:30:00Z"
}
Save the returned API key — it is shown only once and cannot be recovered.
3

3. Configuration

Update your company's visual settings and notification defaults.

PUT /company/config

Update company configuration. Partial updates are supported — send only the fields you want to change.

Field Type Required Description
colorstringNoBrand primary colour (hex)
textColorstringNoText colour (hex)
notificationTitlestringNoDefault notification title
pointsNamestringNoCustom name for your points (e.g. Stars, Credits)
rewardsEnabledbooleanNoEnable / disable the rewards catalogue
Brand colours are applied to all cards issued by your company unless overridden at the card model level.
4

4. Card Models (Referencias)

Card models define the visual template for a set of issued cards. You can have multiple models, each with its own design.

POST /refs

Create a new card model with the given configuration.

Field Type Required Description
namestringYesModel display name
descriptionstringNoShort description (shown on the card)
colorstringNoPrimary colour override (hex)
textColorstringNoText colour override (hex)
pointsEnabledbooleanNoEnable loyalty points for this model
rewardsEnabledbooleanNoEnable rewards catalogue for this model
GET /refs

Return all card models belonging to your company.

PUT /refs/:refId

Update a specific card model. Partial updates supported.

DELETE /refs/:refId

Delete a card model. Already issued cards are not affected.

5

5. Issued Cards

Issued cards are the actual digital passes added to Apple Wallet or Google Wallet by end users.

POST /cards

Create a new card for an end user. Returns the pass URL to share or embed in a QR code.

Field Type Required Description
refIdstringYesCard model ID
userNamestringYesUser full name
userEmailstringNoUser email address
userPhonestringNoUser phone number
customFieldsobjectNoKey-value object with extra user fields
Example Response
{
  "cardId": "card_x9y8z7w6",
  "passUrl": "https://wallet.eluneconnections.com/pass/card_x9y8z7w6",
  "qrCode": "data:image/png;base64,..."
}
GET /cards/:cardId

Get the current status of a specific card.

GET /cards

List all cards issued under your company or a specific model.

DELETE /cards/:cardId

Deactivate a card. The user will no longer receive notifications.

6

6. Notifications

Send push notifications directly to the lock screen of users who have your card.

POST /notifications/bulk

Send a notification to all cards, or filter by field values.

Field Type Required Description
titlestringYesNotification title (max 40 chars)
bodystringYesNotification body (max 120 chars)
filtersarrayNoArray of filter objects to target a subset of cards
Each filter object has three keys: field (string), operator (eq / neq / contains / gt / lt) and value.
Example Request
{
  "title": "¡Oferta especial!",
  "body": "2x1 en cafés hoy hasta las 18h ☕",
  "filters": [
    { "field": "city", "operator": "eq", "value": "Barcelona" }
  ]
}
POST /notifications/single

Send a notification to a single card by its ID.

Field Type Required Description
cardIdstringYesTarget card ID
titlestringYesNotification title (max 40 chars)
bodystringYesNotification body (max 120 chars)
7

7. Points & Rewards

Manage loyalty points and a redeemable rewards catalogue.

POST /points/add

Add points to one or more cards (bulk or single).

Field Type Required Description
pointsnumberYesNumber of points to add or subtract
conceptstringNoTransaction label shown in the history
cardIdstringNoTarget card ID
filtersarrayNoArray of filter objects to target a subset of cards
POST /points/subtract

Subtract points from one or more cards.

GET /points/balance/:cardId

Get the current points balance for a card.

GET /points/history/:cardId

Get the full transaction history for a card.

POST /rewards/redeem

Redeem a reward for a card.

Field Type Required Description
cardIdstringYesTarget card ID
rewardIdstringYesReward ID to redeem
GET /rewards

List all rewards in your catalogue.

8

8. Webhooks

Register an HTTPS endpoint to receive real-time events from Elune.

POST /webhooks

Register a webhook URL for a specific event type.

Field Type Required Description
urlstringYesYour HTTPS endpoint URL
eventstringYesEvent type to subscribe to

Available event types

card.addedA new card was added to a wallet
card.deletedA card was deleted from a wallet
points.addedPoints were added to a card
reward.redeemedA user redeemed a reward
Webhook payloads are signed with HMAC-SHA256. Verify the X-Elune-Signature header to ensure authenticity.
If your endpoint returns a non-2xx status, Elune will retry up to 3 times with exponential backoff.
GET /webhooks

List all registered webhooks for your company.

DELETE /webhooks/:webhookId

Delete a webhook registration.

9

9. Images

Upload logos and banners for your company or specific card models.

POST /images/logo

Upload by URL Provide a publicly accessible image URL.

Upload by file Upload the image file directly.

POST /images/banner

Provide a publicly accessible image URL.

Banner resolution order
  1. Model banner
  2. Company banner
  3. Default banner

Set a company-level banner as a fallback and override it per card model.

10

10. Error Handling

All error responses follow a consistent format.

Example Response
{
  "error": "invalid_api_key",
  "message": "The provided API key is missing or invalid.",
  "statusCode": 401
}
Common HTTP status codes Description
200Request successful
201Resource created
202Accepted for asynchronous processing
400Invalid request
401Missing or invalid API Key
403Quota exceeded
404Resource not found
500Internal server error
11

Quick Reference — All Endpoints

Method Path Auth Description
POST/registerNoneRegister company
PUT/company/configAPI KeyUpdate configuration
POST/images/bannerAPI KeyUpload banner
POST/images/logoAPI KeyUpload logo
POST/refsAPI KeyCreate card model
GET/refsAPI KeyList models
PUT/refs/:refIdAPI KeyUpdate model
DELETE/refs/:refIdAPI KeyDelete model
POST/cardsAPI KeyCreate card
GET/cards/:cardIdAPI KeyCard status
GET/cardsAPI KeyList cards
DELETE/cards/:cardIdAPI KeyDeactivate card
POST/notifications/bulkAPI KeyBulk notification
POST/notifications/singleAPI KeySingle notification
POST/points/addAPI KeyAdd points
POST/points/subtractAPI KeySubtract points
GET/points/balance/:idAPI KeyBalance
GET/points/history/:idAPI KeyHistory
POST/rewards/redeemAPI KeyRedeem
GET/rewardsAPI KeyRewards
POST/webhooksAPI KeyRegister company
GET/webhooksAPI KeyList models
DELETE/webhooks/:idAPI KeyDelete model
POST/register
Register company
PUT/company/config
Update configuration
POST/refs
Create card model
POST/cards
Create card
POST/notifications/bulk
Bulk notification
POST/notifications/single
Single notification
POST/points/add
Add points
POST/rewards/redeem
Redeem