identity.yml

openapi: 3.0.1
info:
  title: Identity
  description: All included utility endpoints for Basiq partners
  version: 3.0.0
  termsOfService: 'https://docs.basiq.io/en/collections/440849-privacy-terms-and-common-questions'
  license: 
    name: Basiq
    url: https://basiq.io   
servers:
  - url: https://au-api.basiq.io
paths:
  /users/{userId}/identities:
    get:
      tags:
      - Identities
      summary: Retrieve identities
      description: Returns a list with a data property that contains an array of user
        identities. Each entry in the array is a separate object. If no data is returned,
        the resulting array will be empty.
      operationId: getUserIdentities
      parameters:
      - name: userId
        in: path
        description: User identifier.
        required: true
        schema:
          type: string
      responses:
        200:
          description: Returns list of identities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentitiesGetResponseResource'
              examples:
                person:
                  summary: Person Identity Response
                  value:
                    type: "list"
                    count: 1
                    data:
                      - type: "identity"
                        id: "q5c62a43-9725-4w4e-bdte-99571aa8c5cb"
                        created: "2024-06-19T10:38:31.152930692Z"
                        updated: "2024-06-19T10:38:31.152930692Z"
                        source: "openbanking"
                        connectionID: "f8c13t7a-ta01-7ec5-b89b-7b96a0ac8305"
                        institutionID: "AU00401"
                        fullName: "John Doe"
                        firstName: "John"
                        lastName: "Doe"
                        middleName: "James"
                        title: "Mr."
                        DOB: "1985-05-25"
                        occupationCode: "12345"
                        occupationCodeVersion: "V1.2"
                        phoneNumbers:
                          - "+6411222333"
                        emailAddresses:
                          - "john.doe@example.com"
                        physicalAddresses:
                          - type: "home"
                            addressLine1: "OAK STREET NSW 2099"
                            postcode: "2099"
                            city: "Northern Beaches Council"
                            state: "New South Wales"
                            country: "Australia"
                            countryCode: "AU"
                            formattedAddress: "OAK STREET NSW 2099, NSW 2099, Australia"
                        organisation:
                          agentFirstName: ""
                          agentLastName: ""
                          agentRole: ""
                          businessName: ""
                          legalName: ""
                          shortName: ""
                          abn: ""
                          acn: ""
                          isACNCRegistered: false
                          industryCode: ""
                          industryCodeVersion: ""
                          organisationType: ""
                          registeredCountry: ""
                        links:
                          self: "https://au-api.basiq.io/users/ea0acf2b-b816-4255-9c9c-72207a0bf836/identities/q5c62a43-9725-4w4e-bdte-99571aa8c5cb"
                          job: "https://au-api.basiq.io/users/ea0acf2b-b816-4255-9c9c-72207a0bf836/connection/f8c13t7a-ta01-7ec5-b89b-7b96a0ac8305"
                organisation:
                  summary: Organisation Identity Response
                  value:
                    type: "list"
                    count: 1
                    data:
                      - type: "identity"
                        id: "1de2bc64-a067-4r34-9he4-14986693fc03"
                        created: "2024-06-19T10:38:31.152930692Z"
                        updated: "2024-06-19T10:38:31.152930692Z"
                        source: "openbanking"
                        connectionID: "8d02bc04-a067-4d34-9fe4-14926683fa03"
                        institutionID: "AU00401"
                        fullName: ""
                        firstName: ""
                        lastName: ""
                        middleName: ""
                        title: ""
                        DOB: ""
                        occupationCode: ""
                        occupationCodeVersion: ""
                        phoneNumbers: []
                        emailAddresses: []
                        physicalAddresses: []
                        organisation:
                          agentFirstName: "Jane"
                          agentLastName: "Smith"
                          agentRole: "Nominated Representative"
                          businessName: "ABC Pty Ltd"
                          legalName: "ABC Pty Limited"
                          shortName: "ABC"
                          abn: "123456789"
                          acn: "987654321"
                          isACNCRegistered: true
                          industryCode: "67890"
                          industryCodeVersion: "V2.0"
                          organisationType: "COMPANY"
                          registeredCountry: "AUS"
                        links:
                          self: "https://au-api.basiq.io/users/ta0ycf2u-b516-4235-9f9c-71207a0vf836/identities/1de2bc64-a067-4r34-9he4-14986693fc03"
                          job: "https://au-api.basiq.io/users/ta0ycf2u-b516-4235-9f9c-71207a0vf836/connection/8d02bc04-a067-4d34-9fe4-14926683fa03"

                
        400:
          description: Returns error that server cannot or will not process the request
            due to something that is perceived to be a client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
              examples:
                    Bad Request:
                     value:
                      type: list
                      correlationId: ac5ah5i
                      data:
                        - type: error
                          title: Parameter not valid.
                          code: parameter-not-valid
                          detail: ID value is not valid.
                          source:
                            parameter: id
                    Invalid Filters:
                      value:
                        type: list
                        correlationId: ac5ah55
                        data:
                          - type: error
                            code: parameter-not-valid
                            title: Parameter value is not valid
                            detail: The provided filter parameter is in invalid format or unsupported
                            source:
                              parameter: filter
        403:
          description: Error that access is forbidden and tied to the application
            logic, such as insufficient rights to a resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenAccessError'
        500:
          description: Returns error response code indicates that the server encountered
            an unexpected condition that prevented it from fulfilling the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      security:
      - services_token: []
  /users/{userId}/identities/{identityId}:
    get:
      tags:
      - Identities
      summary: Retrieve an identity
      description: Returns a specific identity object.
      operationId: getUserIdentity
      parameters:
      - name: userId
        in: path
        description: User identifier.
        required: true
        schema:
          type: string
      - name: identityId
        in: path
        description: Identity identifier.
        required: true
        schema:
          type: string
      responses:
        200:
          description: Returns identity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityData'
        400:
          description: Returns error that server cannot or will not process the request
            due to something that is perceived to be a client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        403:
          description: Error that access is forbidden and tied to the application
            logic, such as insufficient rights to a resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenAccessError'
        404:
          description: Returns error indicating that server can't find requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        500:
          description: Returns error response code indicates that the server encountered
            an unexpected condition that prevented it from fulfilling the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      security:
      - services_token: []
