Welcome to the API documentation for the Loialcard Gateway Service. This guide provides comprehensive information on how to integrate with our gateway service APIs, manage API keys, and interact with various endpoints.

Overview

This documentation covers:

Creating and Managing API Keys
General API Information
Client Endpoints
User Endpoints
Notification Endpoints

Our API allows you to interact with client data, manage users, and send notifications. Whether you're building a custom integration or extending the functionality of your Loialcard implementation, this documentation will guide you through the process.

Getting Started

To begin using our API:

Obtain an API key through the Admin Panel (hub.loialcard.com)
Familiarize yourself with the authentication process and general API structure
Explore the available endpoints and their functionalities

Please note that all requests to our API require authentication using your API key. Ensure you follow the security best practices outlined in this documentation to keep your integration secure.

Let's get started with creating and managing your API keys!

Creating and Managing API Keys

To integrate with our gateway service APIs, you'll need to create an API key. Follow these steps:

Access the Admin Panel -> Navigate to the admin panel at hub.loialcard.com
Go to Settings -> In the admin panel, locate and click on the "Settings" option.
Open the API Keys Tab -> Within the Settings page, select the "API Keys" tab.
Manage API Keys -> In this section, you can view existing API keys and create new ones.

Create a New API Key
- Click the "+" button in the top right corner of the API Keys table.
- Provide a name for your API key.
- Provide a Expiry date for your API Key
- Select the desired permission level:
- Read Only: Allows access to retrieve data only
- Read & Write: Allows both data retrieval and modification
Key Details
After creation, you'll see the new key listed with the following information:
- API Key Name
- Key Secret (partially hidden for security)
- Expiration Date
- Last Used Date
- Security Level (Read Only or Read & Write)

Managing Existing Keys
For each key, you have options to:
- Copy the full key secret (clipboard icon)
- Edit key details (pencil icon)
- Delete the key (trash can icon)

Key Expiration : Note that API keys have expiration dates. Be sure to renew or create new keys before they expire to maintain uninterrupted service.

Security Best Practices
- Create separate keys for different integrations or purposes.
- Use the most restrictive permission level necessary for each integration.
- Regularly review and rotate API keys for enhanced security.

Gateway API Documentation

General Information

Authentication

All gateway endpoints require authentication. Include the following header in all requests:

X-API-KEY: <your_api_key>

Content Type

For POST and PUT requests, set the Content-Type header:

Content-Type: application/json

Error Responses

Error response format:

{
  "detail": [
    {
      "loc": [
        "field_name"
      ],
      "msg": "error message",
      "type": "error_type"
    }
  ]
}

Client Endpoints

Retrieve Client

Endpoint: GET /gateway/client
Response Format:

{
  "_key": "string",
  "_id": "string",
  "qr_code": "uuid",
  "client_key": "string",
  "name": "string",
  "long_form_name": "string",
  "email": "string",
  "preview_only": false,
  "address": {
    "address_line1": "string",
    "address_line2": "string",
    "city": "string",
    "country": "string",
    "postal_code": "string"
  },
  "phone": "string",
  "credit_card_required": false,
  "credit_card_required_for_checkin": false,
  "credit_card_required_for_check_purchase": false,
  "allow_guestlist": false,
  "available_languages": [
    "en",
    "es",
    "sv"
  ],
  "language": "en",
  "send_email_copy_to_superadmins_on_new_place_added": false,
  "manual_approval_needed_for_new_members": false,
  "manual_approval_needed_for_member_changes": false,
  "default_time_for_guest_requests": "string",
  "currencies": [
    "string"
  ],
  "events_enabled": false,
  "generic_events_enabled": false,
  "default_currency": "string",
  "logo_image": {
    "public_id": "string",
    "public_url": "string",
    "thumbnail_url": "string",
    "banner_url": "string"
  },
  "svg_logo_image": {
    "public_id": "string",
    "public_url": "string",
    "thumbnail_url": "string",
    "banner_url": "string"
  },
  "background_image": {
    "public_id": "string",
    "public_url": "string",
    "thumbnail_url": "string",
    "banner_url": "string"
  },
  "svg_background_image": {
    "public_id": "string",
    "public_url": "string",
    "thumbnail_url": "string",
    "banner_url": "string"
  },
  "square_logo_image": {
    "public_id": "string",
    "public_url": "string",
    "thumbnail_url": "string",
    "banner_url": "string"
  },
  "svg_square_logo_image": {
    "public_id": "string",
    "public_url": "string",
    "thumbnail_url": "string",
    "banner_url": "string"
  },
  "background_video": {
    "public_id": "string",
    "public_url": "string",
    "thumbnail_url": "string",
    "banner_url": "string"
  },
  "logo_background_color": "string",
  "information_popup": {
    "enabled": false,
    "header": "string",
    "content": "string",
    "button_text": "string"
  },
  "terms_and_conditions": "string",
  "use_boilerplate_terms_and_conditions": false,
  "about_page_client_name": "string",
  "about_page_email": "string",
  "about_page_website": "string",
  "default_latitude": 0,
  "default_longitude": 0,
  "show_guest_stats": false,
  "points_to_claim_reward": 0,
  "reward_text": "string",
  "firebase_javascript_config": {},
  "track_background_location": false,
  "use_secondary_theme_on_custom_background": false,
  "custom_branding": {
    "button_bg_color": "#FFFFFF",
    "button_bg_transparency": 1,
    "button_text_color": "#000000",
    "button_radius": 5,
    "images_radius": 5,
    "form_fields_radius": 5,
    "font": "Arial"
  }
}

