Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Common Scenarios

Prerequisites

POS Integration API 2.6.0 or later is required for any scenario that writes a POS Instructor profile — scenarios 2, 3, 4 and 7 on this page, and any use of the upsertPosInstructor block.

Check your resort's version with GET /health on the POS Integration API; it reports Package Version. The POS Integration API is installed per resort, so your version is independent of Flaik Connect and does not update with it. If you are below 2.6.0, contact resortsupport@flaik.com to arrange the upgrade before building against these flows.

On 2.5.x, POS Instructor writes behave differently in four ways — two of them silent:

On 2.5.x
Effect

An instructor update that omits posInstructorEmployeeTypeCode

Rejected with InstructorEmployeeTypeCode: -1 not found

Setting posInstructorEmployeeTypeCode on create

Ignored — every instructor is created Full Time

A partial instructor update that omits posInstructorPriorityRanking

Silently overwrites the rank with the default 9999

A partial instructor update that omits posInstructorLessonLocationCode

Silently resets the lesson location to the first configured entry

The last two mean there is no safe partial instructor update below 2.6.0. If you must integrate before upgrading, always send the complete upsertPosInstructor block — including rank, lesson location, location and employment type — on every instructor write, and accept that employment type will not take effect on creates.

Scenarios 1, 5 and 6 do not write an instructor profile and are unaffected by this prerequisite.

Before you start

Everything on this page uses one endpoint. POST /api/employee/upsert takes four independent action flags, and which combination you set is what makes a request "Flaik only", "POS only", "a deactivation", and so on. There is no separate create, update, delete or archive endpoint.

You want to affect
Set

The Flaik employee record

actionUpsertInFlaik: true

The POS Person (the human)

actionUpsertPosPerson: true

The POS Employee (their job)

actionUpsertPosEmployee: true

The POS Instructor (their teaching profile)

actionUpsertPosInstructor: true

At least one must be true. Each destination succeeds or fails independently, so a partial result is normal and expected — always read the per-destination flags on the polling response rather than assuming all-or-nothing.

Create vs update is decided by id. Omit the top-level id and you create a new Flaik employee; supply it and you update that one. There is no separate update call.

POS codes are resort-specific. Every pos*Code value below is a code from the resort's POS reference data. Fetch the valid set from GET api/ResortConfiguration/* rather than hard-coding — the examples here use RTP's common values for illustration.

Flaik ids are resort-specific too, and are not exposed by the API. primaryTeachingDisciplineId, jobTitleId and employmentTypeId are Flaik reference ids that differ per resort. Flaik Connect has no endpoint that lists them, so obtain them from your Flaik implementation contact before you start. The numeric ids in the examples below are illustrative only.

Processing is asynchronous. Every submit returns an upsertEmployeeRequestId and queues the work. Poll Upsert Status until processingStatus is 3 (CompletedSuccessfully) or 4 (CompletedWithError), or supply a webHookUrl and let Flaik call you back.

1. Create an employee in Flaik only

The common case for resorts without a POS integration, or when onboarding staff who will never appear in the POS.

Set only actionUpsertInFlaik. Remember that primaryTeachingDisciplineId is required when creating — including for non-teaching staff, who take the Admin discipline id. Omitting it returns a 400.

Confirm it landed: poll the status endpoint and read actionUpsertInFlaikEmployeeId (the new Flaik employee id) and actionUpsertInFlaikEmployeeWasCreated (true for a create, false if it matched and updated an existing person).

The upsertEmployment block above is complete, and that is required. If you send this block at all, it must carry startDate, jobTitleId, employmentTypeId and all three wage position ids — an incomplete block is rejected with a 400. Send "" for wage position ids the employee does not have, as above. See scenario 4 for why.

Omit upsertEmployment entirely and the employee is still created — but with no job title, employment dates or wage rates for the season. That is legal and safe; it is partial blocks that are not.

2. Create a person in the POS only

For staff who need to exist in the POS but not in Flaik's staff management — or when the POS is your system of record and Flaik is populated separately.

Leave actionUpsertInFlaik as false and enable the POS actions you need. Note that posEmployeeId is required whenever actionUpsertPosEmployee is true; a blank value is rejected with a 400 rather than failing later in the POS.

Confirm it landed: read actionUpsertPOSPersonIdentifier (the POS person id — the RTP IPCode), plus the *WasCreated and *HasError flags for each POS destination.

An RTP instructor must have a supervisor. This is enforced by the POS, not by request validation, so a missing supervisor comes back as an error on actionUpsertPOSInstructorErrorMessage rather than as a 400. If you omit posInstructorSupervisorUniqueIdentifier but set the top-level supervisorFlaikEmployeeId, Flaik falls back to that supervisor's POS identifier.

Creating an instructor without posInstructorEmployeeTypeCode makes them Full Time, because that is RTP's default. Set it explicitly if they are Part Time or Casual using the correct codes for your resort.

3. Create an employee in both Flaik and the POS

The standard onboarding path for an integrated resort: one call creates the Flaik employee and mirrors the person into the POS.

Combine scenarios 1 and 2 — enable actionUpsertInFlaik alongside the POS flags. The top-level person fields (name, date of birth, contact details, address) are shared: the POS Person is built from them, and upsertPosPerson only carries POS-specific overrides such as posGenderCode.