components:
  schemas:
    BadRequestError:
      required:
        - correlationId
        - data
        - type
      type: object
      properties:
        type:
          type: string
          description: Always "list".
          example: list
        correlationId:
          type: string
          description: Unique identifier for this particular occurrence of the problem.
          example: ac5ah5i
        data:
          type: array
          description: Error data.
          items:
            required:
              - code
              - type
            type: object
            properties:
              type:
                type: string
                description: Type of the response, always "error"
                example: error
              title:
                type: string
                description: Title of the error
                example: Parameter not valid.
              code:
                type: string
                description: Application-specific error code, expressed as a string value.
                example: parameter-not-valid
                enum:
                  - parameter-not-supplied
                  - parameter-not-valid
                  - unsupported-accept
                  - invalid-content
                  - institution-not-supported
                  - invalid-credentials
              detail:
                type: string
                description: >-
                  Human-readable explanation specific to this occurrence of the
                  problem.
                example: ID value is not valid.
              source:
                $ref: '#/components/schemas/Source'
    IdentitiesGetResponseResource:
      title: IdentitiesGetResponseResource
      required:
      - count
      - data
      - type
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/IdentityData'
        type:
          type: string
          description: Type, always "list".
          example: list
        count:
          type: integer
          description: Count of the identities in the response.
          format: int64
          example: 100
      description: Object containing details for identities.
    IdentityData:
      required:
      - created
      - id
      - links
      - type
      - updated
      type: object
      properties:
        type:
          type: string
          description: Type, always "identity".
          example: identity
        id:
          type: string
          description: Identity identification.
          example: "61723"
        created:
          type: string
          description: Created date of the identity.
          example: 2019-07-29T07:34:09Z
        updated:
          type: string
          description: Created date of the identity.
          example: 2019-07-29T07:34:09Z
        connectionID:
          type: string
          description: ID of that connection. 
          example: 8d02bc04-a067-4d34-9fe4-14926683fa03
        institutionID:
          type: string
          description: ID of that institution. 
          example: AU04301
        source:
          type: string
          description: Data source.
          example: web
        fullName:
          type: string
          description: FullName of the identity owner.
          example: "John Doe"
        firstName:
          type: string
          description: FirstName of the identity owner.
          example: "John"
        lastName:
          type: string
          description: LastName of the identity owner.
          example: "Doe"
        middleName:
          type: string
          description: MiddleName of the identity owner.
          example: "James"
        title:
          type: string
          description: Title is the prefix to the name of the identity owner.
          example: "Mr."
        DOB:
          type: string
          description: Date of birth of the identity owner.
          example: "1985-05-25"
        occupationCode:
          type: string
          description: Code relating to the occupation held by the identity owner.
          example: "12345"
        occupationCodeVersion:
          type: string
          description: Occupation Code Version.
          example: "v1"
        phoneNumbers:
          type: array
          description: List of phone numbers of the identity owner.
          items:
            type: string
            example: "+6411222333"
        emailAddresses:
          type: array
          description: List of email addresses of the identity owner.
          items:
            type: string
            example: "john.doe@example.com"
        physicalAddresses:
          type: array
          description: List of physical addresses of the identity owner.
          items:
            $ref: '#/components/schemas/PhysicalAddressData'
        organisation:
          type: object
          properties:
            agentFirstName:
              type: string
              description: Agent first name.
              example: "Jane"
            agentLastName:
              type: string
              description: Agent last name.
              example: "Smith"
            agentRole:
              type: string
              description: Agent role.
              example: "Manager"
            businessName:
              type: string
              description: Business name.
              example: "ABC Corp"
            legalName:
              type: string
              description: Legal name.
              example: "ABC Corporation"
            shortName:
              type: string
              description: Short name.
              example: "ABC"
            abn:
              type: string
              description: Australian Business Number.
              example: "123456789"
            acn:
              type: string
              description: Australian Company Number.
              example: "987654321"
            isACNCRegistered:
              type: boolean
              description: Indicates whether is Australian Company Number registered.
              example: true
            industryCode:
              type: string
              description: Industry Code.
              example: "67890"
            industryCodeVersion:
              type: string
              description: Industry Code Version.
              example: "v2"
            organisationType:
              type: string
              description: Organisation Type.
              example: "Corporation"
            registeredCountry:
              type: string
              description: Registered Country.
              example: "Australia"
          description: Organisation data.
        links:
          $ref: '#/components/schemas/IdentityLinks'
    PhysicalAddressData:
      type: object
      properties:
        type:
          type: string
          description: Physical Address Type.
          example: home
        addressLine1:
          type: string
          description: AddressLine1.
          example: 123 Main St
        addressLine2:
          type: string
          description: AddressLine2.
          example: Apt 101
        addressLine3:
          type: string
          description: AddressLine3.
          example: ""
        postcode:
          type: string
          description: Postcode.
          example: "3000"
        city:
          type: string
          description: City.
          example: "Melbourne"
        state:
          type: string
          description: State.
          example: "VIC"
        country:
          type: string
          description: Country.
          example: "Australia"
        countryCode:
          type: string
          description: Country Code.
          example: "AU"
        formattedAddress:
          type: string
          description: Formatted Address.
          example: "123 Main St, Apt 101, Melbourne, VIC, 3000, Australia"
    IdentityLinks:
      required:
      - job
      - self
      type: object
      properties:
        self:
          type: string
          description: Self link to the requested identity
          example: https://au-api.basiq.io/users/cd6fbd92/identities/ea3a81
        job:
          type: string
          description: Link to the job associated with this identity
          example: https://au-api.basiq.io/users/ea3a81/connections/s55bf3
    ForbiddenAccessError:
      required:
        - correlationId
        - data
        - type
      type: object
      properties:
        type:
          type: string
          description: Always "list".
          example: list
        correlationId:
          type: string
          description: Unique identifier for this particular occurrence of the problem.
          example: ac5ah5i
        data:
          type: array
          description: Error data.
          items:
            required:
              - code
              - source
              - type
            type: object
            properties:
              type:
                type: string
                description: Type of the response, always "error"
                example: error
              title:
                type: string
                description: Title of the error
                example: Forbidden Access
              code:
                type: string
                description: Application-specific error code, expressed as a string value.
                example: forbidden-access
                enum:
                  - forbidden-access
                  - no-production-access
                  - access-denied
              detail:
                type: string
                description: >-
                  Human-readable explanation specific to this occurrence of the
                  problem.
                example: Access to this resource is forbidden.
              source:
                $ref: '#/components/schemas/Source'
    InternalServerError:
      required:
        - correlationId
        - data
        - type
      type: object
      properties:
        type:
          type: string
          description: Always "list".
          example: list
        correlationId:
          type: string
          description: Unique identifier for this particular occurrence of the problem.
          example: ac5ah5i
        data:
          type: array
          description: Error data.
          items:
            required:
              - code
              - type
            type: object
            properties:
              code:
                type: string
                description: Application-specific error code, expressed as a string value.
                example: internal-server-error
                enum:
                  - internal-server-error
              detail:
                type: string
                description: >-
                  Human-readable explanation specific to this occurrence of the
                  problem.
                example: Internal Server error. Contact support.
              title:
                type: string
                description: Title of the error
                example: Internal Server error.
              type:
                type: string
                description: Type of the response, always "error"
                example: error
    NotFoundError:
      required:
        - correlationId
        - data
        - type
      type: object
      properties:
        type:
          type: string
          description: Always "list".
          example: list
        correlationId:
          type: string
          description: Unique identifier for this particular occurrence of the problem.
          example: ac5ah5i
        data:
          type: array
          description: Error data.
          items:
            required:
              - code
              - type
            type: object
            properties:
              code:
                type: string
                description: Application-specific error code, expressed as a string value.
                example: resource-not-found
                enum:
                  - resource-not-found
              detail:
                type: string
                description: >-
                  Human-readable explanation specific to this occurrence of the
                  problem.
                example: Resource not found.
              title:
                type: string
                description: Title of the error
                example: Requested resource is not found.
              type:
                type: string
                description: Type of the response, always "error"
                example: error
    Source:
      title: Source
      type: object
      properties:
        parameter:
          type: string
          description: String indicating which URI query parameter caused the error.
          example: id
      description: An object containing references to the source of the error.
  securitySchemes:
    services_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - services_token: []
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true
  samples-languages:
    - curl
    - node
    - ruby
    - javascript
    - python