---
title: "Batch upserts cases"
method: POST
path: "/cases/batchUpsert"
tags: ["Case"]
---

# Batch upserts cases

`POST /cases/batchUpsert`

## Request

- Base URL: `http://localhost:3000/api`
- URL: `http://localhost:3000/api/cases/batchUpsert`
- Auth: none declared

## Request body

- CaseArray
  - `cases` Case[], required
    - `caseReference` object
      - `sourceId` string
      - `sourceUrl` string
      - `uploadIds` string[]: An array of UUIDs of uploads where this case was created or updated through bulk upload or automated ingestion.
      - `verificationStatus` 'UNVERIFIED' | 'VERIFIED' | 'EXCLUDED': Whether the case document has been manually verified for correctness. For new cases, if this field isn't provided, a default value of UNVERIFIED will be used.
      - `additionalSources` object[]
        - `sourceUrl` string
    - `demographics` object
      - `gender` string
      - `ageRange` object
        - `start` number
        - `end` number
      - `ethnicity` string
      - `nationalities` string[]
      - `occupation` string
    - `location` Location
      - `query` string
      - `country` string: ISO-3166-2 code for a country.
      - `administrativeAreaLevel1` string
      - `administrativeAreaLevel2` string
      - `administrativeAreaLevel3` string
      - `place` string
      - `name` string
      - `geoResolution` string
      - `geometry` object
        - `latitude` number, required
        - `longitude` number, required
    - `events` object[]: An event with name "confirmed" must be specified. Other event names include onsetSymptoms, firstClinicalConsultation, selfIsolation, hospitalAdmission, icuAdmission, and outcome.
      - `name` string
      - `dateRange` DateRange
        - `start` union
          - string
          - object
          - number
        - `end` union
          - string
          - object
          - number
      - `value` string
    - `symptoms` object
      - `status` string
      - `values` string[]
    - `preexistingConditions` object
      - `hasPreexistingConditions` boolean
      - `values` string[]
    - `transmission` object
      - `routes` string[]
      - `places` string[]
      - `linkedCaseIds` string[]
    - `travelHistory` object
      - `traveledPrior30Days` boolean
      - `travel` object[]
        - `dateRange` DateRange
          - `start` union
            - string
            - object
            - number
          - `end` union
            - string
            - object
            - number
        - `location` FuzzyLocation: A geo location that can be unspecific. It may not be geocoded if it lacks information.
          - `country` string: ISO-3166-2 code for a country.
          - `administrativeAreaLevel1` string: First administrative subdivision of a country
          - `administrativeAreaLevel2` string: Second administrative subdivision of a country
          - `administrativeAreaLevel3` string: Third administrative subdivision of a country
          - `place` string: Name of the place this location refers to
          - `name` string: Full name of the location
          - `geoResolution` 'undefined' | 'Point' | 'Admin3' | 'Admin2' | 'Admin1' | 'Country': How granular the location is
          - `geometry` object
            - `latitude` number
            - `longitude` number
        - `purpose` string
        - `methods` string[]
    - `variant` object
      - `name` string
    - `vaccines` Vaccine[]: A list of vaccines
      - `name` string: The name of the vaccine administered
      - `batch` string: The batch ID of the vaccine dose administered
      - `date` union
        - string
        - object
        - number
      - `sideEffects` SymptomArray
        - `symptoms` string[]
    - `genomeSequences` object[]
      - `sampleCollectionDate` union
        - string
        - object
        - number
      - `repositoryUrl` string
      - `sequenceId` string
      - `sequenceName` string
      - `sequenceLength` integer
    - `pathogens` object[]
      - `name` string
      - `id` integer
    - `revisionMetadata` object
      - `revisionNumber` integer, required
      - `creationMetadata` EditMetadata
        - `curator` string
        - `date` union
          - string
          - object
          - number
        - `notes` string
      - `editMetadata` EditMetadata
        - `curator` string
        - `date` union
          - string
          - object
          - number
        - `notes` string
    - `SGTF` 'NA' | '0' | '1'

## Response `200`

OK

- BatchUpsertCaseResponse: Response to batch upsert case API requests
  - `phase` 'GEOCODE' | 'VALIDATE' | 'UPSERT', required: The last operation completed by the server
  - `numCreated` number, required: The number of cases created by the request.
  - `numUpdated` number, required: The number of cases modified by the request. Note that this only includes cases that are actually modified by the batch upsert. If a case is included in the batch upsert request, but contains no changes compared to the currently stored case, it won't be counted.
  - `errors` object[], required
    - `index` integer, required: 0-based index of the case which triggered an error
    - `message` string, required: what went wrong

## Other responses

- `207`: Multi-status
- `422`: Unprocessable entity
- `500`: Internal server error

## Changes

- **2026-07-17** `886deae8a6f9`: 1 info
  - added the media type `application/json` for the response with the status `422`
- **2022-04-29** `e11f54229b64`: 2 warning
  - removed the request property `allOf[#/components/schemas/CaseArray]/cases/items/notes`
  - removed the request property `allOf[#/components/schemas/CaseArray]/cases/items/restrictedNotes`
- **2022-01-14** `1619bcaae2df`: 2 breaking, 2 warning
  - the `allOf[#/components/schemas/CaseArray]/cases/items/location/country` request property's minLength was increased from `0` to `2`
  - the `allOf[#/components/schemas/CaseArray]/cases/items/travelHistory/travel/items/location/country` request property's minLength was increased from `0` to `2`
  - the `allOf[#/components/schemas/CaseArray]/cases/items/location/country` request property's maxLength was set to `2`
  - the `allOf[#/components/schemas/CaseArray]/cases/items/travelHistory/travel/items/location/country` request property's maxLength was set to `2`
- **2022-01-06** `875e892119b9`: 1 info
  - added the new optional request property `allOf[#/components/schemas/CaseArray]/cases/items/SGTF`
- …earlier changes not shown

[Operation history](https://skmtc.dev/globaldothealth/apis/global-health-data-service/changes/cases/batchUpsert/post.md)

---

[API](https://skmtc.dev/globaldothealth/apis/global-health-data-service.md) - [All operations](https://skmtc.dev/globaldothealth/apis/global-health-data-service/llms.txt) - [OpenAPI document](https://skmtc.dev/globaldothealth/apis/global-health-data-service/revisions/886deae8a6f9?raw)