Confirm it landed: you should get both actionUpsertInFlaikEmployeeId and actionUpsertPOSPersonIdentifier back. Store both — the Flaik id and the POS identifier are the keys you will use for later updates.

Partial success is real. The Flaik write can succeed while a POS write fails. When retrying, re-submit with only the failed actions enabled rather than replaying the whole payload.

4. Update an existing profile

Updating uses the same endpoint. Two rules govern what happens:

  • Supply the top-level id (the Flaik employee id) to target an existing person. For POS-only updates, supply posIdentifier so Flaik knows which POS person to update.

  • Enable only the actions you want to touch. Leaving actionUpsertPosInstructor as false means the instructor profile is not written at all — this is how you scope an update.

Update the Flaik record only

primaryTeachingDisciplineId is not required on update, so a partial update need not resend it.

The one exception: upsertEmployment is all-or-nothing

Everything above describes the employee fields, which preserve what you omit. The upsertEmployment block does not work that way, and it is the one place where a partial update is unsafe.

That block is full-replace: the employment record is rebuilt from exactly what you send. To stop fields disappearing silently, the API rejects an incomplete block with a 400. When upsertEmployment is present it must carry:

startDate · jobTitleId · employmentTypeId · wageTeachingPositionId · wageNonTeachingPositionId · wageTrainingPositionId

Send "" for any wage position id the employee does not have — an empty string is a valid explicit "none", and only the missing key is rejected.

So there is no such thing as a partial employment update. To change one wage rate, re-send the whole block with that one value different:

If you are not changing employment at all, leave the block out entirely — that is safe and leaves the existing employment record untouched.

Two fields in this block are not covered by the 400, so they need your care. endDate is optional by design, so the API cannot tell an omitted one from an employee with no end date — omitting it clears any stored end date. The four wage rates are plain numbers, so an omitted rate is indistinguishable from a genuine 0.0 and will set that wage to zero. Always send both.

Update the POS instructor only

What happens to fields you leave out: on the POS instructor, omitted fields are preserved — the integration reads the current profile and writes back only what you supplied. Omitting posInstructorEmployeeTypeCode on an update keeps the existing employment type rather than resetting it.

Requires POS Integration API 2.6.0 or later — see Prerequisites. Preserve-on-omit is a 2.6.0 behaviour. Below it, this partial update is rejected outright, and omitting rank or lesson location silently overwrites them.

firstName, lastName and dateOfBirth are always required, on updates as well as creates, even when the action you are performing does not change them.

5. Archive an employee in Flaik

Archiving removes someone from active staff management without deleting them. Set the top-level status to 2 (Archived) with actionUpsertInFlaik: true.

status accepts 1 Active, 2 Archived, 3 Candidate (talent pool). Any other value is rejected with a 400.

What archiving does: the employee's record is retained — it is not deleted — but they drop out of the active staff roster, which filters on active status. They will no longer appear in staff management as a current employee.

Confirm it landed: poll the status endpoint; actionUpsertInFlaikEmployeeWasCreated will be false (an update, not a create) and actionUpsertInFlaikHasError will be absent or false.

Archiving in Flaik does not touch the POS. It is a Flaik-side status only. To deactivate the same person in the POS, combine this with scenarios 6 and 7 in the same request, or send a follow-up call.

6. Make an employee inactive in RTP

Set the POS employee's lifecycle status to inactive with posEmployeeStatusCode: "2".

Use posEmployeeStatusCode, not posEmployeeTypeCode. The status field is the lifecycle (1 Active, 2 Inactive); the type field is the kind of employment. Sending 2 to the type field does not error — it silently reclassifies the person's employment type while leaving them active.

7. Make an instructor inactive in RTP

The instructor profile has its own lifecycle status, separate from the employee's. Set posProfileStatus to 2.

This is a minimal payload by design — you do not need to resend the instructor's location, rank, supervisor or employment type. Those are preserved, and a deactivation will not collaterally change them.

Requires POS Integration API 2.6.0 or later — see Prerequisites. On 2.5.x this minimal deactivation is rejected, and a padded-out version would silently reset the instructor's rank and lesson location as a side effect of deactivating them. Upgrade before relying on this flow.

Deactivating both at once

An employee and their instructor profile are independent records in RTP. Deactivating one does not deactivate the other. To retire someone completely, send both in a single request:

Add "status": 2 and "actionUpsertInFlaik": true to archive them in Flaik in the same call.

Verifying deactivation directly in RTP: RTP versions these profiles. Each update inserts a new row and marks the previous one StatusCode = 3 (Changed). If you query the RTP tables to confirm, read the row with the highest SequenceNumber for that profile — an unordered read can return a superseded version and make a successful deactivation look like it landed the wrong status.

Choosing your actions at a glance

Goal

InFlaik

PosPerson

PosEmployee

PosInstructor

Key field

Create in Flaik only

✅

primaryTeachingDisciplineId required

Create in POS only

✅

✅

✅

posEmployeeId required

Create in both

✅

✅

✅

✅

as above

Update Flaik record

✅

id

Update POS instructor

✅

id + posIdentifier

Archive in Flaik

✅

status: 2

Employee inactive in RTP

✅

posEmployeeStatusCode: "2"

Instructor inactive in RTP

✅

posProfileStatus: "2"

Need help with employee data ingest? Contact resortsupport@flaik.com.

PreviousUpsert Status
NextRTP Prerequisites

Last updated

Was this helpful?