{
    "openapi": "3.0.0",
    "info": {
         "title": "System of Record Agent API",
         "description": "The PCA System of Record Agent provides APIs that enable client systems to search for, or validate, data items that are included in service offerings where the publisher is **NOT** the authoritative source of those data items. Specifically these data items are the HI service, AHPRA, ABN and G-NAF (address) identifiers. <br><br> All these operations are formally specified using OpenAPI v3.0. <br><br> [Raw JSON](assets/pca-open-api.json)",
         "version": "2.0.0-alpha.1 [Draft]",
         "contact": {
              "name": "Australian Digital Health Agency",
              "email": "help@digitalhealth.gov.au"
         }
    },     
    "servers": [
        {
            "url": "https://pca-svt.digitalhealth.gov.au",
            "description": "Vendor testing server",
            "variables": {}
        },
        {
            "url": "https://pca.digitalhealth.gov.au",
            "description": "Production server",
            "variables": {}
        }
    ],
    "paths": {
        "/validation/addresslookup/autocomplete": {"get": {
            "tags": ["Address searching and validation"],
            "operationId": "AddressLookup_Autocomplete",
            "description": "This operation is used to search the [AddressFinder](https://addressfinder.com.au/) data stores to return a list of closely matching addresses which can then be selected from by the user. This operation is used together with the *AddressLookup_Info* operation which provides the metadata associated with a selected address. This metadata includes the G-NAF identifier.",
            "parameters": [
                {
                    "name": "address",
                    "in": "query",
                    "required": true,
                    "schema": {"type": "string"},
                    "example": "400 Queen Street",
                    "description": "The partial address to be searched for."
                }
            ],
            "responses": {
                "200": {
                    "description": "Success",
                    "content": {"application/json": {
                        "schema": {"$ref": "#/components/schemas/AddressLookupAutocompleteResponse"},
                        "example": {"completions": [
                            {
                                "id": "f8e25da8-9e4e-11e9-ba60-9d6146772544",
                                "full_address": "400 Queen Street, MELBOURNE VIC 3000"
                            },
                            {
                                "id": "f8878ed6-9e45-11e9-8a74-9d61b4bff50a",
                                "full_address": "400 Queen Street, BRISBANE CITY QLD 4000"
                            },
                            {
                                "id": "7e94f80c-9e59-11e9-a384-9d613267f4d4",
                                "full_address": "Level 1, 400 Queen Street, MELBOURNE VIC 3000"
                            },
                            {
                                "id": "7e950266-9e59-11e9-a384-9d613267f4d4",
                                "full_address": "Level 2, 400 Queen Street, MELBOURNE VIC 3000"
                            },
                            {
                                "id": "ed391554-9e45-11e9-816b-9d611f18abb8",
                                "full_address": "Shop 1, 400 Queen Street, BRISBANE CITY QLD 4000"
                            }
                        ]}
                    }}
                },
                "400": {"description": "Invalid request"},
                "401": {"description": "Not authorized"}
            },
            "security": [
                {"pca_api_oauth2": ["pca:SYS_RegisteredClient"]}
            ]
        }},
        "/validation/addresslookup/info": {"get": {
            "tags": ["Address searching and validation"],
            "operationId": "AddressLookup_Info",
            "description": "The AddressLookup_Info operation is used to query the [AddressFinder](https://addressfinder.com.au/) data stores to return the metadata associated with an identified address. This metadata includes the G-NAF identifier.",
            "parameters": [
                {
                    "name": "id",
                    "in": "query",
                    "required": true,
                    "schema": {"type": "string"},
                    "example": "f8878ed6-9e45-11e9-8a74-9d61b4bff50a",
                    "description": "The unique address id obtained from the *AddressLookup_Autocomplete* operation response."
                }
            ],
            "responses": {
                "200": {
                    "description": "Success",
                    "content": {"application/json": {
                        "schema": {"$ref": "#/components/schemas/AddressLookupMetadataResponse"},
                        "example": {
                            "id": "f8878ed6-9e45-11e9-8a74-9d61b4bff50a",
                            "address_line_1": "400 Queen Street",
                            "address_line_2": null,
                            "locality_name": "BRISBANE CITY",
                            "state_territory": "QLD",
                            "postcode": "4000",
                            "dpid": "91659008",
                            "gnaf_id": "GAQLD163222800"
                        }
                    }}
                },
                "400": {"description": "Invalid request"},
                "401": {"description": "Not authorized"}
            },
            "security": [
                {"pca_api_oauth2": ["pca:SYS_RegisteredClient"]}
            ]
        }},
        "/ahpra/search": {"get": {
            "tags": ["AHPRA registration searching and validation"],
            "operationId": "Ahpra_Search",
            "description": "This operation is used to search the [AHPRA register](https://www.ahpra.gov.au/) to return registration details of healthcare professionals.",
            "parameters": [
                {
                    "name": "familyName",
                    "in": "query",
                    "required": false,
                    "schema": {"type": "string"},
                    "example": "Smith",
                    "description": "The surname of the practitioner."
                },
                {
                    "name": "givenName",
                    "in": "query",
                    "required": false,
                    "schema": {"type": "string"},
                    "description": "The first name of the practitioner."
                },
                {
                    "name": "registrationNumber",
                    "in": "query",
                    "required": false,
                    "schema": {"type": "string"},
                    "description": "An AHPRA registration number for the practitioner."
                },
                {
                    "name": "healthProfession",
                    "in": "query",
                    "required": false,
                    "schema": {"type": "string"},
                    "description": "The AHPRA defined profession for the practitioner."
                },
                {
                    "name": "suburb",
                    "in": "query",
                    "required": false,
                    "schema": {"type": "string"},
                    "description": "The suburb of the principal place of practice for the practitioner."
                },
                {
                    "name": "postcode",
                    "in": "query",
                    "required": false,
                    "schema": {"type": "string"},
                    "description": "The postcode of the principal place of practice for the practitioner."
                },
                {
                    "name": "state",
                    "in": "query",
                    "required": false,
                    "schema": {"type": "string"},
                    "description": "The Australian State of the principal place of practice for the practitioner."
                }
            ],
            "responses": {
                "200": {
                    "description": "Success",
                    "content": {"application/json": {
                        "schema": {"$ref": "#/components/schemas/AhpraSearchResponseModel"},
                        "example": {
                            "maxResults": 50,
                            "providers": [
                                {
                                    "id": 1234567,
                                    "practitionerIdentifier": "12345678901234567890123456789012",
                                    "nameTitle": "Dr",
                                    "familyName": "Ellis",
                                    "givenName": "Gabrial ",
                                    "middleName": "",
                                    "professionNumber": "TES0000000001",
                                    "profession": "Medical Practitioner",
                                    "gender": "F",
                                    "created": "2019-01-00T15:54:19.3414206+10:00",
                                    "lastUpdated": null,
                                    "addresses": [
                                        {
                                            "id": 123123123,
                                            "suburb": "GREENSLOPES",
                                            "postcode": "4120",
                                            "state": "QLD"
                                        }
                                    ],
                                    "registrations": [
                                        {
                                            "id": 456456,
                                            "recordNumber": "003",
                                            "division": "",
                                            "registrationType": "Specialist",
                                            "registrationSubType": "",
                                            "registrationStatus": "Registered",
                                            "registrationSubStatus": "Current",
                                            "registrationExpiry": "2019-12-31",
                                            "specialtyName": "",
                                            "fieldOfSpecialty": "",
                                            "initialRegDate": "2000-01-01"
                                        },
                                        {
                                            "id": 678678,
                                            "recordNumber": "001",
                                            "division": "",
                                            "registrationType": "General",
                                            "registrationSubType": "",
                                            "registrationStatus": "Registered",
                                            "registrationSubStatus": "Current",
                                            "registrationExpiry": "2019-12-31",
                                            "specialtyName": "",
                                            "fieldOfSpecialty": "",
                                            "initialRegDate": "2000-01-01"
                                        }
                                    ],
                                    "qualifications": [
                                        {
                                            "id": 121212,
                                            "qualificationTitle": "Bachelor of Medicine / Bachelor of Surgery",
                                            "awardingInstitution": "XXXXX University",
                                            "countryQualificationObtained": "Australia",
                                            "yearOfQualification": "2000"
                                        },
                                        {
                                            "id": 232323,
                                            "qualificationTitle": "Fellowship of the Royal Australian College of General Practitioners",
                                            "awardingInstitution": "The Royal Australian College of General Practitioners",
                                            "countryQualificationObtained": "Australia",
                                            "yearOfQualification": "2017"
                                        }
                                    ]
                                }
                            ]
                        }
                    }}
                },
                "400": {"description": "Invalid request"},
                "401": {"description": "Not authorized"}
            },
            "security": [
                {"pca_api_oauth2": ["pca:SYS_RegisteredClient"]}
            ]
        }}
    },
    "components": {
        "schemas": {
            "AddressLookupAutocompleteResponse": {
                "type": "object",
                "properties": {"completions": {
                    "description": "This object is an array of possible matches for the partial address that was supplied as input to the *AddressLookup_Autocomplete* operation",
                    "uniqueItems": false,
                    "type": "array",
                    "items": {"$ref": "#/components/schemas/AddressLookupCompletions"}
                }}
            },
            "AddressLookupCompletions": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "A unique id for this full-address that must be provided as input to the  *AddressLookup_Info* operation to get the G-NAF id"
                    },
                    "full_address": {
                        "description": "A possible match for the partial address that was supplied as input to the *AddressLookup_Autocomplete* operation",
                        "type": "string"
                    }
                }
            },
            "AddressLookupMetadataResponse": {
                "type": "object",
                "properties": {
                    "id": {
                        "description": "The id provided as input.",
                        "type": "string"
                    },
                    "address_line_1": {"type": "string"},
                    "address_line_2": {"type": "string"},
                    "locality_name": {"type": "string"},
                    "state_territory": {"type": "string"},
                    "postcode": {"type": "string"},
                    "dpid": {
                        "description": "If present, represents the postal delivery point that corresponds to the address - not used in PCA Addresses",
                        "type": "string"
                    },
                    "gnaf_id": {
                        "description": "This G-NAF id **SHALL** be included in the PCA Address using the *pca-address-identifier-ext* extension.",
                        "type": "string"
                    }
                }
            },
            "AhpraSearchResponseModel": {
                "type": "object",
                "properties": {
                    "maxResults": {
                        "format": "int32",
                        "type": "integer",
                        "description": "The maximum number of results that PCA returns in response to this operation. This number will be greater than or equal to the actual number of results returned."
                    },
                    "providers": {
                        "uniqueItems": false,
                        "description": "An array of matching providers.",
                        "type": "array",
                        "items": {"$ref": "#/components/schemas/AhpraPractitionerModel"}
                    }
                }
            },
            "AhpraPractitionerModel": {
                "required": [
                    "nameTitle",
                    "familyName",
                    "givenName",
                    "professionNumber",
                    "profession",
                    "gender"
                ],
                "type": "object",
                "properties": {
                    "id": {
                        "format": "int32",
                        "type": "integer"
                    },
                    "practitionerIdentifier": {"type": "string"},
                    "nameTitle": {
                        "maxLength": 20,
                        "type": "string"
                    },
                    "familyName": {
                        "maxLength": 40,
                        "type": "string"
                    },
                    "givenName": {
                        "maxLength": 40,
                        "type": "string"
                    },
                    "middleName": {
                        "maxLength": 40,
                        "type": "string"
                    },
                    "professionNumber": {
                        "maxLength": 20,
                        "type": "string"
                    },
                    "profession": {
                        "maxLength": 80,
                        "type": "string"
                    },
                    "gender": {
                        "maxLength": 1,
                        "type": "string"
                    },
                    "created": {
                        "format": "date-time",
                        "type": "string"
                    },
                    "lastUpdated": {
                        "format": "date-time",
                        "type": "string"
                    },
                    "addresses": {
                        "uniqueItems": false,
                        "type": "array",
                        "items": {"$ref": "#/components/schemas/AhpraAddressModel"}
                    },
                    "registrations": {
                        "uniqueItems": false,
                        "type": "array",
                        "items": {"$ref": "#/components/schemas/AhpraRegistrationModel"}
                    },
                    "qualifications": {
                        "uniqueItems": false,
                        "type": "array",
                        "items": {"$ref": "#/components/schemas/AhpraQualificationModel"}
                    }
                }
            },
            "AhpraAddressModel": {
                "required": [
                    "suburb",
                    "postcode",
                    "state"
                ],
                "type": "object",
                "properties": {
                    "id": {
                        "format": "int32",
                        "type": "integer"
                    },
                    "suburb": {
                        "maxLength": 100,
                        "type": "string"
                    },
                    "postcode": {
                        "maxLength": 4,
                        "type": "string"
                    },
                    "state": {
                        "maxLength": 15,
                        "type": "string"
                    }
                }
            },
            "AhpraRegistrationModel": {
                "required": [
                    "recordNumber",
                    "registrationType",
                    "registrationStatus",
                    "registrationExpiry",
                    "initialRegDate"
                ],
                "type": "object",
                "properties": {
                    "id": {
                        "format": "int32",
                        "type": "integer"
                    },
                    "recordNumber": {
                        "maxLength": 3,
                        "type": "string"
                    },
                    "division": {
                        "maxLength": 40,
                        "type": "string"
                    },
                    "registrationType": {
                        "maxLength": 80,
                        "type": "string"
                    },
                    "registrationSubType": {
                        "maxLength": 80,
                        "type": "string"
                    },
                    "registrationStatus": {
                        "maxLength": 40,
                        "type": "string"
                    },
                    "registrationSubStatus": {
                        "maxLength": 40,
                        "type": "string"
                    },
                    "registrationExpiry": {
                        "maxLength": 10,
                        "type": "string"
                    },
                    "specialtyName": {
                        "maxLength": 100,
                        "type": "string"
                    },
                    "fieldOfSpecialty": {
                        "maxLength": 100,
                        "type": "string"
                    },
                    "initialRegDate": {
                        "maxLength": 10,
                        "type": "string"
                    }
                }
            },
            "AhpraQualificationModel": {
                "required": ["qualificationTitle"],
                "type": "object",
                "properties": {
                    "id": {
                        "format": "int32",
                        "type": "integer"
                    },
                    "qualificationTitle": {
                        "maxLength": 150,
                        "type": "string"
                    },
                    "awardingInstitution": {
                        "maxLength": 75,
                        "type": "string"
                    },
                    "countryQualificationObtained": {
                        "maxLength": 50,
                        "type": "string"
                    },
                    "yearOfQualification": {
                        "maxLength": 4,
                        "type": "string"
                    }
                }
            }
        },
        "securitySchemes": {"pca_api_oauth2": {
            "type": "oauth2",
            "flows": {"clientCredentials": {
                "tokenUrl": "/SraAuthApi/auth/token",
                "scopes": {"pca:SYS_RegisteredClient": "A registered client system"}
            }}
        }}
    }
}