openapi: 3.2.0
info:
  title: CDR Common Data Holder Customers API
  version: 1.36.0
  description: Specifications for common endpoints applicable to all data holders (except secondary data holders).
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  contact:
    name: Data Standards Body
    email: contact@dsb.gov.au
    url: https://dsb.gov.au/
servers:
- description: MTLS
  url: https://mtls.dh.example.com/cds-au/v1
tags:
- name: Data Holder Customers
  x-shortName: Customers
  description: Data Holder Customer endpoints
paths:
  /common/customer:
    get:
      tags:
      - Data Holder Customers
      summary: Get Customer
      description: 'Obtain basic information on the customer that has authorised the current session.


        <h3 id=''cdr-common-api_get-customer_conventions''>Conventions</h3>

        In the customer payloads there are conventions that are explained below.


        #### Given Names


        _firstName_ represents the first of a person''s given names.


        _middleNames_ represents a collection of given names if the person has more than one given name.


        Where a data holder holds a person''s given names as a single string in source systems, it may not possible in some situations to reliably split these given names into their component first and middle names. In these situations, data holders **MAY** use the _firstName_ field to return the single string of given names and an empty _middleNames_ array.


        For example, if a person''s given names are "John Paul Winston" and the Data Holder is unable to determine which is the first name, they can return `"firstName": "John Paul Winston"`.'
      operationId: getCustomer
      parameters:
      - $ref: '#/components/parameters/HeaderXV'
      - $ref: '#/components/parameters/HeaderXMinV'
      - $ref: '#/components/parameters/HeaderXFAPIInteractionId'
      - $ref: '#/components/parameters/HeaderXFAPIAuthDate'
      - $ref: '#/components/parameters/HeaderXFAPICustomerIPAddress'
      - $ref: '#/components/parameters/HeaderXCDSClientHeaders'
      responses:
        '200':
          $ref: '#/components/responses/GetCustomer200'
        '400':
          $ref: '#/components/responses/GetCustomer400'
        '406':
          $ref: '#/components/responses/GetCustomer406'
      x-scopes:
      - common:customer.basic:read
      x-version: '1'
  /common/customer/detail:
    get:
      tags:
      - Data Holder Customers
      summary: Get Customer Detail
      description: 'Obtain detailed information on the authorised customer within the current session.


        Obsolete versions: [v1](includes/obsolete/get-customer-detail-v1.html).'
      operationId: getCustomerDetail
      parameters:
      - $ref: '#/components/parameters/HeaderXV'
      - $ref: '#/components/parameters/HeaderXMinV'
      - $ref: '#/components/parameters/HeaderXFAPIInteractionId'
      - $ref: '#/components/parameters/HeaderXFAPIAuthDate'
      - $ref: '#/components/parameters/HeaderXFAPICustomerIPAddress'
      - $ref: '#/components/parameters/HeaderXCDSClientHeaders'
      responses:
        '200':
          $ref: '#/components/responses/GetCustomerDetail200'
        '400':
          $ref: '#/components/responses/GetCustomerDetail400'
        '406':
          $ref: '#/components/responses/GetCustomerDetail406'
      x-scopes:
      - common:customer.detail:read
      x-version: '2'
