---
title: "Start a job to retrieve information about the patient"
method: POST
path: "/patient-history/jobs"
tags: ["Patient History Retrieval"]
---

# Start a job to retrieve information about the patient

`POST /patient-history/jobs`

This endpoint takes a reference for a patient that is stored in the FHIR server and starts a job that will asynchronously collect, parse and store on the server all documents that are related to this patient that are available on the external sources.

## Headers

- `Zus-Account` string, uuid — The Builder ID of another builder on whose behalf the caller is acting. This requires that the provider builder has a cross-builder grant allowing access to the caller.

## Request body

- union
  - RequestBodyWithProviderAttributes
    - `data` object, required
      - `type` string, required — Type name of the request.
      - `attributes` object
        - `targetDate` string, date-time — Possible formats: "2023-01-20", "2023-01-20T12:18:46.970516-08:00", "2023-01-20T12:18:46.970516Z".
        - `requestConsent` boolean — If set to true, indicates that the patient has consented to have their medical data retrieved by the provider.
        - `provider` JsonApiProvider — Required if the practitioner relation is not passed. Will appear on the response if passed in request body.
          - `npi` string, required — The NPI number of the user/organization making the request.
          - `role` string, required — The SNOMED CT value representing the role that the user/organization is playing when making the request.
          - `name` string, required — The user/organization who has a treatment relationship with the patient
        - `priority` boolean — When the priority field is set to true, the patient history job will run right away. When it is set to false, it will be queued to run as part of our batch process, which manages load on the data networks and is described [here](https://docs.zushealth.com/reference/get_patient-history-jobs-job-id). Developers should set the priority field to true for end-user requests, and to false when running large cohorts.
        - `chartBuildType` 'pro-ehr-pharmacy' | 'pro-ehr-only' | 'lite-ehr-pharmacy' | 'lite-ehr-only' — This field allows users to request a specific job type (pro-ehr-only, pro-ehr-pharmacy, lite-ehr-pharmacy or lite-ehr-only). It is only available to builders whose order forms have multiple chart build types. When omitted, the job will use the default type configured during implementation.
      - `relationships` JsonApiBaseRelationship, required
        - `patient` PatientRelation, required
          - `data` object, required
            - `type` string, required
            - `id` string, uuid, required — The FHIR ID of a Patient resource
  - RequestBodyWithPractitionerAttributes
    - `data` object, required
      - `type` string, required — Type name of the request.
      - `attributes` object
        - `targetDate` string, date-time — Possible formats: "2023-01-20", "2023-01-20T12:18:46.970516-08:00", "2023-01-20T12:18:46.970516Z".
        - `requestConsent` boolean — If set to true, indicates that the patient has consented to have their medical data retrieved by the provider.
        - `practitioner` JsonApiProvider — Required if the practitioner relation is not passed. Will appear on the response if passed in request body.
          - `npi` string, required — The NPI number of the user/organization making the request.
          - `role` string, required — The SNOMED CT value representing the role that the user/organization is playing when making the request.
          - `name` string, required — The user/organization who has a treatment relationship with the patient
        - `priority` boolean — When the priority field is set to true, the patient history job will run right away. When it is set to false, it will be queued to run as part of our batch process, which manages load on the data networks and is described [here](https://docs.zushealth.com/reference/get_patient-history-jobs-job-id). Developers should set the priority field to true for end-user requests, and to false when running large cohorts.
        - `chartBuildType` 'pro-ehr-pharmacy' | 'pro-ehr-only' | 'lite-ehr-pharmacy' | 'lite-ehr-only' — This field allows users to request a specific job type (pro-ehr-only, pro-ehr-pharmacy, lite-ehr-pharmacy or lite-ehr-only). It is only available to builders whose order forms have multiple chart build types. When omitted, the job will use the default type configured during implementation.
      - `relationships` JsonApiBaseRelationship, required
        - `patient` PatientRelation, required
          - `data` object, required
            - `type` string, required
            - `id` string, uuid, required — The FHIR ID of a Patient resource
  - RequestBodyWithPractitionerRelation
    - `data` object, required
      - `type` string, required — Type name of the request.
      - `attributes` object
        - `targetDate` string, date-time — Possible formats: "2023-01-20", "2023-01-20T12:18:46.970516-08:00", "2023-01-20T12:18:46.970516Z".
        - `requestConsent` boolean — If set to true, indicates that the patient has consented to have their medical data retrieved by the provider.
        - `priority` boolean — When the priority field is set to true, the patient history job will run right away. When it is set to false, it will be queued to run as part of our batch process, which manages load on the data networks and is described [here](https://docs.zushealth.com/reference/get_patient-history-jobs-job-id). Developers should set the priority field to true for end-user requests, and to false when running large cohorts.
        - `chartBuildType` 'pro-ehr-pharmacy' | 'pro-ehr-only' | 'lite-ehr-pharmacy' | 'lite-ehr-only' — This field allows users to request a specific job type (pro-ehr-only, pro-ehr-pharmacy, lite-ehr-pharmacy or lite-ehr-only). It is only available to builders whose order forms have multiple chart build types. When omitted, the job will use the default type configured during implementation.
      - `relationships` object, required
        - `patient` PatientRelation, required
          - `data` object, required
            - `type` string, required
            - `id` string, uuid, required — The FHIR ID of a Patient resource
        - `practitioner` PractitionerRelation, required
          - `data` object, required
            - `type` string, required
            - `id` string, uuid, required — The FHIR ID of a Practitioner resource.
  - RequestBodyWithOrganizationRelation
    - `data` object, required
      - `type` string, required — Type name of the request.
      - `attributes` object
        - `targetDate` string, date-time — Possible formats: "2023-01-20", "2023-01-20T12:18:46.970516-08:00", "2023-01-20T12:18:46.970516Z".
        - `requestConsent` boolean — If set to true, indicates that the patient has consented to have their medical data retrieved by the provider.
        - `priority` boolean — When the priority field is set to true, the patient history job will run right away. When it is set to false, it will be queued to run as part of our batch process, which manages load on the data networks and is described [here](https://docs.zushealth.com/reference/get_patient-history-jobs-job-id). Developers should set the priority field to true for end-user requests, and to false when running large cohorts.
        - `chartBuildType` 'pro-ehr-pharmacy' | 'pro-ehr-only' | 'lite-ehr-pharmacy' | 'lite-ehr-only' — This field allows users to request a specific job type (pro-ehr-only, pro-ehr-pharmacy, lite-ehr-pharmacy or lite-ehr-only). It is only available to builders whose order forms have multiple chart build types. When omitted, the job will use the default type configured during implementation.
      - `relationships` object, required
        - `patient` PatientRelation, required
          - `data` object, required
            - `type` string, required
            - `id` string, uuid, required — The FHIR ID of a Patient resource
        - `practitioner` OrganizationRelation
          - `data` object, required
            - `type` string, required
            - `id` string, uuid, required — The FHIR ID of a Organization resource

## Response `201`

Patient history retrieval job has been created.

- PostJobsResponse
  - `data` object, required
    - `type` string, required — Type name of the request.
    - `id` string, uuid, required — The ID of a patient history job.
    - `attributes` object, required
      - `targetDate` string, date-time — Possible formats: "2023-01-20", "2023-01-20T12:18:46.970516-08:00", "2023-01-20T12:18:46.970516Z".
      - `createdAt` string, required — The epoch string indicating creation/update time.
      - `jobStatus` string
      - `requestConsent` boolean, required — If set to true, indicates that the patient has consented to have their medical data retrieved by the provider.
      - `provider` JsonApiProvider — Required if the practitioner relation is not passed. Will appear on the response if passed in request body.
        - `npi` string, required — The NPI number of the user/organization making the request.
        - `role` string, required — The SNOMED CT value representing the role that the user/organization is playing when making the request.
        - `name` string, required — The user/organization who has a treatment relationship with the patient
      - `practitioner` JsonApiPractitioner — Required if the practitioner relation is not passed. Will appear on the response if passed in request body. Note: this field is deprecated, please use `provider` field.
        - `npi` string, required — The NPI number of the user/organization making the request. Note: this field is deprecated, pleasue use `provider` field.
        - `role` string, required — The SNOMED CT value representing the role that the user/organization is playing when making the request. Note: this field is deprecated, pleasue use `provider` field.
        - `name` string, required — The user/organization who has a treatment relationship with the patient. Note: this field is deprecated, pleasue use `provider` field.
    - `relationships` object, required
      - `patient` PatientRelation, required
        - `data` object, required
          - `type` string, required
          - `id` string, uuid, required — The FHIR ID of a Patient resource
      - `practitioner` PractitionerRelation
        - `data` object, required
          - `type` string, required
          - `id` string, uuid, required — The FHIR ID of a Practitioner resource.
      - `organization` OrganizationRelation
        - `data` object, required
          - `type` string, required
          - `id` string, uuid, required — The FHIR ID of a Organization resource

## Other responses

- `400` — Patient history retrieval job was not created because the request is invalid.
- `401` — Patient history retrieval job was not created because the request is not authorized.
- `404` — Patient history retrieval job was not created because the request referenced not existing resources.
- `405` — Patient history retrieval job was not created because the request did not provide the patient's consent.
- `429` — Patient history retrieval job was not created because the rate limit for a patient has been exceeded.
- `500` — Patient history retrieval job was not created because something went wrong.

---

[API](https://skmtc.net/zushealth/apis/auth-service-api.md) · [All operations](https://skmtc.net/zushealth/apis/auth-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zushealth/auth-service-api/revisions/ee03e3c0910d/schema)