> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolve FHIR Codings - Batch

## Overview

Batch-resolve up to **100** FHIR `Coding` inputs in a single request. The
batch never fails because one coding could not be resolved - failing
items are reported inline in the `results` array with an `error`
field, and the surrounding successful resolutions are still returned.

Use this endpoint in ETL pipelines where you are iterating over a FHIR
Bundle or exporting a FHIR dataset and need high-throughput code
resolution.

## Request Body

<ParamField body="codings" type="array" required>
  Array of FHIR coding inputs. Each item accepts the same fields as the
  single resolve endpoint: `system`, `code`, `display`, `vocabulary_id`.
  Maximum 100 items.
</ParamField>

<ParamField body="resource_type" type="string">
  FHIR resource type applied to every item in the batch. Used for
  domain alignment checks and as the domain filter on semantic search
  fallbacks. Supported values match the single resolve endpoint.
</ParamField>

<ParamField body="include_recommendations" type="boolean" default="false">
  Include Phoebe recommendations on every successful resolution.
</ParamField>

<ParamField body="recommendations_limit" type="integer" default="5">
  Maximum Phoebe recommendations per resolved concept (1–20).
</ParamField>

<ParamField body="include_quality" type="boolean" default="false">
  Include a `mapping_quality` signal on every successful resolution.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.omophub.com/v1/fhir/resolve/batch" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "codings": [
        { "system": "http://snomed.info/sct", "code": "44054006" },
        { "system": "http://loinc.org", "code": "2951-2" },
        { "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "197696" },
        { "system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "E11.9" }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.omophub.com/v1/fhir/resolve/batch",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={
          "codings": [
              {"system": "http://snomed.info/sct", "code": "44054006"},
              {"system": "http://loinc.org", "code": "2951-2"},
              {"system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "197696"},
          ],
          "include_quality": True,
      },
  )
  for item in resp.json()["data"]["results"]:
      if "resolution" in item:
          print(item["resolution"]["standard_concept"]["concept_name"],
                "→", item["resolution"]["target_table"])
      else:
          print("failed:", item["error"]["code"], item["input"])
  ```
</RequestExample>

<ResponseExample>
  ```json Mixed batch with one failure theme={null}
  {
    "success": true,
    "data": {
      "results": [
        {
          "input": {
            "system": "http://snomed.info/sct",
            "code": "44054006"
          },
          "resolution": {
            "vocabulary_id": "SNOMED",
            "source_concept": {
              "concept_id": 201826,
              "concept_name": "Type 2 diabetes mellitus",
              "concept_code": "44054006",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S"
            },
            "standard_concept": {
              "concept_id": 201826,
              "concept_name": "Type 2 diabetes mellitus",
              "concept_code": "44054006",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S"
            },
            "mapping_type": "direct",
            "target_table": "condition_occurrence",
            "domain_resource_alignment": "not_checked"
          }
        },
        {
          "input": {
            "system": "http://snomed.info/sct",
            "code": "00000000"
          },
          "error": {
            "code": "concept_not_found",
            "message": "No matching OMOP concept found for the provided input",
            "details": {
              "vocabulary_id": "SNOMED",
              "code": "00000000"
            }
          }
        }
      ],
      "summary": {
        "total": 2,
        "resolved": 1,
        "failed": 1
      }
    },
    "meta": {
      "request_id": "req_fhir_batch_123",
      "timestamp": "2026-04-09T10:00:00Z",
      "vocab_release": "2025.2"
    }
  }
  ```
</ResponseExample>

## Response Shape

Each entry in `results` is either a successful resolution (same shape as
[`POST /fhir/resolve`](/api-reference/fhir/resolve)) or an error entry:

```json theme={null}
{
  "input": { /* echoed coding plus resource_type */ },
  "error": {
    "code": "concept_not_found",
    "message": "…",
    "details": { /* optional */ }
  }
}
```

The `summary` block reports totals to make monitoring easier:

| Field      | Type    | Description                          |
| ---------- | ------- | ------------------------------------ |
| `total`    | integer | Number of codings submitted          |
| `resolved` | integer | Number that resolved successfully    |
| `failed`   | integer | Number that reported an inline error |

## Errors

| HTTP | `error.code`            | Cause                                                 |
| ---- | ----------------------- | ----------------------------------------------------- |
| 400  | `validation_error`      | `codings` missing, empty, or exceeds 100 items        |
| 400  | `invalid_resource_type` | `resource_type` is not a supported FHIR resource type |

Per-item errors (e.g. `concept_not_found`, `unknown_system`,
`vocabulary_restricted`) are returned inline in the `results` array and
do not fail the batch.

## See also

* [Single resolve](/api-reference/fhir/resolve)
* [CodeableConcept resolve](/api-reference/fhir/resolve-codeable-concept)