Payroll is a stream of Case Changes - hire, salary change, bonus, sickness, termination, an address update, and so on. You report what happened; Ason applies the correct payroll logic.
Before reporting anything, you can query which cases you're actually allowed to report: GET .../cases/sets returns every available case, for the company or for a specific employee, based on your assigned regulations. Reporting then always looks the same, no matter which case it is: POST .../cases/sets with the case name and its field values - the same endpoint and shape whether you're reporting a hire, a salary change, or an address update.
The three channels
There are three ways to get data into Ason - all of them end up as the same thing under the hood: a Case Change.
CaseMan (the built-in frontend - see Build your own solution to run it locally) - the guided, no-code way. It shows exactly what's missing (see "Missing Company Data" / "Missing Employee Data" below), walks users through the right case for their situation, and is what most HR users interact with day to day. Available in German, English, French and Italian.
Direct API - your platform reports a case change itself, with exactly the fields it has. See the examples below.
Excel import - for bulk data. You attach a spreadsheet to a case: each column is a case field, each row is an employee (matched by their EmployeeIdentifier). Useful for migrating many employees at once - see "Migrating historical data" below.
Import cases
Some cases - like CompanyOnboardingData or EmployeeNewEntryData, the ones used in Quickstart steps 4 and 6 - are deliberately large "import" cases: dozens of fields, almost all optional, designed to capture everything at once rather than one fact at a time. You don't have to fill in every field - only send what you actually have, and report the rest later as its own, smaller case change.
Master data vs. variable data
Every case field has a time type that decides how a value you report behaves over time:
- Period - master data. Valid from a
startdate onward until you change it again - noendneeded. Example: address, IBAN, civil status. - Moment - variable data. Tied to a single point in time -
startandendare the same date. Example: hours worked on a day, a one-off bonus. - Timeless - practically never changes (e.g. a fixed configuration value).
This is a property of the field, not of the case - both examples below report through the same case (EmployeeNewEntryData), and you only need to send the field(s) that actually changed, not the full onboarding set again.
Moment values are summed within a payrun period. If you report a CHF 500 bonus on May 2 and a CHF 380 bonus on May 16, both fall inside the May payrun period, so the value used for that period's calculation is CHF 880 - not the last value reported, the total of everything reported.
_
_
The same pattern applies to CH.Swissdec.EmployeeActivityWorkedHours (hours worked on a day) - any Moment field, not just bonuses.
Modeling the same fact different ways
Two companies rarely track the same thing the same way - Ason's regulations provide multiple case fields for the same real-world concept, so you can pick the one that matches how your data already looks. For example:
- Sunday work - report it as a flat amount (
CH.Swissdec.EmployeeActivitySundayBonus, in CHF) or as a rate-based surcharge (CH.Swissdec.EmployeeSundaySurcharge50, hours at a 50% surcharge) - whichever matches your source data. - Meal deductions - the calculation itself can vary by employee type, e.g. for hourly-wage restaurant employees.
- Absences - as a number of days, a date range, or with a reduction/percentage applied - depending on what your source system tracks.
- Totals and balances - some customers pre-calculate a total before sending it to Ason; others send the raw components and let Ason calculate. Both are valid - see Embedded Into Your Platform for how to decide which fits your platform.
If you're not sure which variant fits your data, get in touch - matching your existing model to the right case fields is usually a one-time exercise during onboarding.
Migrating historical data
Moving off another payroll system? Historical data is reported through the exact same case changes described above - there's no separate import mode. Two things are specific to migrating rather than reporting as-it-happens:
- Entry date - set an employee's entry date to their original hire date, not the date you migrated them into Ason
- Retroactive calculation - a
startdate in the past is fine; Ason calculates retroactively as needed, but won't re-trigger declarations already sent to authorities for periods before your go-live date
Company Data
Company-level Case Changes - onboarding data, insurance policies, bank details - reported the same way as any other case change (see "The three channels" above). Some company case fields don't hold a text or number value - they hold a file. An insurance policy PDF, a signed contract, a scanned ID: these are reported the same way as any other case change, just with a documents array attached to the value instead of (or alongside) a value.
This is different from Outputs: outputs are files Ason generates (payslips, declarations). Documents are files you upload as evidence for a case value.
Attaching a document: add a documents array to any CaseValueSetup in a case change. Each entry needs a name, a contentType (MIME type), and base64-encoded content.
_
The response echoes back each value with its own id - that id is the case value id, and it's what you need to retrieve or delete the document later. It is not the same as the case change id.
Retrieving documents:
_
Supports the usual OData query parameters (filter, select, top, skip, ...). Each item in the list is a reference (id, name, contentType) - append /{documentId} to fetch the actual content.
Deleting a document: DELETE the same single-document URL (.../documents/{documentId}) to remove it. This is permanent - there's no separate archive step.
Company events (Ereignisse)
The company's case-change history - what was reported, when, and why. Each entry shows the event/field/value with its Start/End/Created dates and reason. There's no "changed by" attribution in the underlying data - you see what changed, not necessarily who entered it.
Missing Company Data
Missing company data is any required company-level field that hasn't been reported yet - a case field that needs a value before Ason can calculate a correct result. Ason tracks this continuously.
- A Task is created automatically pointing at the missing field
- The missing-data view lists everything outstanding for the company, so nothing gets lost between individual tasks
- A payroll period cannot be closed while relevant data is missing - surfacing gaps early, rather than failing at period close, is what keeps results always up to date without manual intervention
Employee Data
Employee-level Case Changes - entry, salary, personal details - reported the same way as any other case change (see "The three channels" above). Some employee case fields don't hold a text or number value - they hold a file. A signed contract, a scanned ID, a salary certificate: these are reported the same way as any other case change, just with a documents array attached to the value instead of (or alongside) a value.
Reference list of all case fields used to report an Employee Case Change - the same fields used in the "Enter salary & employee data" step of the Quickstart - see Employee Master Data and Variable data for employees on the Switzerland Regulation page for the full field reference.
Attaching a document: add a documents array to any CaseValueSetup in a case change, and include employeeId (instead of relying on divisionId alone) so the value is scoped to the right employee. Each document entry needs a name, a contentType (MIME type), and base64-encoded content. The response echoes back each value with its own id - that id is the case value id, and it's what you need to retrieve or delete the document later.
Retrieving documents:
_
Supports the usual OData query parameters (filter, select, top, skip, ...). Each item in the list is a reference (id, name, contentType) - append /{documentId} to fetch the actual content.
Deleting a document: DELETE the same single-document URL (.../documents/{documentId}) to remove it. This is permanent - there's no separate archive step.
Employee events (Ereignisse)
The employee's own case-change history - same idea as company events above, just scoped to that employee: event/field/value with Start/End/Created and reason, no "changed by" attribution.
Missing Employee Data
Missing employee data is any required employee-level field that hasn't been reported yet. Ason tracks this continuously, per employee.
- A Task is created automatically pointing at the missing field
- The missing-data view lists everything outstanding for an employee, so nothing gets lost between individual tasks
- Employees can complete their own missing data directly via ESS, without HR involvement
- A payroll period cannot be closed while relevant data is missing
ESS
ESS (Employee Self-Service) is the portal where employees access their own payroll data directly - without going through HR for every small change or question.
What employees can do:
- Report certain Employee Case Changes themselves - e.g. address or bank account changes
- Complete their own missing data (see "Missing Employee Data" above) when something required is outstanding
- View and download their own documents - payslips, salary certificates, contracts
What stays with HR: case changes that need review or approval (e.g. salary changes, contract changes) are not exposed via ESS by default - they're reported by HR through the regular Employee Case Change flow. Which fields are ESS-editable is configured per regulation.
Access: employees access ESS with their existing account if you've connected your Identity & Access Management (IAM) - see Embedded Payroll for the two ways to set that up. No separate ESS login is needed.
After you report data
Regardless of which channel was used, the same checks apply:
- Missing Company Data / Missing Employee Data (above) - required fields that are still outstanding
- Payroll Control (Lohnkontrolle) - flagged cases worth a human check before closing a period
- Tasks - created automatically to guide whoever needs to act next
FAQ
Reporting case changes
Do I need to resend the full onboarding case every time something changes?
No - only send the field(s) that actually changed, not the full case again.
What happens if I report the same Moment field twice in one period?
The values are summed, not overwritten - see "Master data vs. variable data" above.
How do I know which channel (CaseMan, API, Excel) to use?
Whichever matches your integration - see "The three channels" above. You can mix channels freely; they all produce the same Case Change underneath.
Can I report data with a start date in the past?
Yes - see "Migrating historical data" above for what's specific to backdated data.
What do I find under "new event" (Ctrl+K)?
The case-change entry point in CaseMan - every case you're allowed to report, for the company or for a specific employee, based on your assigned regulations.
Can I report an event for an employee who has already left?
Yes, as long as the date falls within their employment period and isn't before the payroll's accounting start date - the employee list just hides former employees by default (there's a toggle to show them), it doesn't block reporting events for them.
Can I choose myself which events I see, or turn some off?
No - the case list is driven by your assigned regulation(s), not individually configurable per user.
How do I subscribe to a webhook?
POST /tenants/{tenantId}/webhooks - see Webhooks for the full setup example.
Can events only be entered via the frontend, or also imported?
Both, plus the direct API - see "The three channels" above.
How do I import an event/change?
Via Excel import - attach a spreadsheet to a case, where each column is a case field and each row is an employee (matched by EmployeeIdentifier).
Can I delete a case change I already reported?
No delete operation was found - corrections go through reporting a new case change (or a cancellation), not deleting the original one.
Company data & documents
Can I attach a document without also setting a value?
Yes - the example above sets value: null and only attaches the document.
Is there a file size or type limit?
Not documented here - check the API Reference for the specific case field's constraints.
How does this differ from what Quickstart does?
It's the same mechanism - Quickstart steps 4 (company) and 6 (employee) are live examples of exactly this.
Do I see all of the company's data under Company Data?
Yes - every company-level case field relevant to your assigned regulations.
As of which date are the values shown?
Today's currently active values - there's no "as of" date picker on the main screen.
Can I see values from the past, or future-dated values that aren't valid yet?
Yes - any field with more than one recorded value gets a History view, listing every value with its Start/End/Created dates, including future-dated ones.
Which documents do I see under Documents?
Files attached to case values - insurance policies, signed contracts, scanned IDs, and similar evidence. This is different from Outputs, which Ason generates itself (payslips, declarations).
Can I upload documents myself? Where?
Yes - attach a documents array to a case value, either through CaseMan or the API (see "Company Data" above).
Can I delete documents?
Via the API, yes (DELETE .../documents/{documentId}, permanent). In the standard product frontend, the delete control on the documents list is only visible to Ason's internal support role - a normal Admin/Manager user won't see a delete button there.
Missing data
Does missing data block closing a period?
Yes - a payroll period cannot be closed while relevant data is missing, at company or employee level.
Who resolves missing company data vs. missing employee data?
Company: HR / admin only, via the regular case-change flow - there's no self-service equivalent at company level. Employee: either HR, or the employee themselves via ESS.
How is a field reported once it's no longer missing?
The same way as any other case field - see "The three channels" above.
Why do these tasks appear at all?
Because a required case field doesn't have a value yet - Ason needs it to calculate a correct result, so it's flagged automatically, whether at company or employee level.
Do employees see their own missing data in ESS too?
Yes - an employee sees exactly their own outstanding missing-data items via ESS, and can complete them directly.
Employee data & documents
Can I attach more than one document to a case value?
Yes - the documents array accepts multiple entries.
How do I find the caseValueId for a document I attached earlier?
It's returned in the response when you report the case change - see "Employee Data" above.
Can employees see their own documents?
Yes, via ESS.
Is employee data scoped only to that individual employee?
Yes - everything here is scoped to employeeId.
Does employee data work the same way as company data?
Yes - today's values by default, full history per field, documents attached to case values, deletable only via the API.
ESS
Can employees report a salary change themselves?
No - that needs review or approval and stays with HR. Only certain fields (e.g. address) are ESS-editable, configured per regulation.
Do employees need a separate ESS login?
No - ESS uses the same IAM-connected account as the rest of your platform.
Can an employee see all of their data, or other employees'/company data?
Only their own record - access is strictly scoped to their own employee record, never other employees' or company data.
Do employees see reports in ESS? Which ones?
Only their own documents (payslips, salary certificates, contracts) via the Documents tab - there's no separate broader reports view in ESS.
Can employees report their own personal data via ESS? Which fields?
Yes, but only whatever fields are configured as ESS-editable per regulation (typically things like address or bank details) - fields needing review or approval, like salary, stay with HR.
Can HR see when an employee has entered/completed data via ESS?
HR can see what changed and when in the case-change history, but the underlying data doesn't carry a "changed by" field - so you can't reliably tell from that history alone whether a given change came from HR or from the employee via ESS.
API Endpoints
Case changes:
| What | Call |
|---|---|
| List cases available to report (company or employee) | GET /tenants/{orgId}/payrolls/{payrollId}/cases/sets |
| Report a case change | POST /tenants/{orgId}/payrolls/{payrollId}/cases/sets |
| List reported case changes (history) | GET /tenants/{orgId}/payrolls/{payrollId}/changes |
| Get current data values | GET /tenants/{orgId}/payrolls/{payrollId}/cases/values/time |
| Get a field's value history | GET /tenants/{orgId}/payrolls/{payrollId}/changes/values |
| Count data values (e.g. for missing-data checks) | GET /tenants/{orgId}/payrolls/{payrollId}/cases/values/count |
| List case fields that hold documents | GET /tenants/{orgId}/payrolls/{payrollId}/casefields |
Company data & documents:
| What | Call |
|---|---|
| Get a company document | GET /tenants/{orgId}/companycases/{caseValueId}/documents/{documentId} |
| Delete a company document | DELETE (same URL as above) |
| List missing company data | GET /tenants/{orgId}/payrolls/{payrollId}/missingdata |
Employee data & documents:
| What | Call |
|---|---|
| Get an employee document | GET /tenants/{orgId}/employees/{employeeId}/cases/{caseValueId}/documents/{documentId} |
| Delete an employee document | DELETE (same URL as above) |
| List missing employee data | GET /tenants/{orgId}/payrolls/{payrollId}/missingdata/employees |
ESS reuses the regular case-change, missing-data and document endpoints above, scoped to the logged-in employee's own record - there is no separate ESS-only API surface.