Upsert Status

Overview

Returns the current processing status — and, once complete, the per-subsystem results — of an upsert request previously submitted via Upsert Employee. Because the upsert pipeline is asynchronous, this is the endpoint clients poll to know when their request has finished and what happened.

Authentication

Include your access token in the Authorization header:

Authorization: Bearer {access_token}

This endpoint requires the flaik.connect.api.write scope (same as the submit endpoint). See the Authentication Guide for details.

Endpoint

GET {api-url}/api/employee/upsert/{upsertEmployeeRequestId}

Path Parameters

Parameter	Type	Required	Description
upsertEmployeeRequestId	integer	Yes	The id returned by the submit endpoint

Query Parameters

None.

Example Request

GET {api-url}/api/employee/upsert/90041
Authorization: Bearer {access_token}

Processing Status Values

The processingStatus field on the response is a numeric enum:

Value	Name	Meaning
1	Pending	Queued, not yet picked up. Per-subsystem result fields will be null.
2	Processing	Currently being processed. Per-subsystem result fields will be null.
3	CompletedSuccessfully	All requested actions completed without errors. Per-subsystem result fields are populated.
4	CompletedWithError	One or more requested actions failed. Per-subsystem result fields are populated; check the *HasError flags.

1 and 2 are non-terminal — keep polling. 3 and 4 are terminal.

Polling Guidance

• Poll no faster than once every 2–5 seconds for the same request.

• Most requests reach a terminal state within 30 seconds; back off the interval after that.

• If you've supplied webHookUrl on the original submit, you can rely on the webhook callback and skip polling entirely (still poll on a long timeout as a safety net).

Response Format

Pending / Processing

{
  "upsertEmployeeRequestId": 90041,
  "processedUtc": null,
  "processingStatus": 1,
  "actionUpsertInFlaikEmployeeId": null,
  "actionUpsertInFlaikEmployeeWasCreated": null,
  "actionUpsertInFlaikHasError": null,
  "actionUpsertInFlaikErrorMessage": null,
  "actionUpsertPOSPersonIdentifier": null,
  "actionUpsertPOSPersonWasCreated": null,
  "actionUpsertPOSPersonHasError": null,
  "actionUpsertPOSPersonErrorMessage": null,
  "actionUpsertPOSEmployeeIdentifier": null,
  "actionUpsertPOSEmployeeWasCreated": null,
  "actionUpsertPOSEmployeeHasError": null,
  "actionUpsertPOSEmployeeErrorMessage": null,
  "actionUpsertPOSInstructorIdentifier": null,
  "actionUpsertPOSInstructorWasCreated": null,
  "actionUpsertPOSInstructorHasError": null,
  "actionUpsertPOSInstructorErrorMessage": null,
  "upsertEmployeeRequest": { /* the original request body */ }
}

Completed (CompletedSuccessfully or CompletedWithError)

{
  "upsertEmployeeRequestId": 90041,
  "processedUtc": null,
  "processingStatus": 3,

  "actionUpsertInFlaikEmployeeId": 15,
  "actionUpsertInFlaikEmployeeWasCreated": true,
  "actionUpsertInFlaikHasError": false,
  "actionUpsertInFlaikErrorMessage": null,

  "actionUpsertPOSPersonIdentifier": "POS789",
  "actionUpsertPOSPersonWasCreated": true,
  "actionUpsertPOSPersonHasError": false,
  "actionUpsertPOSPersonErrorMessage": null,

  "actionUpsertPOSEmployeeIdentifier": null,
  "actionUpsertPOSEmployeeWasCreated": null,
  "actionUpsertPOSEmployeeHasError": null,
  "actionUpsertPOSEmployeeErrorMessage": null,

  "actionUpsertPOSInstructorIdentifier": "POS-INST-789",
  "actionUpsertPOSInstructorWasCreated": false,
  "actionUpsertPOSInstructorHasError": false,
  "actionUpsertPOSInstructorErrorMessage": null,

  "upsertEmployeeRequest": { /* the original request body */ }
}

In this example the request asked for Flaik + POS Person + POS Instructor (it didn't ask for POS Employee, so the actionUpsertPOSEmployee* fields stay null). All three requested actions succeeded; the instructor record already existed and was updated rather than created.

Response Field Reference

Top level

Field	Type	Description
upsertEmployeeRequestId	integer	Identifier of the upsert request
processedUtc	datetime	UTC timestamp processing finished. May be null even on terminal states — see Known Quirks.
processingStatus	integer	See Processing Status Values
processingStatusName	string	Human-readable form of processingStatus (e.g. "CompletedSuccessfully"), so you need not hard-code the numeric mapping
upsertEmployeeRequest	object	The original request body, echoed back

Per-subsystem result fields are populated only on terminal states (3 and 4). On 1 and 2 they are all null.

Per-subsystem fields — pattern

For each of the four subsystems (Flaik Employee, POS Person, POS Employee, POS Instructor) the response carries the same four-field pattern:

Suffix	Type	Description
*Identifier (or *EmployeeId for Flaik)	string / integer	The id of the record after upsert. null if the subsystem wasn't requested.
*WasCreated	boolean	true if the record was created, false if it was updated, null if not requested
*HasError	boolean	true if this subsystem failed
*ErrorMessage	string	Error detail when *HasError is true; otherwise null

Flaik Employee

Field	Type
actionUpsertInFlaikEmployeeId	integer
actionUpsertInFlaikEmployeeWasCreated	boolean
actionUpsertInFlaikHasError	boolean
actionUpsertInFlaikErrorMessage	string

POS Person

Field	Type
actionUpsertPOSPersonIdentifier	string
actionUpsertPOSPersonWasCreated	boolean
actionUpsertPOSPersonHasError	boolean
actionUpsertPOSPersonErrorMessage	string

POS Employee

Field	Type
actionUpsertPOSEmployeeIdentifier	string
actionUpsertPOSEmployeeWasCreated	boolean
actionUpsertPOSEmployeeHasError	boolean
actionUpsertPOSEmployeeErrorMessage	string

POS Instructor

Field	Type
actionUpsertPOSInstructorIdentifier	string
actionUpsertPOSInstructorWasCreated	boolean
actionUpsertPOSInstructorHasError	boolean
actionUpsertPOSInstructorErrorMessage	string

Reading the Result

A request with processingStatus = 4 (CompletedWithError) means at least one subsystem failed — not necessarily all of them. Inspect the four *HasError flags individually:

• A processingStatus of 4 with actionUpsertInFlaikHasError = false and actionUpsertPOSEmployeeHasError = true means Flaik was updated successfully but the POS Employee write failed. The Flaik change is not rolled back.

• For each subsystem with *HasError = true, the matching *ErrorMessage carries the failure reason.

This means partial success is possible. Design your retry logic to look at the per-subsystem flags rather than treating the whole request as atomic.

Error Responses

HTTP Status	Description
400	The supplied upsertEmployeeRequestId does not match any submitted request for this resort
401	Missing or invalid access token
403	Token does not include the flaik.connect.api.write scope

Need help interpreting an upsert result? Contact [e-mail].