API Documentation

The Atriums Circle REST API lets you integrate your system with the loyalty platform.

Authentication

All API requests require an x-api-key header with your API key (available in Admin → Integrations).

Main endpoints

POST
/api/webhook/inbound

Register a transaction (with auto-enroll if member doesn't exist)

POST
/api/import/members

Bulk import members from external system

GET
/api/members

List program members

POST
/api/members

Create a new member

GET
/api/tiers

List configured tiers

GET
/api/leaderboard

Member leaderboard

POST /api/webhook/inbound

Main endpoint for integrating PMS, POS, and other systems. Send a transaction for a customer: if the customer is already a member, the transaction is processed normally. If the customer doesn't exist and customer_name is provided, Circle creates them automatically and returns an invite link.

POST /api/webhook/inbound
Content-Type: application/json
X-Api-Key: sk_live_...

{
  "event": "transaction",
  "customer_email": "mario@rossi.it",
  "customer_phone": "+39123456789",
  "customer_name": "Mario Rossi",
  "amount": 450.00,
  "currency": "EUR",
  "category": "domestic",
  "description": "3 notti – Appartamento Deluxe, Bari",
  "reference": "RES-2026-789",
  "lang": "it"
}

POST /api/import/members

Bulk import members from external systems (PMS, CRM, management software). Creates members with invite links. Idempotent on externalId or email. Max 1000 members per call.

POST /api/import/members
Content-Type: application/json
X-Api-Key: sk_live_...

{
  "source": "atriums-ops",
  "members": [
    {
      "externalId": "CUST-123",
      "name": "Mario Rossi",
      "email": "mario@rossi.it",
      "phone": "+393331234567",
      "totalSpentCents": 45000,
      "lang": "it",
      "consentSource": "explicit"
    }
  ]
}