Integrating with the JSON or XML API
Integrationer · Steg-för-steg-guide
Modul:
Tillvalsmodul: Importmodulen
För integrationsansvariga och administratörer
Uppdaterad 2026-11-12 10:50
✓
Short answer
First determine which task the integration should create or update. Then choose the API call and the JSON or XML format corresponding to that specific task. Test with a limited data set and check both the API response and the result in Timeplan.
Fördjupning
Before you start
The import module must be enabled for the import functions in this guide. Appoint a person responsible for integration and another responsible for the affected tasks in Timeplan. An API is an interface that allows another system to submit or retrieve data through a call. JSON and XML describe how data is structured in the call; they do not determine which permissions or functions are used.
Obtain the current documentation for the chosen call. Here you need to check the address, which data must be sent, their format, and which access is required. This guide does not replace that description or provide a ready-made example for your specific function.
!
Do not test against live data without a recovery plan
Some imports update existing employments or replace schedules and balances for a date. Check which data is changed and how to correct a faulty run before starting the integration.
Steg för steg
Choose the right API
1Describe the task to be transferredDecide whether you need to transfer budget, units, shifts, personal data or holiday balances. #### Further details - JSON is used in the documented data for, among other things, budget values, creation or updating of units, as well as planned shifts and full-day absences. These calls have different fields and different effects. - XML is used, among others, for Hogia's personal and holiday balance data and SD Worx employment and holiday information. An XML file structured for one provider should not be sent to another provider's endpoint. - The file extension does not determine API choice. Read the description of the data content for the call that will actually be used and verify which external identifiers need to exist beforehand. A readable format alone is not enough if the call concerns a different task than the one you want to change.
2Arrange permission and identifiersCheck which rights the integration requires and how external companies, employees, accounts and units are identified. #### Further details - The JSON calls /v1/dataimport/forenadebudget, /v1/dataimport/budget and /v1/dataimport/createorupdatecostdivision require an authenticated Timeplan user. This means the call must use a verified user identity. Verify that the integration uses the correct account and the correct Timeplan environment for the chosen call. - JSON import of shifts via /integration/shifts/json requires super administrator permission or the authorization level Timeplan Support. In addition, the account must have full access to all companies or all tasks. Only one of these two access options is required; both are not needed simultaneously. Do not confuse tasks with the organisation's higher-level departments when checking access. - Hogia's personal and employment import via /v1/dataimport/hogiapersonimport requires an authenticated Timeplan user. It does not have the same permission requirements as the SD Worx calls, even though both accept XML. - SD Worx calls /v1/integrations/sdworx/import/employment_update and /v1/integrations/sdworx/import/staff_vacation require super administrator permission or the authorization level Timeplan Support. Check this permission before testing either of these calls; access to Hogia's personal import is not sufficient for control. - Hogia's separate import of holiday balances via /payroll/balances/hogia requires both an authenticated user and the page access that the call's public API control requires. The fact that an account can run Hogia's personal import does not show that it can also update holiday balances. Have the responsible administrator verify access for this specific call before using the integration. - An external identifier must point to the correct employee, account or unit. If a number cannot be matched, the connection must be corrected before testing continues. Do not use an internal database ID as a guessed replacement; a seemingly valid number might instead refer to a different task than the one you intend to change. - With Hogia XML, personal identity number, collective agreement and task must be checked against Timeplan before submitting personal data. An unknown value for collective agreement may currently select another agreement instead of triggering an error. Multiple people with the same identifier can also yield a first match without a duplicate error, and for an already registered person, the task from the previous agreement may be used despite a different value in the XML file. Therefore, compare the actually changed person, agreement and task after the test; do not interpret a successful response as proof of correct matching. - Passwords, tokens and complete personal or payroll data must not be copied into error reports or regular support messages. Share only the information needed for troubleshooting via an approved channel.
Steg för steg
Testing the integration
1Send a limited testUse the documented format, correct content type, and a small test dataset for the chosen call. > [!WARNING] > Check existing values before sending a repeated call > An error from the SD Worx XML import does not necessarily mean all changes failed: valid records may already have been saved despite the response HTTP 400. A successful Budget import with JSON also replaces previous budget values for the affected account and affected tasks for the entire selected date range. The Budget call multiplies each submitted amount by 3,600 without first checking whether the account pertains to time, quantity or money. Therefore, do not test an amount on an account with a unit other than time as if the recipient's value were established. Have the integration responsible check what already exists in Timeplan and how a rerun affects it before resending the same data. #### Further details - A JSON call requires the fields and date formats described for the chosen function. An XML call requires the corresponding structure for the correct provider. Check the content against the documentation before sending the test; a successful technical response alone does not guarantee that the intended data has been changed. - When importing Budget with JSON, it is not enough to review the dates present in the new file. For the account and each task included, old budget values are replaced on all dates in the interval, even if some dates are missing in the new entries. Therefore, check the entire interval and keep documentation showing which values should remain after the import. - Budget JSON transforms each submitted Amount by multiplying it by 3,600 regardless of the account’s unit. For a time account, you must compare with the intended time unit; for accounts concerning money or quantity, the intended external unit is not yet established. Do not use a successful call as proof that amounts or quantities have the correct size. - Schedule import may replace existing shifts or full-day absence for imported days. Therefore, choose test dates and employees where you can verify both what was added and what was possibly replaced on the Weekly overview page. - Save the timestamp, call type and response from the test. If the response contains a reference or correlation number for the run, record it as well. This allows the integration responsible to find the correct attempt without needing you to share the entire content of the call.
2Check the result in TimeplanCompare the test’s expected value with the actual record for the correct company, date and employee or account. #### Further details - An import of budget values should be followed up on the correct account and date. The saved daily value does not mean that weekly, monthly or other period reports have already been updated: Budget JSON does not request a guaranteed recalculation covering the entire imported interval. Therefore, check reports only after a confirmed calculation covering the right dates, and distinguish between still old report values and missing daily values. A personal or holiday import should be followed up on the correct employee and employment, including via the Personal data page. - If the call is rejected, follow the error description to the data that caused the error. Check data content, permission or external identifier depending on what the response shows. For SD Worx XML, also verify which valid records have already been saved despite HTTP 400. Fix the cause and plan a rerun only when you know how to handle already saved data; then compare both the response and the result in Timeplan before sending more data.
Fördjupning
Confirm the result
The integration is ready for recurring use when a documented test has shown correct permission, correct format and proper change in Timeplan. Also document how you detect and handle failed or duplicate deliveries.
Steg för steg
Frequently asked questions
1Can the same permission be used for all API imports?No. Each call has its own requirements for authentication and access. Check the current API documentation for the chosen function before setting up the integration.