User Endpoints

Read Users

Endpoint: GET /gateway/users
Response Format:

[
  {
    "_key": "string",
    "_id": "string",
    "qr_code": "uuid",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "company": "string",
    "phone": "string",
    "phone_country_code": "string",
    "address": {
      "address_line1": "string",
      "address_line2": "string",
      "city": "string",
      "country": "string",
      "postal_code": "string"
    },
    "image": {
      "public_id": "string",
      "public_url": "string",
      "thumbnail_url": "string",
      "banner_url": "string"
    },
    "gender": "string",
    "promo_code": "string",
    "age": 0,
    "dob": "2023-08-25",
    "member_no": "string",
    "notes": "string",
    "roles": [
      {
        "_key": "string",
        "_id": "string",
        "qr_code": "uuid",
        "name": "string",
        "security_level": 0
      }
    ],
    "favourite_place": {},
    "places": [
      {}
    ],
    "freja_user": false,
    "number_of_paid": 0,
    "number_of_free": 0,
    "entry_time": "string",
    "all_night": false,
    "date_registered": "string",
    "membership_card": {},
    "groups": [
      {}
    ],
    "update_request_pending": false,
    "approval_info": {},
    "dynamic_data": {
      "version": 1,
      "values": [
        {
          "field_id": "string",
          "value": "any"
        }
      ]
    },
    "email_update": {},
    "created_datetime_utc": "2023-08-25T12:00:00Z"
  }
]

Read User

Endpoint: GET /gateway/users/user/{key}
Response Format: Same as a single user object in the Read Users response.

Create User

Endpoint: POST /gateway/users/create-user
Request Body Format:

{
  "email": "string",
  "password": "string",
  "is_admin": false
}

Response Format: Same as a single user object in the Read Users response.

Update User

Endpoint: PUT /gateway/users/{user_key}
Request Body Format: Same as Create User, but only include fields that need to be updated.
Response: 204 No Content on success.

User Autocomplete

Endpoint: GET /gateway/users/user-autocomplete
Response Format:

{
  "results": [
    {
      "_key": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "string"
    }
  ],
  "total_count": 0,
  "page": 1,
  "page_size": 10
}

Get List of Roles

Endpoint: GET /gateway/users/all-roles
Response Format:

[
  {
    "_key": "string",
    "_id": "string",
    "qr_code": "uuid",
    "name": "string",
    "security_level": 0
  }
]

Notification Endpoints

Get Notifications

Endpoint: GET /gateway/notifications
Response Format:

[
  {
    "_key": "string",
    "_id": "string",
    "qr_code": "uuid",
    "title": "string",
    "body": "string",
    "notification_image": {
      "public_id": "string",
      "public_url": "string",
      "thumbnail_url": "string",
      "banner_url": "string"
    },
    "url": "string",
    "created_datetime_utc": "string",
    "deep_link_url": "string",
    "is_read": false,
    "send_at": "2023-08-25T12:00:00Z",
    "job_id": "string"
  }
]

Send Notification

Endpoint: POST /gateway/notifications/send-notification
Request Body Format:

{
  "title": "string",
  "body": "string",
  "user_ids": [
    "string"
  ],
  "deep_link_url": "string",
  "notification_image": {
    "public_id": "string",
    "public_url": "string",
    "thumbnail_url": "string",
    "banner_url": "string"
  },
  "send_at": "2023-08-25T12:00:00Z"
}

Response: 200 OK on success.

Get Deep Links

Endpoint: GET /gateway/notifications/deep-links
Response Format:

{
  "deep_link_1": "string",
  "deep_link_2": "string",
  "deep_link_3": "string"
}

Identifying the future URL / web address of your App

Gateway Service Integration