Magentus Practice Management FHIR Implementation Guide
1.2.60 - ci-build

Magentus Practice Management FHIR Implementation Guide - Local Development build (v1.2.60) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

## OperationDefinition: Diagnostic Request Claim Operation

Official URL: http://fhir.geniesolutions.io/OperationDefinition/EOrderClaimOperation | Version: 1.2.60
Active as of 2026-04-03 | Computable Name: EOrderClaimOperation

This operation is used to claim a request based on a scanned barcode and returns a group `Task` reference. An `Organization` reference is also supplied so that a particular brand of service may be required for the transfer of the request.

The transferred request will result in the creation of a new set of `Task`s, including a group `Task` and child `Task`s, each of which will be placed in a `requested` status. To distinguish a request that has been claimed, the `businessStatus` of the `Task`s will be set to `claimed-request` and a tag will be set to the same `claimed-request` value. The reason for the tag is that the businessStatus will change over time but the tag is persistent between resource versions.

The original `Task` will be placed in a `cancelled` status and the `businessStatus` will be set to `claimed-cancel`. To prevent re-discovering `Cancelled` tasks, the original filler should set the `businessStatus` to `cancel-handled` and when searching for new `requested` or `cancelled` tasks, explicitly exclude those that have already been handled via the `businessStatus`.

The operation will return a `Coding` value that indicates the result of the claim attempt. If the claim is successful, the group `Task` reference will be returned. If the claim is unsuccessful, an error code will be returned.

URL: [base]/Task/$claim

### Parameters

Use | Name | Scope | Cardinality | Type | Binding | Documentation
IN | requisition |  | 1..1 | Identifier |  | The group identifier for the request, typically the barcode.
IN | organization |  | 1..1 | Reference (Genie Organization) |  | Reference to the branded organization claiming the request.
OUT | groupTask |  | 0..1 | Reference (EOrders Task Fulfillment Request Group) |  | Returns a reference to the group `Task` assigned to the requesting organisation or nothing if an error occurred.
OUT | result |  | 1..1 | Coding | Request Claim Result Type ValueSet (Required) | The result of the attempting request claim.

### Notes:

- The server MUST enforce authentication and authorisation before processing this operation. Callers that are not authenticated or not authorised to claim requests MUST receive a `401 Unauthorized` or `403 Forbidden` response respectively.
- The `groupTask` output is returned for result codes `ok`, `fulfillment-active`, and `already-fulfiller`.
- The `result` Coding indicates the outcome of the claim attempt.

### Parameters

Direction | Name | Type | Card. | Description
--- | --- | --- | --- | ---
in | requisition | Identifier | 1..1 | The group identifier for the request, typically the barcode.
in | organization | Reference(GSOrganization) | 1..1 | Reference to the brand Organization claiming the request.
out | groupTask | Reference(EOrdersTaskFulfillmentGroup) | 0..1 | Reference to the group Task assigned to the claiming organization. Present when result is `ok`, `fulfillment-active`, or `already-fulfiller`.
out | result | Coding | 1..1 | The result of the claim attempt, bound to the claim result code system.

### Result Codes

Code | Display | Description
--- | --- | ---
ok | OK | Claim successful; a new fulfillment Task set has been created for the claiming organization.
fulfillment-active-elsewhere | Fulfillment is in-progress with another organization | The request is actively being fulfilled by a different organization.
fulfillment-active | Fulfillment is in-progress with the provided organization | The provided organization is already actively fulfilling the request.
already-fulfiller | Fulfillment is already claimed by the provided organization | The provided organization has already claimed but not yet started fulfillment.
fulfillment-cancelled | Fulfillment was cancelled | The fulfillment has been cancelled.
requisition-not-found | Requisition Not Found | No request matching the supplied identifier was found.
organization-not-found | Organisation Not Found | The referenced Organization could not be resolved.
claim-in-progress | Claim is already in progress | A concurrent claim attempt is already underway for this request.

### Example Response

    {
      "resourceType": "Parameters",
      "parameter": [
        {
          "name": "groupTask",
          "valueReference": {
            "reference": "Task/b1c3d456-e789-4abc-def0-123456789abc"
          }
        },
        {
          "name": "result",
          "valueCoding": {
            "system": "http://fhir.geniesolutions.io/CodeSystem/eorder-claim-result-type-codesystem",
            "code": "ok",
            "display": "OK"
          }
        }
      ]
    }