Quick decision guide

✅

Recommendation: For all new integrations, start with the JSON API. All future development and new features will be introduced in the JSON API.

JSON API ("Integration JSON")

The modern, REST-style interface and smenso's primary API model going forward.

Format: JSON request and response bodies
Operations: Create, Read, Update, Delete
Processing: Synchronous and asynchronous (depending on endpoint)
Status: Actively developed - new features ship here first

Example endpoint:

POST https://{workspace}.smenso.cloud/skyisland/api/integration/absence/json

Example request:

curl -X POST \
  "https://{workspace}.smenso.cloud/skyisland/api/integration/absence/json" \
  -H "Authorization: Basic {your-api-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "{user-guid}",
    "startDate": "15.09.2025",
    "endDate": "19.09.2025",
    "absenceTypeId": {type-id}
  }'

Best for: Lightweight integrations, automation workflows, event-driven architectures, and any project where you want access to the latest API capabilities.

XML API ("Integration XML")

A comprehensive interface for structured batch operations and advanced workflows.

Format: XML request and response bodies
Operations: Create, Read, Update, Delete
Processing: Primarily asynchronous (ticket-based)
Status: Fully supported, but no longer extended with new features

Example endpoint:

POST https://{workspace}.smenso.cloud/skyisland/api/integration/task

Example request:

curl -X POST \
  "https://{workspace}.smenso.cloud/skyisland/api/integration/task" \
  -H "Authorization: Basic {your-api-token}" \
  -H "Content-Type: application/xml" \
  -d '<Tasks projectId="{project-guid}">
        <Task>
          <Title><![CDATA[My new task]]></Title>
          <Priority>1</Priority>
        </Task>
        </Tasks>'

Best for: Existing enterprise integrations, large-scale batch imports, and workflows that require the ticket-based async processing model.

Reporting API ("Export")

A read-only export interface driven by saved list views configured in the smenso UI.

Format: Returns JSON or CSV
Operations: Read-only (GET and POST for filtered queries)
Processing: Synchronous
Status: Stable

How it works:

1. Create or select a saved list view in the smenso UI (e.g., a portfolio overview with specific columns).
2. Copy the API link for that view (available via the share menu in the UI).
3. Call the API - it returns exactly the fields displayed in the selected view.

Example endpoint:

GET https://{workspace}.smenso.cloud/skyisland/api/reports/projects?view={viewId}

Output format control:

# JSON output (default)
&format=json

# CSV output
&format=csv

# German locale (affects date formats etc.)
&lang=de

📘

Some Reporting endpoints support POST to pass advanced filter criteria in the request body. Despite using POST, these endpoints remain read-only and do not modify data.

Best for: Dashboards (e.g., Power BI), periodic data exports, analytics, and scenarios where business users control the output schema via the UI.

Comparison table

Combining API models

You can use multiple API models within the same integration and with the same token:

• JSON API + Reporting API: Use JSON for write operations and Reporting for periodic data exports to a BI tool.
• XML API + Reporting API: Continue using XML for batch imports while adding Reporting for analytics.
• JSON API + XML API: Unusual, but possible during a migration phase.

The same role-based visibility rules apply across all models.

Migration guidance