Akahu Outlets API

openapi: 3.2.0
info:
  title: Genie transaction enrichment Outlets API
  version: 1.0.0
  description: 'Applications that use Akahu for bank account connectivity can use our transactions API to get high quality enriched transactions that include merchant and category information. We''ve built the Genie API to expose Akahu''s transaction enrichment engine for applications that instead source raw transaction data themselves.


    Genie is entirely separate from the core Akahu API and does not require an Akahu App ID Token or App Secret to access. If you''re keen to get your hands on an API key to try it out, get in touch with us at hello@akahu.nz.'
servers:
- url: https://api.genie.akahu.io/v1
tags:
- name: Outlets
paths:
  /outlets/{id}:
    get:
      summary: Get outlet
      description: Retrieve details for an outlet.
      operationId: GenieGetOutlet
      parameters:
      - name: id
        in: path
        required: true
        description: The outlet identifier
        schema:
          type: string
      tags:
      - Outlets
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                  item:
                    $ref: '#/components/schemas/GenieOutlet'
                required:
                - success
                - item
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenieErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenieErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenieErrorResponse'
        '429':
          description: Rate Limiting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenieErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenieErrorResponse'
components:
  schemas:
    GenieErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - false
        message:
          type: string
          description: A description of the error that has occurred
      required:
      - success
      - message
    GenieOutlet:
      type: object
      description: An individual outlet (i.e. specific location). An outlet will always be returned in combination with its related "parent" merchant.
      required:
      - _id
      - name
      properties:
        _id:
          type: string
          description: The unique outlet identifier.
        name:
          type: string
          description: The outlet name. This is usually more specific than the merchant name. For example, the merchant name may be "Pak'nSAVE", while the outlet name is "Pak'nSAVE Sylvia Park".
        logo:
          type: string
          description: A URL referencing the outlet's logo. This field will only be included if the logo for this outlet differs from the merchant's logo.
        website:
          type: string
          description: The URL for the outlet's website. This field will only be included if the website for this outlet differs from the merchant's website.
        phone:
          type: string
          description: The outlet's phone number. This field will only be included if the phone number for this outlet differs from the merchant's phone number.
        nzbn:
          type: string
          description: The outlet's NZBN (New Zealand Business Number). This field will only be included if the NZBN for this outlet differs from the merchant's NZBN.
        location:
          description: The outlet's location.
          allOf:
          - $ref: '#/components/schemas/GenieLocation'
        tags:
          type: array
          description: Tags that apply to the outlet. For example, to indicate that the outlet provides a subscription service. Tags are inherited (and potentially extended) from the outlet's "parent" merchant.
          items:
            $ref: '#/components/schemas/GenieTag'
      example:
        _id: outlet_cm0qk0idc000l08kydt9gf9gz
        name: FreshChoice Greytown
        website: https://greytown.store.freshchoice.co.nz/
        phone: 06 304 7237
        location:
          accuracy: establishment
          formatted: 12 Hastwell Street, Greytown 5712, New Zealand
          address:
            street: 12 Hastwell Street
            city: Greytown
            region: Wellington
            country: New Zealand
            postal_code: '5712'
          coordinates:
            lat: -41.0809289
            lon: 175.4589657
        tags: []
    GenieCoordinates:
      type: object
      description: Latitude/longitude location coordinates.
      required:
      - lat
      - lon
      properties:
        lat:
          type: number
        lon:
          type: number
      example:
        lat: -36.848461
        lon: 174.763336
    GenieAddress:
      type: object
      required:
      - street
      - city
      - region
      - country
      - postal_code
      properties:
        street:
          type: string
        suburb:
          type: string
        city:
          type: string
        region:
          type: string
        country:
          type: string
        postal_code:
          type: string
      example:
        street: 125 Queen Street
        suburb: Auckland CBD
        city: Auckland
        region: Auckland
        country: New Zealand
        postal_code: '0620'
    GenieTag:
      type: string
      description: A tag applied to an outlet or merchant, indicating a specific attribute that applies to that entity.
      enum:
      - subscription
      - closed
    GenieLocation:
      type: object
      description: A physical location.
      required:
      - accuracy
      - formatted
      - coordinates
      properties:
        accuracy:
          type: string
          enum:
          - country
          - region
          - locality
          - sublocality
          - establishment
        formatted:
          type: string
        coordinates:
          $ref: '#/components/schemas/GenieCoordinates'
        address:
          description: The address fields in a structured format. This is available on almost all establishment-level locations, however it may occasionally be missing,
          allOf:
          - $ref: '#/components/schemas/GenieAddress'
      example:
        accuracy: establishment
        formatted: 12 Hastwell Street, Greytown 5712, New Zealand
        address:
          street: 12 Hastwell Street
          city: Greytown
          region: Wellington
          country: New Zealand
          postal_code: '5712'
        coordinates:
          lat: -41.0809289
          lon: 175.4589657
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Token based API authentication
x-samples-languages:
- shell
- csharp
- java
- node
- python
- go
- php
- ruby
x-provenance:
  method: searched
  source: https://developers.akahu.nz/reference
  harvested: '2026-10-26'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developers.akahu.nz/reference/geniegetcategory.md
  - https://developers.akahu.nz/reference/geniegetmerchant.md
  - https://developers.akahu.nz/reference/geniegetoutlet.md
  - https://developers.akahu.nz/reference/geniegetpublickey.md
  - https://developers.akahu.nz/reference/geniesearch.md
  - https://developers.akahu.nz/reference/post_feedback.md
  merge:
    pages: 6
    deduped: 22
    conflicts_kept_first: 0