Import / Interface

Your platform already holds company and/or employee data. This page covers getting it into Ason once (import), keeping it in sync afterwards (interface) - and why open cases still go through CaseMan either way.

Step by step

1. Match employees - one Ason employee per person, keyed by your own identifier
2. Map master data - field by field, codes from lookups, the right start date - try it in the Mapping Tool
3. Map variable data - each pay component to a wage type, dated in its period
4. Import - pick the right cases, report each change with a reason
5. Resolve open cases - through CaseMan, or your own UI on the same calls
6. Keep in sync - send every change live, not in a nightly batch: each follow-up question otherwise waits for the next run

Match employees

• Your key is the identifier: set the employee's identifier to your platform's unique personnel key. It's unique per tenant, so the same person never exists twice
• Find the employee id by identifier: GET /tenants/{orgId}/employees with filter=identifier eq '...' - only if nothing comes back, create the employee with POST /tenants/{orgId}/employees

Map master data

Master data are Period fields - valid from start until changed (see Master data vs. variable data). Field lists: Employee Data Import (category Master Data) and Company Data Import.

• Each field mapped to its Ason case field - the lists show value type and lookup per field
• Codes, not labels for lookup fields - canton GE (abroad: EX), country DE (ISO 3166-1 alpha-2), not "Genf" or "Deutschland". All valid codes: GET /tenants/{orgId}/payrolls/{payrollId}/lookups/values
• Start date = valid-from date in your system - but never before the payroll's accounting start date: anything older starts on that date, with the value it had then
• Structured, not combined - e.g. street and house number in separate fields
• Empty on purpose isn't missing - "AHV number unknown" opens a different case than a missing AHV number

Duplicates and mistakes

Situation	Effect	Fix
Same value sent twice	None on results - one more history entry	Nothing to fix
Wrong value	Applies from its start date	Report the right value with the same start - the later report wins from that date
Wrong start date	Applies from the wrong date	Report again with the right start - if the wrong one started too early, also re-report the previous value for that gap

Map variable data

Variable data are Moment fields - each value is tied to a date and summed within its payrun period. Employee Data Import lists them under Variable Data: bonuses, allowances, hours, expenses, corrections.

• Each pay component mapped to one Ason field and its wage type
• Missing in Ason? Copy a wage type - duplicate the closest copyable one and give it the same name as in your platform (all four languages), so both sides show the same pay component. The copy comes with its own employee case and case field, under its own name - report its values there. See Copying a wage type
• Dated inside the right period - the date decides which payrun period the value is summed into
• Sent exactly once - Ason can't tell a resend from a second bonus

Duplicates and mistakes

Situation	Effect	Fix
Same value sent twice	Summed - paid twice	Report the same case field again with the negative amount - a bonus of 500 is reversed with -500
Wrong amount	Wrong amount paid	Reverse it with the negative amount on the same case field, then report the right amount
Wrong date	Summed into the wrong payrun period	Reverse it with the negative amount on the same date, then report it with the right date

Import

Which cases to report

• Single-field cases are named after their field - importing just one CaseField means reporting a case with that same name
• Special-Data-Cases - deliberately huge: dozens of mostly-optional fields, to capture everything at once instead of one case per field:
  • CompanyOnboardingData - all company setup data in one go (address, insurers, contracts, workplaces, ...)
  • EmployeeNewEntryData - the data needed to hire a new employee (personal data, address, insurances, bank, salary certificate, statistics)
  • PeriodTimelessFieldsCase - all employee master data: every field whose value stays valid until changed (Period and Timeless)
  • MomentFieldsCase - all employee variable data: one-off values tied to a point in time (bonuses, corrections, absences, allowances)
  • CompanyUploadExcelImportFile - employee data as an Excel file: each column maps to a case field, each row to one case change - Employee Data Import File (.xlsx)
• Documents are the exception - always import them as a single-field case, named after the document's CaseField - see Documents on case values

Not sure which case fits? Get in touch.

Every case change

