Skip to main content

Create Relay Operation

Experimental

This is an early access feature and is subject to change.

OPERATION: POST [base]/[Resource]/$create-relay

The Create Relay operation is used to relay requests to another FHIR server.

Supported Resources​

This operation has been implemented for the following resources:

Workflow​

Authorization​

This operation will require the application obtain authorization to read the resource to relay using one of the following SMART clinical scopes.

  • v1: [patient|user|system]/[Location|Organization].[write|*]
  • v2: [patient|user|system]/[Location|Organization].[c] (future)

Parameters​

UseNameCardinalityTypeDocumentation
INresource1..1ResourceThe resource to create.
INtarget-system1..1stringThe unique ID assigned to the external FHIR server.
OUTid0..1stringThe ID assigned to the created resource.
OUToutcome1..1OperationOutcomeThe outcome of the operation. On success this will provide a success statement or warnings related to the change. If the operation was unsuccessful, the OperationOutcome will include the reason for the failure.

Examples​

curl -X POST 'https://fhir.netsmartcloud.com/v4/Organization/$create-relay' \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d @payload.json

Payloads​

Sample Create Relay Payload​

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "resource",
      "resource": {
        // resource to create
      }
    },
    {
      "name": "target-system",
      "valueString": "ac97a53f-54cc-4d73-8f9a-ffae5f503d78"
    }
  ]
}

Sample Create Relay Response Payloads​

Create Relay Success​
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "resource",
      "resource": {
        // resource to create
      }
    },
    {
      "name": "target-system",
      "valueString": "ac97a53f-54cc-4d73-8f9a-ffae5f503d78"
    },
    // outcome of request
    {
      "name": "id",
      "valueReference": {
        "reference": "Organization/123",
        "type": "Organization"
      }
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "information",
            "code": "informational",
            "details": {
              "text": "Success message"
            }
          }
        ]
      }
    }
  ]
}
Invalid Create Relay Payload or Other Unprocessable Request​
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "processing",
      "details": {
        "text": "Exception message"
      }
    }
  ]
}
Rejections or Other Create Relay Processing Errors​
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "resource",
      "resource": {
        // resource to create
      }
    },
    {
      "name": "target-system",
      "valueString": "ac97a53f-54cc-4d73-8f9a-ffae5f503d78"
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "error",
            "code": "processing",
            "details": {
              "text": "status note"
            }
          }
        ]
      }
    }
  ]
}

Integration Patterns​

Relay Workflow​

  1. Configure Target System

    • Obtain target system identifier
    • Validate external FHIR server connectivity
    • Ensure proper authentication

  2. Prepare Resource

    • Create resource with required fields
    • Validate resource structure
    • Include target-system parameter

  3. Execute Relay

    • Submit create relay operation
    • Handle response and extract ID
    • Process OperationOutcome

Best Practices​

  • Validate target system availability before relay
  • Handle network timeouts appropriately
  • Implement retry logic for transient failures
  • Monitor relay operation success rates

Relationships to Other Resources​

Error Handling​

For comprehensive error handling information, see Common Errors.

Support​

For technical support with Create Relay operations: