API Reference | Lynes Loyalty API
User Groups API Reference | Lynes Loyalty API

User Groups API

Use this endpoint to create user groups programmatically. User groups segment users for differentiated event rewards, leaderboards, and analytics.

  • Authentication: JWT Bearer token or API key (x-api-key). See JWT Authentication and API Secret.
  • Versioning: Paths support /v0, /v1, /v2, /v3. The version prefix is stripped internally.
ℹ️

Dashboard vs. API

You can also manage user groups in the Lynes dashboard. The Customer API endpoint is intended for server-side integrations that need to create groups and receive the userGroupId in the response.

Endpoints Overview

MethodPathDescription
POST/usergroupCreate a user group (returns userGroupId)

The admin dashboard uses POST /admin/usergroup with the same payload and logic (Cognito authentication).

POST /usergroup – Create User Group

Creates a new user group in the project table. The group is stored with status ACTIVE.

  • Method: POST
  • Path: /v1/usergroup
  • Auth (one of):
    • Authorization: Bearer <JWT_TOKEN>
    • x-api-key: <API_KEY>
ℹ️

JWT: `sub` claim

JWTs must include a non-empty sub claim or authentication fails. For this endpoint, sub is not evaluated — use a fixed service identifier (e.g. backend-integration), not an end-user ID.

Request Body

{
  "userGroupId": "your-usergroup-id",
  "title": {
    "default": "Region Unterfranken",
    "de": "Region Unterfranken",
    "en": "Lower Franconia"
  },
  "description": {
    "default": "Users in Unterfranken",
    "de": "Nutzer in Unterfranken"
  }
}

Fields

FieldTypeRequiredDescription
titleobjectYesMultilingual display name. Must include default and de. en is optional.
descriptionobjectNoMultilingual description. Defaults to empty strings if omitted.
userGroupIdstringNoCustom identifier (letters, numbers, _, -, max 128 chars). If omitted, the API generates one (e.g. ug_a1b2c3d4e5f6).

Example Request

curl -X POST "https://<your-api-host>/v1/usergroup" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": {
      "default": "Premium subscribers",
      "de": "Premium-Abonnenten"
    },
    "description": {
      "default": "Paying subscribers",
      "de": "Zahlende Abonnenten"
    }
  }'

With API key:

curl -X POST "https://<your-api-host>/v1/usergroup" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userGroupId": "premium",
    "title": { "default": "Premium", "de": "Premium" }
  }'

Responses

201 Created

{
  "message": "User group created successfully",
  "userGroupId": "ug_a1b2c3d4e5f6",
  "createdAt": 1740000000000
}
  • userGroupId – Use this value in event metadata.usergroup and leaderboard groupId parameters.
  • createdAt – Unix timestamp in milliseconds.

400 Bad Request

  • Invalid or missing title
  • Invalid userGroupId format (special characters not allowed)
  • userGroupId is "default" (reserved system group)

401 Unauthorized

  • Missing or invalid JWT / API key
  • Anonymous access not allowed for this endpoint

409 Conflict

  • A user group with the same userGroupId already exists. Existing data is not overwritten.
{
  "statusCode": 409,
  "message": "User group with id \"your-usergroup-id\" already exists"
}

500 Internal Server Error

  • Unexpected server or database error

Using the user group ID

After creation, reference the group when logging events:

{
  "eventId": "purchase_completed",
  "userId": "user-123",
  "metadata": {
    "usergroup": ["your-usergroup-id"],
    "amount": 29.99
  }
}

See Send Event and Event Settings – User Group Rewards.

Related

User & Loyalty API Reference | Lynes Loyalty API