• Reason on every case change: reason is free text, stored with the case change and shown in its history (CaseMan: "Note") - e.g. "Migration from HR platform, cutoff 2026-01-01"
• Reason on the payslip: cases carrying the attribute reasonOnWageTypeNumber can print the reason on the payslip - send attributes: { "reasonOnWageTypeNumber": "<its value>", "includeReasonInPayslip": "true" } (CaseMan: "Show reason in payslip")

A single-field case, named after its field:

Code
{
  "employeeId": "{employeeId}",
  "divisionId": "{divisionId}",
  "reason": "Migration from HR platform, cutoff 2026-01-01",
  "case": {
    "caseName": "CH.Swissdec.EmployeeNationality",
    "values": [
      { "caseFieldName": "CH.Swissdec.EmployeeNationality", "value": "DE", "start": "2026-01-01T00:00:00Z" }
    ]
  }
}

Why always CaseMan

Import without CaseMan delivers the data you have. It can't deliver what Ason asks for next - that depends on the data itself. So even if your HR system feels complete, Ason opens cases after the import, and they're resolved through CaseMan.

What an import can't know

Which fields are required is decided by rules over data that's already there: company setup and earlier answers. A new employee - German, lives in Switzerland, married, spouse also employed:

Step	You deliver	Ason reacts
1	Personal data, Swiss address, marital status, hire date, wage	Not Swiss - case "Record residence category"
2	Residence category B	Withholding tax liable - withholding tax data required
3	Withholding tax data with code C (married, both earning)	Code C - partner data required
4	Partner data (personal data, address)	Partner's employment missing - case "Record partner employment"
5	Partner's employment	Complete - cases close, the employee is payable and ready for ELM submission

None of these steps can be mapped in advance: what's needed next only emerges from the previous answer.

Even complete data opens cases

Trigger	Example
Company setup	Cost centers switched on (also later) - a cost center is required for every employee. No UVGZ or KTG insurance - those cases never appear
Earlier answers	Not Swiss - residence category. Category B - withholding tax data. Code C - partner data
Changes over time	Wage type changes from monthly to hourly - every value the hourly wage needs is required. Child data changes - confirm or correct the withholding tax code
Recurring checks	Hourly wage - record hours every period, or confirm "none". Monthly wage deviates from the previous month - confirm or correct

Recurring checks aren't gaps in your data, and no import can answer them in advance. Unresolved Missing Data and Payroll Control cases also block closing the Payrun Period.

Two example imports

EMPL1 - French national, lives in France, works in Geneva. The import delivers nationality FRA, residence FRA (with "75" in the canton field - a French département number), work location GE, married, 90 % workload, withholding tax location GE, exit 31.10.2026. Empty: residence permit, partner data, withholding tax status.

#	Case Ason opens	Why
1	Record residence category	Not Swiss, permit missing (probably cross-border permit G)
2	Record withholding tax data	Location GE delivered, status and tariff missing
3	Record type of stay	Residence abroad and withholding tax liable - unless a cross-border commuter
4	Record partner data	Married, partner data empty - mandatory for code C
5	Check additional employment / replacement income	90 % workload, withholding tax liable
6	Check exit	Exit in the open period (if that Payroll Control check is switched on)

EMPL2 - German with B permit, hourly wage, Geneva. The import delivers nationality DEU, permit B, married (partner not employed), 1 child, hourly wage, withholding tax location GE. Empty: withholding tax status and tariff - although everything the tariff needs is there (married, sole earner, 1 child).

#	Case Ason opens	Why
1	Record withholding tax data	B permit means withholding tax liable, status and tariff missing
2	Record hours (every period)	Hourly wage - record hours or confirm "no hours"
3	Check withholding tax code (ongoing)	Whenever child data changes

Data that looks complete still opens 6 and 3 cases - and in the second example, two of them recur.

Resolve through Build, not around it

Missing Data and Payroll Control are Cases too. Resolving one goes through Build, then Report - and Ason re-checks, which can open the next case. That loop is what CaseMan runs.

• Skipping Build risks missing newly required fields
• Your own UI works if it runs the same loop on the same calls - a CaseMan equivalent, not a fixed import mapping

to Feature Map