> ## Documentation Index > Fetch the complete documentation index at: https://docs.parchment.health/llms.txt > Use this file to discover all available pages before exploring further. # IHI Precheck > Checks whether patient data resolves a valid IHI without creating the patient. Same search as Create Patient; the IHI number is never returned. ## Overview Checks whether patient data resolves a valid IHI **before** you create the patient. Send the same body as [Create Patient](/api-reference/endpoint/v1/create-patient). The precheck runs the same HI Service search as creation, creates nothing, and never returns the IHI number. Branch on `data.outcome`. Two flags answer the two common questions: * **`create_would_succeed`** — would an identical create request succeed right now? * **`ihi_check_passed`** — did the search resolve an `ACTIVE` + `VERIFIED` IHI (the prescribing bar)? Absent when no search ran. * **`message`** is a human-readable summary naming the identifier that matched. It is informational only. ## Outcomes | `outcome` | Meaning | `create_would_succeed` | `ihi_check_passed` | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ihi_found` | The HI Service returned an IHI for this patient. Read `ihi_status` and `ihi_record_status` to see whether it is usable. | `true` when `ihi_record_status` is `VERIFIED`. `false` when it is `PROVISIONAL` or `UNVERIFIED`: creation is rejected until the record is verified. | `true` when `ihi_status` is `ACTIVE` **and** `ihi_record_status` is `VERIFIED`. `false` otherwise, for example a `VERIFIED` record whose status is `DECEASED` or `EXPIRED`. | | `no_match` | Every identifier was tried; none matched. The patient is created without an IHI. | `true` | `false` | | `insufficient_data` | No identifier to search on. `search_paths` lists what would unlock each path. | `false`, or `true` for Medicare without `medicare_irn` | absent | | `already_exists` | A patient with this `partner_patient_id` exists. The live check still runs on the submitted data. Creation returns the existing patient. | `true` | live result, or absent if the check could not run | | `organization_not_ready` | The organization has no HPI-O. Contact Parchment. | `false` | absent | | `hi_service_error` | The HI Service is unreachable. Retry later. | `false` | absent | ## Search Paths Every identifier you supply is tried in priority order until one matches. An identifier that returns no record falls back to the next. Supply every identifier you hold. | Priority | Path | Requires | | -------- | --------------------------- | --------------------------------------- | | 1 | `ihi_number` | `ihi_number` | | 2 | `medicare` | `medicare_card_number` + `medicare_irn` | | 3 | `dva` | `dva_file_number` | | 4 | `mobile` | `phone` (Australian mobile) | | 5 | `email` | `email` | | 6 | `australian-street-address` | `australian_street_address` | | 7 | `international-address` | `international_address` | All paths also require `family_name`, `given_name`, `date_of_birth`, `sex`. `searched_path` is the identifier that matched (or the last one tried on `no_match`). `failed_paths` lists the identifiers tried before it. It is absent when the first identifier matched. ## Request Example ```json theme={null} { "partner_patient_id": "PMS-000123", "partner_id": "demo", "given_name": "Denice", "family_name": "SHEA", "date_of_birth": "1992-12-16", "sex": "F", "medicare_card_number": "6951907501", "medicare_irn": "1", "phone": "0417903853", "email": "919@Ausnet.com.au", "australian_street_address": { "street_number": "163", "street_name": "Law Rd", "suburb": "Jitarning", "state": "WA", "postcode": "6365" } } ``` ## Response Examples ### IHI Found (200) ```json theme={null} { "success": true, "statusCode": 200, "message": "IHI found using Medicare number", "code": "SUCCESS", "data": { "outcome": "ihi_found", "create_would_succeed": true, "ihi_check_passed": true, "searched_path": "medicare", "ihi_status": "ACTIVE", "ihi_record_status": "VERIFIED" }, "timestamp": "2024-01-15T10:30:00.000Z", "requestId": "req_1705312200000_abc123" } ``` ### IHI Found After Fallback (200) ```json theme={null} { "success": true, "statusCode": 200, "message": "IHI found using mobile number (no record found using Medicare number)", "code": "SUCCESS", "data": { "outcome": "ihi_found", "create_would_succeed": true, "ihi_check_passed": true, "searched_path": "mobile", "failed_paths": ["medicare"], "ihi_status": "ACTIVE", "ihi_record_status": "VERIFIED" }, "timestamp": "2024-01-15T10:30:00.000Z", "requestId": "req_1705312200000_abc123" } ``` ### No Match (200) ```json theme={null} { "success": true, "statusCode": 200, "message": "No IHI found using Medicare number, mobile number, Australian address", "code": "SUCCESS", "data": { "outcome": "no_match", "create_would_succeed": true, "ihi_check_passed": false, "searched_path": "australian-street-address", "failed_paths": ["medicare", "mobile"] }, "timestamp": "2024-01-15T10:30:00.000Z", "requestId": "req_1705312200000_abc123" } ``` ### Insufficient Data (200) ```json theme={null} { "success": true, "statusCode": 200, "message": "Not enough identifiers to run an IHI search", "code": "SUCCESS", "data": { "outcome": "insufficient_data", "create_would_succeed": false, "search_paths": [ { "path": "ihi_number", "missing": ["ihi_number"] }, { "path": "medicare", "missing": ["medicare_card_number", "medicare_irn"] }, { "path": "dva", "missing": ["dva_file_number"] }, { "path": "mobile", "missing": ["phone"] }, { "path": "email", "missing": ["email"] }, { "path": "australian-street-address", "missing": ["australian_street_address"] }, { "path": "international-address", "missing": ["international_address"] } ] }, "timestamp": "2024-01-15T10:30:00.000Z", "requestId": "req_1705312200000_abc123" } ``` ### Patient Already Exists (200) ```json theme={null} { "success": true, "statusCode": 200, "message": "Patient already exists; IHI check did not pass using Medicare number", "code": "SUCCESS", "data": { "outcome": "already_exists", "create_would_succeed": true, "ihi_check_passed": false, "searched_path": "medicare", "parchment_patient_id": "pat_abc123def456", "has_ihi": false }, "timestamp": "2024-01-15T10:30:00.000Z", "requestId": "req_1705312200000_abc123" } ``` ### Validation Error (422) Schema and identifier-format failures (Medicare checksum, IHI check digit, mobile, email, future date of birth) are reported together: ```json theme={null} { "success": false, "statusCode": 422, "error": { "type": "https://parchment.health/errors/validation-error", "title": "Validation failed", "detail": "There were some problems with your input.", "validation": [ { "field": "email", "message": "Invalid email address", "code": "VALIDATION_ERROR" }, { "field": "medicare_card_number", "message": "Invalid Medicare number", "code": "VALIDATION_ERROR" } ] }, "timestamp": "2024-01-15T10:30:00.000Z", "requestId": "req_1705312200000_abc123" } ``` ## Response Fields | Field | Type | Description | | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `outcome` | string | `ihi_found`, `no_match`, `insufficient_data`, `already_exists`, `organization_not_ready`, `hi_service_error` | | `create_would_succeed` | boolean | Whether an identical create request would succeed now | | `ihi_check_passed` | boolean | `true` only for an `ACTIVE` + `VERIFIED` IHI. Absent when no search ran | | `searched_path` | string | Identifier that matched, or the last one tried on `no_match` | | `failed_paths` | array | Identifiers tried before `searched_path`. Absent when the first matched | | `ihi_status` | string | `ACTIVE`, `DECEASED`, `RETIRED`, `EXPIRED`, `RESOLVED`, `UNKNOWN` | | `ihi_record_status` | string | `VERIFIED`, `UNVERIFIED`, `PROVISIONAL`, `UNKNOWN` | | `has_ihi` | boolean | `already_exists` only: the stored record holds an IHI | | `parchment_patient_id` | string | `already_exists` only | | `search_paths` | array | `insufficient_data` only: fields that would unlock each path | ## Status Codes | Code | Meaning | | ---- | ------------------------------------------------- | | 200 | Precheck completed — read `data.outcome` | | 401 | Authentication failed | | 409 | Multiple patients share this `partner_patient_id` | | 422 | Validation failed — see `error.validation` | | 500 | Unexpected server error | ## Notes * Requires the `create:patient` scope. * The IHI number is never returned. Create the patient to have Parchment store it. * Medicare without `medicare_irn` as the only identifier reports `insufficient_data`. ## OpenAPI ````yaml POST /v1/organizations/{organization_id}/users/{user_id}/patients/ihi-precheck openapi: 3.0.1 info: title: Parchment APIs description: >- Parchments API documentation for partner integrations, enabling secure e-prescription services license: name: MIT version: 1.0.0 servers: - url: https://api.sandbox.parchmenthealth.io/external - url: https://api.parchmenthealth.io/external security: - bearerAuth: [] paths: /v1/organizations/{organization_id}/users/{user_id}/patients/ihi-precheck: post: summary: IHI Precheck description: >- Checks whether patient data resolves a valid IHI without creating the patient. Same search as Create Patient; the IHI number is never returned. parameters: - name: x-organization-secret in: header required: true description: Organization secret for authentication - provided by Parchment schema: type: string - name: organization_id in: path required: true description: Organization ID schema: type: string format: uuid - name: user_id in: path required: true description: User ID schema: type: string format: uuid requestBody: description: Same body as Create Patient. Supply every identifier you hold. content: application/json: schema: $ref: '#/components/schemas/NewPatient' example: partner_patient_id: PMS-000123 partner_id: demo given_name: Denice family_name: SHEA date_of_birth: '1992-12-16' sex: F medicare_card_number: '6951907501' medicare_irn: '1' phone: '0417903853' email: 919@Ausnet.com.au australian_street_address: street_number: '163' street_name: Law Rd suburb: Jitarning state: WA postcode: '6365' required: true responses: '200': description: Precheck completed - read data.outcome for the result content: application/json: schema: $ref: '#/components/schemas/IHIPrecheckResponse' examples: ihi_found: summary: A verified IHI matched the supplied details value: success: true statusCode: 200 message: IHI found using Medicare number code: SUCCESS data: outcome: ihi_found create_would_succeed: true ihi_check_passed: true searched_path: medicare ihi_status: ACTIVE ihi_record_status: VERIFIED timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_abc123 no_match: summary: >- The search ran but no IHI resolved - creation would still succeed, without an IHI value: success: true statusCode: 200 message: No IHI found using Medicare number code: SUCCESS data: outcome: no_match create_would_succeed: true ihi_check_passed: false searched_path: medicare timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_abc123 insufficient_data: summary: >- No search path can run - each entry lists the fields that would unlock it value: success: true statusCode: 200 message: Not enough identifiers to run an IHI search code: SUCCESS data: outcome: insufficient_data create_would_succeed: false search_paths: - path: ihi_number missing: - ihi_number - path: medicare missing: - medicare_card_number - medicare_irn - path: dva missing: - dva_file_number - path: mobile missing: - phone - path: email missing: - email - path: australian-street-address missing: - australian_street_address - path: international-address missing: - international_address timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_abc123 already_exists: summary: >- A patient with this partner_patient_id already exists - the live IHI check still runs and is reported value: success: true statusCode: 200 message: >- Patient already exists; IHI check did not pass using Medicare number code: SUCCESS data: outcome: already_exists create_would_succeed: true ihi_check_passed: false searched_path: medicare parchment_patient_id: pat_abc123def456 has_ihi: false timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_abc123 organization_not_ready: summary: >- The organization has no HPI-O configured, so no IHI search is possible - contact Parchment value: success: true statusCode: 200 message: Organization has no HPI-O; an IHI search cannot run code: SUCCESS data: outcome: organization_not_ready create_would_succeed: false timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_abc123 hi_service_error: summary: The HI Service could not be reached - retry later value: success: true statusCode: 200 message: HI Service unavailable; the IHI search could not complete code: SUCCESS data: outcome: hi_service_error create_would_succeed: false searched_path: medicare timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_abc123 '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false statusCode: 401 error: type: https://parchment.health/errors/authentication-required title: Authentication required detail: Invalid client credentials timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_abc123 '409': description: Multiple patients already share this partner_patient_id content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false statusCode: 409 error: type: https://parchment.health/errors/resource-conflict title: Conflict detail: Patient already exists timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_abc123 '422': description: >- Validation failed - includes schema failures and identifier format/checksum failures (Medicare checksum, IHI check digit) content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false statusCode: 422 error: type: https://parchment.health/errors/validation-error title: Validation failed detail: There were some problems with your input. validation: - field: medicare_card_number message: Invalid Medicare number code: VALIDATION_ERROR timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_abc123 components: schemas: NewPatient: type: object description: Patient information to be created required: - family_name - given_name - date_of_birth - sex - partner_patient_id - partner_id properties: dva_file_number: type: string description: DVA file number ihi_number: type: string description: >- 16-digit Individual Healthcare Identifier (IHI). If omitted, Parchment will attempt to fetch it from the HI Service. medicare_card_number: type: string description: Medicare card number medicare_irn: type: string description: Medicare IRN given_name: type: string description: Patient's given name family_name: type: string description: Patient's family name date_of_birth: type: string format: date description: Patient's date of birth in YYYY-MM-DD format sex: $ref: '#/components/schemas/Sex' email: type: string format: email description: Patient's email address (optional) phone: type: string description: >- Patient's Australian mobile number (optional). Must be a valid Australian mobile (04xxxxxxxx or 05xxxxxxxx), digits only. International format with +61 or 61 prefix is also accepted. Landlines are rejected. A mobile number can be used for IHI lookup against the Healthcare Identifiers Service. australian_street_address: $ref: '#/components/schemas/australian_street_address' australian_address: description: Alias of australian_street_address. Send one, not both. allOf: - $ref: '#/components/schemas/australian_street_address' medicare_valid_to: type: string format: date description: Medicare card expiry date concession_pension_number: type: string description: Concession or pension number entitlement_number: type: string description: Entitlement number dva_card_color: $ref: '#/components/schemas/DVA_COLOR' racf_id: type: string description: RACF identifier ctg_eligible: type: boolean description: Closing the Gap eligibility indigenous_type: $ref: '#/components/schemas/IndigenousType' partner_patient_id: type: string description: Partner's unique identifier for the patient partner_id: type: string example: demo description: >- Your Parchment-assigned partner identifier (lowercase slug, e.g. 'tacklit'). Parchment registers this value during partner onboarding — requests with an unregistered value are rejected with a 422 validation error. Contact Parchment before go-live to have your identifier registered. IHIPrecheckResponse: type: object required: - success - statusCode - message - code - data - timestamp - requestId properties: success: type: boolean description: Always true for a completed precheck example: true statusCode: type: integer description: HTTP status code example: 200 message: type: string description: >- Human-readable summary naming the matched identifier. Informational only. example: >- IHI found using mobile number (no record found using Medicare number) code: type: string description: Always SUCCESS. Branch on data.outcome instead. enum: - SUCCESS example: SUCCESS data: $ref: '#/components/schemas/IHIPrecheckData' timestamp: type: string format: date-time description: ISO 8601 timestamp of the response example: '2024-01-15T10:30:00.000Z' requestId: type: string description: Unique identifier for request tracing example: req_1705312200000_abc123 Error: $ref: '#/components/schemas/ExternalApiErrorResponse' Sex: type: string enum: - M - F - 'N' - I description: Patient's sex australian_street_address: type: object required: - street_number - street_name - suburb - state - postcode properties: street_number: type: string description: Street number street_name: type: string description: Street name suburb: type: string description: Suburb state: $ref: '#/components/schemas/AU_STATE' postcode: type: string description: Australian postcode (4 digits) DVA_COLOR: type: string enum: - gold - white - orange description: DVA card color IndigenousType: type: string enum: - aboriginal - torres_strait_islander - both - neither - not_stated description: Patient's indigenous status IHIPrecheckData: type: object description: Codified IHI precheck result. The IHI number itself is never returned. required: - outcome - create_would_succeed properties: outcome: type: string description: >- The precheck result. ihi_found: a live HI Service search matched an IHI. no_match: the search ran but no IHI resolved (creation still succeeds, without an IHI). insufficient_data: no search path can run with the supplied fields. already_exists: a patient with this partner_patient_id already exists for the organization. organization_not_ready: the organization has no HPI-O configured. hi_service_error: the HI Service could not be reached. enum: - ihi_found - no_match - insufficient_data - already_exists - organization_not_ready - hi_service_error create_would_succeed: type: boolean description: >- Whether an identical create request would succeed now. True for already_exists and no_match; false for PROVISIONAL/UNVERIFIED records, organization_not_ready, hi_service_error and insufficient_data without any identifier. ihi_check_passed: type: boolean description: True only for an ACTIVE + VERIFIED IHI. Absent when no search ran. searched_path: type: string description: >- Identifier that matched, or the last one tried on no_match. Identifiers are tried in priority order: IHI, Medicare, DVA, mobile, email, Australian address, international address. enum: - ihi_number - medicare - dva - mobile - email - australian-street-address - international-address failed_paths: type: array description: >- Identifiers tried before searched_path. Absent when the first matched. items: type: string enum: - ihi_number - medicare - dva - mobile - email - australian-street-address - international-address ihi_status: type: string description: IHI number status, when known enum: - ACTIVE - DECEASED - RETIRED - EXPIRED - RESOLVED - UNKNOWN ihi_record_status: type: string description: IHI record status, when known enum: - VERIFIED - UNVERIFIED - PROVISIONAL - UNKNOWN has_ihi: type: boolean description: 'already_exists only: whether the stored patient holds an IHI' parchment_patient_id: type: string description: 'already_exists only: the Parchment patient ID' search_paths: type: array description: >- insufficient_data only: per-path list of the request fields that would unlock each search path items: type: object properties: path: type: string enum: - ihi_number - medicare - dva - mobile - email - australian-street-address - international-address missing: type: array items: type: string ExternalApiErrorResponse: type: object required: - success - statusCode - error - timestamp - requestId properties: success: type: boolean description: Indicates if the request was successful example: false statusCode: type: integer description: HTTP status code example: 400 code: type: string description: Machine-readable operation code identifying the error example: RESOURCE_NOT_FOUND error: type: object description: RFC 7807 compliant error details required: - type - title - detail properties: type: type: string format: uri description: URI identifying the problem type example: https://parchment.health/errors/validation-error title: type: string description: Human-readable summary of the problem example: Validation failed detail: type: string description: Human-readable explanation of the problem example: There were some problems with your input. instance: type: string format: uri description: URI reference to the specific occurrence example: /patients/123 validation: type: array description: Field-level validation errors (for 422 responses) items: type: object properties: field: type: string description: Field name that failed validation message: type: string description: Validation error message code: type: string description: Error code for programmatic handling timestamp: type: string format: date-time description: ISO 8601 timestamp of the response example: '2024-01-15T10:30:00.000Z' requestId: type: string description: Unique identifier for request tracing example: req_1705312200000_def456 meta: type: object description: Additional response metadata properties: apiVersion: type: string description: API version used example: '1.0' AU_STATE: type: string enum: - NSW - VIC - QLD - WA - SA - TAS - ACT - NT description: Australian state or territory securitySchemes: bearerAuth: type: http scheme: bearer ````