components:
  parameters:
    HeaderXFAPIInteractionId:
      name: x-fapi-interaction-id
      in: header
      description: An **[[RFC4122]](#nref-RFC4122)** UUID used as a correlation id. If provided, the data holder **MUST** play back this value in the _x-fapi-interaction-id_ response header. If not provided a **[[RFC4122]](#nref-RFC4122)** UUID value is required to be provided in the response header to track the interaction.
      schema:
        type: string
    HeaderXV:
      name: x-v
      in: header
      description: Version of the API endpoint requested by the client. Must be set to a positive integer. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If the value of [_x-min-v_](#request-headers) is equal to or higher than the value of [_x-v_](#request-headers) then the [_x-min-v_](#request-headers) header should be treated as absent. If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`. See [HTTP Headers](#request-headers).
      required: true
      schema:
        type: string
    HeaderXFAPICustomerIPAddress:
      name: x-fapi-customer-ip-address
      in: header
      description: The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls.
      schema:
        type: string
    HeaderXCDSClientHeaders:
      name: x-cds-client-headers
      in: header
      description: The customer's original standard http headers [Base64](#common-field-types) encoded, including the original User-Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls.
      schema:
        type: string
      x-conditional: true
      x-cds-type: Base64
    HeaderXFAPIAuthDate:
      name: x-fapi-auth-date
      in: header
      description: The time when the customer last logged in to the Data Recipient Software Product as described in **[[FAPI-1.0-Baseline]](#nref-FAPI-1-0-Baseline)**. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls.
      schema:
        type: string
      x-conditional: true
    HeaderXMinV:
      name: x-min-v
      in: header
      description: Minimum version of the API endpoint requested by the client. Must be set to a positive integer if provided. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`.
      schema:
        type: string
  schemas:
    CommonPerson:
      required:
      - lastName
      - middleNames
      type: object
      properties:
        lastUpdateTime:
          type: string
          description: The date and time that this record was last updated by the customer. If no update has occurred then this date should reflect the initial creation date for the data.
          x-cds-type: DateTimeString
        firstName:
          type: string
          description: For people with single names this field need not be present. The single name should be in the _lastName_ field. Where a data holder cannot determine first and middle names from a collection of given names, a single string representing all given names **MAY** be provided.
        lastName:
          type: string
          description: For people with single names, the single name should be in this field.
        middleNames:
          type: array
          description: Field is mandatory but array may be empty.
          items:
            type: string
        prefix:
          type: string
          description: Also known as title or salutation. The prefix to the name (e.g., Mr, Mrs, Ms, Miss, Sir, etc.)
        suffix:
          type: string
          description: Used for a trailing suffix to the name (e.g., Jr.)
        occupationCode:
          type: string
          description: Value is a valid **[[ANZSCO]](#iref-ANZSCO)** Standard Occupation classification code. If the occupation code held by the data holder is not one of the supported **[[ANZSCO]](#iref-ANZSCO)** versions, then it must not be supplied.
          x-cds-type: ExternalRef
        occupationCodeVersion:
          type: string
          description: The applicable **[[ANZSCO]](#iref-ANZSCO)** release version of the occupation code provided. Mandatory if an _occupationCode_ is supplied. If _occupationCode_ is supplied but _occupationCodeVersion_ is absent, default is `ANZSCO_1220.0_2013_V1.2`.
          default: ANZSCO_1220.0_2013_V1.2
          enum:
          - ANZSCO_1220.0_2006_V1.0
          - ANZSCO_1220.0_2006_V1.1
          - ANZSCO_1220.0_2013_V1.2
          - ANZSCO_1220.0_2013_V1.3
      x-conditional:
      - occupationCodeVersion
    CommonSimpleAddress:
      description: Required if _addressUType_ is set to `simple`.
      required:
      - addressLine1
      - city
      - state
      type: object
      properties:
        mailingName:
          type: string
          description: Name of the individual or business formatted for inclusion in an address used for physical mail.
        addressLine1:
          type: string
          description: First line of the standard address object.
        addressLine2:
          type: string
          description: Second line of the standard address object.
        addressLine3:
          type: string
          description: Third line of the standard address object.
        postcode:
          type: string
          description: Mandatory for Australian addresses.
        city:
          type: string
          description: Name of the city or locality.
        state:
          type: string
          description: Free text if the country is not Australia. If country is Australia then must be one of the values defined by the [State Type Abbreviation](https://auspost.com.au/content/dam/auspost_corp/media/documents/australia-post-data-guide.pdf) in the PAF file format. `NSW`, `QLD`, `VIC`, `NT`, `WA`, `SA`, `TAS`, `ACT`, `AAT`.
        country:
          type: string
          description: A valid [ISO 3166 Alpha-3](https://www.iso.org/iso-3166-country-codes.html) country code. Australia (`AUS`) is assumed if country is not present.
          default: AUS
          x-cds-type: ExternalRef
      x-conditional:
      - postcode
    CommonPhoneNumber:
      required:
      - fullNumber
      - number
      - purpose
      type: object
      properties:
        isPreferred:
          type: boolean
          description: May be `true` for one and only one entry to indicate the preferred phone number. Assumed to be `false` if not present.
          default: false
        purpose:
          type: string
          description: The purpose of the number as specified by the customer.
          enum:
          - HOME
          - INTERNATIONAL
          - MOBILE
          - OTHER
          - UNSPECIFIED
          - WORK
        countryCode:
          type: string
          description: If absent, assumed to be Australia (`+61`). The `+` should be included.
          default: '+61'
        areaCode:
          type: string
          description: Required for non Mobile Phones, if field is present and refers to Australian code - the leading `0` should be omitted.
        number:
          type: string
          description: The actual phone number, with leading zeros as appropriate.
        extension:
          type: string
          description: An extension number (if applicable).
        fullNumber:
          type: string
          description: Fully formatted phone number with country code, area code, number and extension incorporated. Formatted according to section 5.1.4. of **[[RFC3966]](#iref-RFC3966)**.
          x-cds-type: ExternalRef
      x-conditional:
      - areaCode
    CommonPhysicalAddress:
      required:
      - addressUType
      type: object
      properties:
        addressUType:
          type: string
          description: The type of address object present.
          enum:
          - paf
          - simple
        simple:
          $ref: '#/components/schemas/CommonSimpleAddress'
        paf:
          $ref: '#/components/schemas/CommonPAFAddress'
      x-conditional:
      - simple
      - paf
    Meta:
      type: object
    ResponseCommonCustomer:
      required:
      - data
      - links
      type: object
      properties:
        data:
          required:
          - customerUType
          type: object
          properties:
            customerUType:
              type: string
              description: The type of customer object that is present.
              enum:
              - organisation
              - person
            person:
              $ref: '#/components/schemas/CommonPerson'
            organisation:
              $ref: '#/components/schemas/CommonOrganisation'
          x-conditional:
          - person
          - organisation
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
    CommonPersonDetailV2:
      allOf:
      - $ref: '#/components/schemas/CommonPerson'
      - required:
        - emailAddresses
        - phoneNumbers
        - physicalAddresses
        type: object
        properties:
          phoneNumbers:
            type: array
            description: Array is mandatory but may be empty if no phone numbers are held.
            items:
              $ref: '#/components/schemas/CommonPhoneNumber'
          emailAddresses:
            type: array
            description: May be empty.
            items:
              $ref: '#/components/schemas/CommonEmailAddress'
          physicalAddresses:
            type: array
            description: Array is mandatory but may be empty if no valid addresses are held. One and only one address may have the purpose of `REGISTERED`. Zero or one, and no more than one, record may have the purpose of `MAIL`. If zero then the `REGISTERED` address is to be used for mail.
            items:
              $ref: '#/components/schemas/CommonPhysicalAddressWithPurpose'
    CommonPAFAddress:
      required:
      - localityName
      - postcode
      - state
      type: object
      properties:
        dpid:
          type: string
          description: Unique identifier for an address as defined by Australia Post. Also known as Delivery Point Identifier.
        thoroughfareNumber1:
          type: integer
          description: Thoroughfare number for a property (first number in a property ranged address).
          x-cds-type: PositiveInteger
        thoroughfareNumber1Suffix:
          type: string
          description: Suffix for the thoroughfare number. Only relevant if _thoroughfareNumber1_ is populated.
        thoroughfareNumber2:
          type: integer
          description: Second thoroughfare number (only used if the property has a ranged address e.g., 23-25).
          x-cds-type: PositiveInteger
        thoroughfareNumber2Suffix:
          type: string
          description: Suffix for the second thoroughfare number. Only relevant if _thoroughfareNumber2_ is populated.
        flatUnitType:
          type: string
          description: Type of flat or unit for the address.
        flatUnitNumber:
          type: string
          description: Unit number (including suffix, if applicable).
        floorLevelType:
          type: string
          description: Type of floor or level for the address.
        floorLevelNumber:
          type: string
          description: Floor or level number (including alpha characters).
        lotNumber:
          type: string
          description: Allotment number for the address.
        buildingName1:
          type: string
          description: Building/Property name 1.
        buildingName2:
          type: string
          description: Building/Property name 2.
        streetName:
          type: string
          description: The name of the street.
        streetType:
          type: string
          description: The street type. Valid enumeration defined by Australia Post PAF code file.
        streetSuffix:
          type: string
          description: The street type suffix. Valid enumeration defined by Australia Post PAF code file.
        postalDeliveryType:
          type: string
          description: Postal delivery type. (e.g., PO BOX). Valid enumeration defined by Australia Post PAF code file.
        postalDeliveryNumber:
          type: integer
          description: Postal delivery number if the address is a postal delivery type.
          x-cds-type: PositiveInteger
        postalDeliveryNumberPrefix:
          type: string
          description: Postal delivery number prefix related to the postal delivery number.
        postalDeliveryNumberSuffix:
          type: string
          description: Postal delivery number suffix related to the postal delivery number.
        localityName:
          type: string
          description: Full name of locality.
        postcode:
          type: string
          description: Postcode for the locality.
        state:
          type: string
          description: State in which the address belongs. Valid enumeration defined by Australia Post PAF code file [State Type Abbreviation](https://auspost.com.au/content/dam/auspost_corp/media/documents/australia-post-data-guide.pdf). `NSW`, `QLD`, `VIC`, `NT`, `WA`, `SA`, `TAS`, `ACT`, `AAT`.
      description: Australian address formatted according to the file format defined by the [PAF file format](https://auspost.com.au/content/dam/auspost_corp/media/documents/australia-post-data-guide.pdf). Required if _addressUType_ is set to `paf`.
    Links:
      required:
      - self
      type: object
      properties:
        self:
          type: string
          description: Fully qualified link that generated the current response document.
          x-cds-type: URIString
    CommonOrganisationDetailV2:
      allOf:
      - $ref: '#/components/schemas/CommonOrganisation'
      - required:
        - physicalAddresses
        type: object
        properties:
          physicalAddresses:
            type: array
            description: Array is mandatory but may be empty if no valid addresses are held. One and only one address may have the purpose of `REGISTERED`. Zero or one, and no more than one, record may have the purpose of `MAIL`. If zero then the `REGISTERED` address is to be used for mail.
            items:
              $ref: '#/components/schemas/CommonPhysicalAddressWithPurpose'
    CommonOrganisation:
      required:
      - agentLastName
      - agentRole
      - businessName
      - organisationType
      type: object
      properties:
        lastUpdateTime:
          type: string
          description: The date and time that this record was last updated by the customer. If no update has occurred then this date should reflect the initial creation date for the data.
          x-cds-type: DateTimeString
        agentFirstName:
          type: string
          description: The first name of the individual providing access on behalf of the organisation. For people with single names this field need not be present. The single name should be in the _lastName_ field.
        agentLastName:
          type: string
          description: The last name of the individual providing access on behalf of the organisation. For people with single names, the single name should be in this field.
        agentRole:
          type: string
          description: The role of the individual identified as the agent who is providing authorisation. Expected to be used for display. Default to "Unspecified" if the role is not known.
        businessName:
          type: string
          description: Name of the organisation.
        legalName:
          type: string
          description: Legal name, if different to the business name.
        shortName:
          type: string
          description: Short name used for communication, if different to the business name.
        abn:
          type: string
          description: Australian Business Number for the organisation.
        acn:
          type: string
          description: Australian Company Number for the organisation. Required only if an ACN is applicable for the organisation type.
        isACNCRegistered:
          type: boolean
          description: '`true` if registered with the ACNC. `false` if not. Absent or `null` if not confirmed.'
          default: null
        industryCode:
          type: string
          description: A valid [ANZSIC](http://www.abs.gov.au/ANZSIC) code for the organisation. If the industry code held by the data holder is not one of the supported [ANZSIC](http://www.abs.gov.au/ANZSIC) versions, then it must not be supplied.
          x-cds-type: ExternalRef
        industryCodeVersion:
          type: string
          description: The applicable [ANZSIC](http://www.abs.gov.au/ANZSIC) release version of the industry code provided. Should only be supplied if _industryCode_ is also supplied. If _industryCode_ is supplied but _industryCodeVersion_ is absent, default is `ANZSIC_1292.0_2006_V2.0`.
          default: ANZSIC_1292.0_2006_V2.0
          enum:
          - ANZSIC_1292.0_2006_V1.0
          - ANZSIC_1292.0_2006_V2.0
        organisationType:
          type: string
          description: Legal organisation type.
          enum:
          - COMPANY
          - GOVERNMENT_ENTITY
          - OTHER
          - PARTNERSHIP
          - SOLE_TRADER
          - TRUST
        registeredCountry:
          type: string
          description: Enumeration with values from [ISO 3166 Alpha-3](https://www.iso.org/iso-3166-country-codes.html) country codes. Assumed to be `AUS` if absent.
          default: AUS
          x-cds-type: ExternalRef
        establishmentDate:
          type: string
          description: The date the organisation described was established.
          x-cds-type: DateString
      x-conditional:
      - industryCodeVersion
    ResponseErrorListV2:
      type: object
      required:
      - errors
      properties:
        errors:
          description: List of errors.
          type: array
          items:
            $ref: '#/components/schemas/ErrorV2'
    CommonPhysicalAddressWithPurpose:
      allOf:
      - $ref: '#/components/schemas/CommonPhysicalAddress'
      - required:
        - purpose
        type: object
        properties:
          purpose:
            type: string
            description: Enumeration of values indicating the purpose of the physical address.
            enum:
            - MAIL
            - OTHER
            - PHYSICAL
            - REGISTERED
            - WORK
    ResponseCommonCustomerDetailV2:
      required:
      - data
      - links
      type: object
      properties:
        data:
          required:
          - customerUType
          type: object
          properties:
            customerUType:
              type: string
              description: The type of customer object that is present.
              enum:
              - organisation
              - person
            person:
              $ref: '#/components/schemas/CommonPersonDetailV2'
            organisation:
              $ref: '#/components/schemas/CommonOrganisationDetailV2'
          x-conditional:
          - person
          - organisation
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorV2:
      type: object
      required:
      - code
      - title
      - detail
      x-conditional:
      - meta
      properties:
        code:
          type: string
          description: The code of the error encountered. Where the error is specific to the respondent, an application-specific error code, expressed as a string value. If the error is application-specific, the URN code that the specific error extends must be provided in the _meta_ object. Otherwise, the value is the error code URN.
        title:
          type: string
          description: A short, human-readable summary of the problem that **MUST NOT** change from occurrence to occurrence of the problem represented by the error code.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        meta:
          type: object
          x-conditional:
          - urn
          description: Additional data for customised error codes.
          properties:
            urn:
              type: string
              description: The CDR error code URN which the application-specific error code extends. Mandatory if the error _code_ is an application-specific error rather than a standardised error code.
    CommonEmailAddress:
      required:
      - address
      - purpose
      type: object
      properties:
        isPreferred:
          type: boolean
          description: May be `true` for one and only one email record in the collection. Denotes the default email address.
        purpose:
          type: string
          description: The purpose for the email, as specified by the customer.
          enum:
          - HOME
          - OTHER
          - UNSPECIFIED
          - WORK
        address:
          type: string
          description: A correctly formatted email address, as defined by the addr-spec format in **[[RFC5322]](#nref-RFC5322)**.
          x-cds-type: ExternalRef
  headers:
    XV:
      description: The [payload version](#response-headers) that the endpoint has responded with.
      required: true
      schema:
        type: string
    XFAPIInteractionId:
      description: An **[[RFC4122]](#nref-RFC4122)** UUID used as a correlation id. If provided, the data holder **MUST** play back this value in the _x-fapi-interaction-id_ response header. If not provided a **[[RFC4122]](#nref-RFC4122)** UUID value is required to be provided in the response header to track the interaction.
      required: true
      schema:
        type: string
  responses:
    GetCustomer200:
      description: Successful response
      headers:
        x-v:
          $ref: '#/components/headers/XV'
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseCommonCustomer'
    GetCustomerDetail406:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[406 - Unsupported Version](#error-406-header-unsupported-version)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    GetCustomerDetail400:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[400 - Invalid Field](#error-400-field-invalid)</li><li>[400 - Missing Required Field](#error-400-field-missing)</li><li>[400 - Invalid Version](#error-400-header-invalid-version)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    GetCustomer406:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[406 - Unsupported Version](#error-406-header-unsupported-version)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    GetCustomer400:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[400 - Invalid Field](#error-400-field-invalid)</li><li>[400 - Missing Required Field](#error-400-field-missing)</li><li>[400 - Invalid Version](#error-400-header-invalid-version)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    GetCustomerDetail200:
      description: Successful response
      headers:
        x-v:
          $ref: '#/components/headers/XV'
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseCommonCustomerDetailV2'