Quarma360 API v1 – Quick Reference

2026.01.23.

Base URL

https://app.quarma360.com/api/v1

Authentication

X-API-Key: YOUR_API_KEY

Rate Limit

60 requests/minute

Quick Start

# Test connection
curl -H "X-API-Key: YOUR_KEY" https://app.quarma360.com/api/v1/health

# Get organization info
curl -H "X-API-Key: YOUR_KEY" https://app.quarma360.com/api/v1/organization

Endpoints Cheat Sheet

Organization

GET /organization                  # Organization details + stats + config
GET /organization/statistics       # Statistics only
GET /organization/configuration    # Configuration only
GET /competencies                  # List all competencies

Users

GET /users                         # List all users (paginated)
GET /users/{id}                    # User details
GET /users/{id}/competencies       # User's competencies
GET /users/{id}/hierarchy          # Manager, colleagues, subordinates

Common Filters:

?department_id=5
?role=manager|employee|ceo|admin
?search=john
?page=1&per_page=50                # Max per_page: 100
?sort_by=name&sort_order=asc
?locale=hu|en|de                   # Language for competencies

Assessments

GET /assessments                   # List assessments (paginated)
GET /assessments/{id}              # Assessment details
GET /assessments/{id}/participants # Participants (closed only)
GET /assessments/{id}/results      # Results (closed only)

Common Filters:

?status=open|closed
?year=2024
?from_date=2024-01-01
?to_date=2024-12-31
?per_page=50                       # Max: 100

Results

GET /results/user/{userId}         # User's complete history

Bonus/Malus

GET /bonus-malus                   # Current status (all users)
GET /bonus-malus/configuration     # Multiplier configuration
GET /bonus-malus/categories        # All categories (B01-B15)
GET /bonus-malus/{id}              # Assessment bonus summary
GET /bonus-malus/{id}/results      # Assessment bonus details
GET /bonus-malus/user/{userId}     # User's bonus/malus history

Common Filters:

?month=2024-10
?level=8
?department_id=5
?is_paid=1
?per_page=50                       # Max: 100

System

GET /health                        # Health check (auth required)
GET /status                        # Status (public)

Response Format

Success

{
  "success": true,
  "data": { ... }
}

Paginated

{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 150,
    "per_page": 50,
    "current_page": 1,
    "last_page": 3
  }
}

Note: Maximum per_page is 100. Values exceeding 100 are automatically capped.

Error

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Description"
  }
}

Common Error Codes

Code	Status	Meaning
`MISSING_API_KEY`	401	No API key provided
`INVALID_API_KEY_FORMAT`	401	Invalid key format
`INVALID_API_KEY`	401	Invalid/expired key
`API_DISABLED`	403	API disabled for org
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`NOT_FOUND`	404	Resource not found
`ASSESSMENT_NOT_CLOSED`	400	Can't access open assessment
`USER_NOT_IN_ORGANIZATION`	404	User not in your org

Common Patterns

Pagination Loop

let page = 1, hasMore = true;
while (hasMore) {
  const res = await fetch(`/api/v1/users?page=${page}&per_page=100`, {
    headers: { 'X-API-Key': apiKey }
  });
  const data = await res.json();
  // Process data.data
  hasMore = page < data.pagination.last_page;
  page++;
}

Error Handling

const res = await fetch(endpoint, { headers: { 'X-API-Key': key }});

if (res.status === 429) {
  // Rate limited - wait and retry
  const retryAfter = res.headers.get('Retry-After');
  await sleep(retryAfter * 1000);
}

if (res.status === 401) {
  // Invalid API key
  console.error('Authentication failed');
}

const data = await res.json();
if (!data.success) {
  console.error('API Error:', data.error);
}

Rate Limit Check

const remaining = res.headers.get('X-RateLimit-Remaining');
const reset = res.headers.get('X-RateLimit-Reset');

if (remaining < 5) {
  console.warn('Rate limit almost exceeded');
}

Multi-Language Competencies

// Get competencies in Hungarian
const huComp = await fetch('/api/v1/competencies?locale=hu', {
  headers: { 'X-API-Key': apiKey }
});

// Get competencies in English
const enComp = await fetch('/api/v1/competencies?locale=en', {
  headers: { 'X-API-Key': apiKey }
});

Data Relationships

Organization
├── Users (employees)
│   ├── Competencies (with translations)
│   ├── Hierarchy (manager/colleagues/subordinates)
│   ├── Assessment Results (historical)
│   └── Bonus/Malus History
├── Assessments
│   ├── Participants
│   ├── Results (per user)
│   └── Bonus/Malus Payments
├── Competencies (global + custom)
│   └── Translations (hu, en, de, etc.)
└── Configuration

Key Response Examples

Organization Statistics

{
  "total_employees": 85,
  "active_employees": 82,
  "pending_assessments": 1,
  "completed_assessments": 12,
  "total_assessments": 13,
  "active_competencies": 25,
  "total_departments": 8,
  "total_managers": 12
}

Note:

total_employees: All employees (including inactive)
active_employees: Currently active employees only

Competency (with translation)

{
  "id": 1,
  "name": "Leadership",
  "description": "Ability to lead and inspire teams",
  "organization_id": null,
  "type": "global",
  "questions_count": 5
}

Use ?locale=hu for Hungarian, ?locale=en for English, etc.

User with Competencies

{
  "user_id": 123,
  "competencies": [
    {
      "id": 1,
      "name": "Leadership",
      "description": "...",
      "type": "global"
    }
  ]
}

Bonus/Malus Categories

{
  "categories": [
    {"level": 1, "code": "B01", "multiplier": 0.5, "configured": true},
    {"level": 2, "code": "B02", "multiplier": 0.6, "configured": true},
    ...
    {"level": 15, "code": "B15", "multiplier": 2.0, "configured": true}
  ],
  "total_levels": 15
}

Notes

Read-Only: API is read-only (no POST/PUT/DELETE for data)
Closed Assessments: Results only available after assessment closure
Organization Scoped: Each API key accesses only its organization
HTTPS Required: All requests must use HTTPS
Timestamps: ISO 8601 format (e.g., 2024-10-15T10:30:00Z)
Pagination Limit: Maximum 100 items per page (auto-capped)
Multi-Language: Use locale parameter for translated competencies
Performance: All requests logged with response time and status code

Quick Testing

#!/bin/bash
API_KEY="qa360_live_YOUR_KEY"
BASE_URL="https://your-domain.com/api/v1"

# Test authentication
curl -H "X-API-Key: $API_KEY" "$BASE_URL/health"

# Get org info
curl -H "X-API-Key: $API_KEY" "$BASE_URL/organization" | jq '.'

# Get users (test pagination limit)
curl -H "X-API-Key: $API_KEY" "$BASE_URL/users?per_page=500" | jq '.pagination'
# Expected: per_page will be 100 (not 500)

# Get competencies in Hungarian
curl -H "X-API-Key: $API_KEY" "$BASE_URL/competencies?locale=hu" | jq '.data.competencies[0]'

# Get statistics (check active_employees)
curl -H "X-API-Key: $API_KEY" "$BASE_URL/organization/statistics" | jq '.data | {active_employees, total_employees}'

# Check rate limit headers
curl -I -H "X-API-Key: $API_KEY" "$BASE_URL/health" | grep -i ratelimit

# Get bonus categories (B01-B15)
curl -H "X-API-Key: $API_KEY" "$BASE_URL/bonus-malus/categories" | jq '.data.categories | length'
# Expected: 15

Important Limits

Feature	Limit	Notes
Rate Limit	60 req/min	Per API key
Per-Page	100 max	Auto-capped if exceeded
API Keys	1 active/org	Revoke old before new
Response Size	N/A	Pagination recommended
Timeout	30s	Request timeout

Language Support

Competencies support multiple languages via locale parameter:

# Hungarian (default)
/competencies?locale=hu

# English
/competencies?locale=en

# German
/competencies?locale=de

# Romanian
/competencies?locale=ro

# Polish
/competencies?locale=pl

# Czech
/competencies?locale=cs

# Slovak
/competencies?locale=sk

# Slovenian
/competencies?locale=sl

Fallback: If translation unavailable → Hungarian → English

For full documentation, see: API_DOCUMENTATION

Version: 1.0.1
Last Updated: January 25, 2026

Legfontosabb:

Olvasd el további tartalmainkat:

Quarma360 API Documentation v1

The Quarma360 API provides read-only access to your organization’s performance assessment data, employee information, and bonus/malus calculations. This RESTful API uses JSON for all requests and responses.

How to Build the Relationship Map for an Effective 360-Degree Evaluation

The success of a 360-degree evaluation largely depends on how the relationship network...

Olvasd el további tartalmainkat:

Quarma360 API Documentation v1

How to Build the Relationship Map for an Effective 360-Degree Evaluation

The success of a 360-degree evaluation largely depends on how the relationship network is designed. A poorly constructed relationship map can lead to...

Designing and Selecting Competencies for Job Roles

What Is a Competency and Why Is It Important to Measure? Competencies are the specific skills, abilities, and behavioral characteristics that determine how...