Data Retrieval

This guide covers retrieving account data through Blink Data APIs.

Consent Required

Before retrieving data, you must create and authorise a consent. See the Quick Start guide for the complete flow.

Each data endpoint needs a permission on the consent, which the customer approved when they authorised it. See Permissions for the full mapping.

Bank Metadata

Before retrieving data, use the metadata endpoint to discover which features each bank supports.

Request:

GET /v1/meta HTTP/1.1
Host: sandbox.data.blinkpay.co.nz
Authorization: Bearer {access_token}

Response:

[
  {
    "bank_id": "0b7a9c3e-5d2f-4e8a-9f61-2c4d8e7b1a05",
    "name": "PNZ",
    "features": {
      "accounts": true,
      "balances": true,
      "transactions": true,
      "statements": true,
      "party": true
    }
  }
]

The response is a top-level array with one entry per bank enabled for your organisation. bank_id differs between sandbox and production, so match on name rather than hard-coding the ID.

Why use metadata:

Banks continuously add new features
Your application can adapt automatically
No code changes needed when features become available

Best practices:

Cache metadata response for 24 hours
Check feature availability before creating consents
Provide fallback workflows for unsupported features

Accounts API

List Accounts

Request:

GET /v1/accounts?consent_id={consent_id} HTTP/1.1
Host: sandbox.data.blinkpay.co.nz
Authorization: Bearer {access_token}

Required Permission: ReadAccounts

The customer chooses which accounts to share at their bank, so the list can hold more than one account. It accepts page and size (see Pagination).

Response:

{
  "accounts": [
    {
      "account_id": "eyJhY2NvdW50SWQiOiIxMjM0NTY3ODkwIn0",
      "name": "Everyday Account",
      "type": "current",
      "currency": "NZD",
      "details": {
        "number": "12-3456-7890123-00",
        "name": "Everyday Transactional Account"
      }
    },
    {
      "account_id": "eyJhY2NvdW50SWQiOiIwOTg3NjU0MzIxIn0",
      "name": "Savings Account",
      "type": "savings",
      "currency": "NZD",
      "details": {
        "number": "12-3456-7890123-01",
        "name": "Savings Account"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "size": 500,
    "total_pages": 1,
    "total_records": 2
  }
}

Get an Account

GET /v1/accounts/{account_id}?consent_id={consent_id} HTTP/1.1
Host: sandbox.data.blinkpay.co.nz
Authorization: Bearer {access_token}

Required Permission: ReadAccounts

Returns a single account object, in the same shape as an entry in the accounts list above.

Balances API

Get Account Balances

Request:

GET /v1/accounts/{account_id}/balances?consent_id={consent_id} HTTP/1.1
Host: sandbox.data.blinkpay.co.nz
Authorization: Bearer {access_token}

Required Permission: ReadBalances

Response:

{
  "balances": [
    {
      "account_id": "eyJhY2NvdW50SWQiOiIxMjM0NTY3ODkwIn0",
      "type": "current",
      "amount": {
        "amount": "1234.56000",
        "currency": "NZD"
      },
      "direction": "in",
      "date_time": "2026-10-07T10:30:00+13:00"
    },
    {
      "account_id": "eyJhY2NvdW50SWQiOiIxMjM0NTY3ODkwIn0",
      "type": "available",
      "amount": {
        "amount": "1734.56000",
        "currency": "NZD"
      },
      "direction": "in",
      "date_time": "2026-10-07T10:30:00+13:00"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 500,
    "total_pages": 1,
    "total_records": 2
  }
}

Balance Types

The endpoint returns two balance types, current and available.

Type	Description
`current`	Cleared funds balance
`available`	Booked funds plus pending items. Includes an overdraft or credit limit only where the bank reports one on the account

date_time is the point in time the balance was calculated at. Some banks calculate balances once a day, in which case date_time reads as midnight of the current day rather than the time of your request.

Direction

Value	Description
`in`	Positive balance (money available)
`out`	Negative balance (overdraft)

Transactions API

Get Transactions

Request:

GET /v1/accounts/{account_id}/transactions?consent_id={consent_id}&from_booking_date_time={date}&to_booking_date_time={date}&page={page}&size={size} HTTP/1.1
Host: sandbox.data.blinkpay.co.nz
Authorization: Bearer {access_token}

Required Permission: ReadTransactions

Parameters:

Parameter	Required	Description
`consent_id`	Yes	The consent ID
`from_booking_date_time`	Yes	Start of the range (ISO 8601 date-time, with offset)
`to_booking_date_time`	No	End of the range (ISO 8601 date-time, with offset)
`page`	No	Page number (default: 1)
`size`	No	Records per page (default: 500, max: 500)

Date filters: send a full ISO 8601 date-time with an offset (2026-09-01T00:00:00Z or 2026-09-01T00:00:00+12:00); a date on its own is rejected. The range must sit inside the consent's start_date_time to end_date_time window, the start can't be in the future and the end can't be after today. The same rules apply to the statement date filters. Timestamps in responses are in New Zealand time (+12:00 or +13:00).

Response:

{
  "transactions": [
    {
      "transaction_id": "txn-123",
      "type": "POS",
      "direction": "out",
      "amount": {
        "amount": "45.50000",
        "currency": "NZD"
      },
      "status": "posted",
      "date_time": "2026-09-15T14:23:00+12:00",
      "description": "Coffee Shop",
      "balance": {
        "account_id": "eyJhY2NvdW50SWQiOiIxMjM0NTY3ODkwIn0",
        "type": "current",
        "amount": {
          "amount": "1189.06000",
          "currency": "NZD"
        },
        "direction": "in",
        "date_time": "2026-09-15T14:23:00+12:00"
      },
      "merchant": {
        "name": "Coffee Shop",
        "category": "5812"
      }
    },
    {
      "transaction_id": "txn-124",
      "type": "DC",
      "direction": "in",
      "amount": {
        "amount": "1500.00000",
        "currency": "NZD"
      },
      "status": "posted",
      "date_time": "2026-09-14T09:00:00+12:00",
      "description": "Salary Payment",
      "balance": {
        "account_id": "eyJhY2NvdW50SWQiOiIxMjM0NTY3ODkwIn0",
        "type": "current",
        "amount": {
          "amount": "2689.06000",
          "currency": "NZD"
        },
        "direction": "in",
        "date_time": "2026-09-14T09:00:00+12:00"
      },
      "reference": {
        "from_party": {
          "name": "ACME Corp",
          "reference": {
            "reference": "Payroll"
          }
        },
        "to_party": {
          "name": "J Smith",
          "reference": {
            "particulars": "Salary",
            "code": "Sep",
            "reference": "John Smith"
          }
        }
      }
    }
  ],
  "pagination": {
    "page": 1,
    "size": 500,
    "total_pages": 3,
    "total_records": 1234
  }
}

Reading Transactions

amount.amount is a string that is never signed (up to 13 digits and 5 decimal places). The sign is carried by direction: in is money into the account and out is money out of it.

transaction_id is optional. Some banks don't send it, so don't use it as a unique key without a fallback. type is the bank's own transaction code, passed through unchanged; its format differs by bank (the values above are illustrative), so don't map on it across banks. merchant (name and MCC category), card, from_account, to_account and reference are optional; handle them being absent.

In reference, the parties are fixed by role, not by direction: from_party is the payer and to_party is the payee, each with the name and the particulars, code and reference on their side of the payment. For an incoming payment such as the salary above, the payer's name is in from_party.name and the details the payer entered for the account holder are usually in to_party.reference. For an outgoing payment, the account holder is the payer.

Transaction Status

Status	Description
`posted`	Transaction completed and cleared
`pending`	Transaction pending/processing

Statements API

Statements are available at some banks only: see Bank Coverage, or check features.statements in GET /v1/meta. The PNZ test bank supports them. All three statement endpoints need the ReadStatements permission on the consent.

List Statements

Request:

GET /v1/accounts/{account_id}/statements?consent_id={consent_id}&from_statement_date_time=2026-01-01T00:00:00Z HTTP/1.1
Host: sandbox.data.blinkpay.co.nz
Authorization: Bearer {access_token}

Required Permission: ReadStatements

Parameters:

Parameter	Required	Description
`consent_id`	Yes	The consent ID
`from_statement_date_time`	Yes	Start of the range (ISO 8601 date-time, with offset)
`to_statement_date_time`	No	End of the range (ISO 8601 date-time, with offset)
`page`	No	Page number (default: 1)
`size`	No	Records per page (default: 500, max: 500)

The date filters follow the same rules as transactions.

Response:

{
  "statements": [
    {
      "statement_id": "stmt-001",
      "date": "2026-09-01T00:00:00+12:00",
      "type": "regular",
      "description": "August 2026 Statement",
      "period": {
        "from": "2026-08-01T00:00:00+12:00",
        "to": "2026-08-31T23:59:59+12:00"
      },
      "starting_balance": {
        "amount": {
          "amount": "2104.10000",
          "currency": "NZD"
        },
        "direction": "credit"
      },
      "closing_balance": {
        "amount": {
          "amount": "1689.06000",
          "currency": "NZD"
        },
        "direction": "credit"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "size": 500,
    "total_pages": 1,
    "total_records": 1
  }
}

type is regular for a periodic statement or interim for one issued part-way through a period. starting_balance and closing_balance are optional; their direction is credit or debit.

Get a Statement

GET /v1/accounts/{account_id}/statements/{statement_id}?consent_id={consent_id} HTTP/1.1
Host: sandbox.data.blinkpay.co.nz
Authorization: Bearer {access_token}

Required Permission: ReadStatements

Returns a single statement object, in the same shape as an entry in the statements list above.

Download Statement

Request:

GET /v1/accounts/{account_id}/statements/{statement_id}/file?consent_id={consent_id} HTTP/1.1
Host: sandbox.data.blinkpay.co.nz
Authorization: Bearer {access_token}

Required Permission: ReadStatements

Returns the statement file as a download (Content-Disposition: attachment). Production banks provide a PDF (application/pdf); the PNZ test bank returns plain text (text/plain) instead, so read the Content-Type header rather than assuming a PDF.

Party API

Get Party Information

Two endpoints return a single party object. GET /v1/party returns the customer who authorised the consent; GET /v1/accounts/{account_id}/party returns the party for a specific account.

Request:

GET /v1/party?consent_id={consent_id} HTTP/1.1
Host: sandbox.data.blinkpay.co.nz
Authorization: Bearer {access_token}

GET /v1/accounts/{account_id}/party?consent_id={consent_id} HTTP/1.1
Host: sandbox.data.blinkpay.co.nz
Authorization: Bearer {access_token}

Required Permission: ReadParty

Response:

{
  "party_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "John Smith",
  "party_type": "personal",
  "email_address": "john@example.com",
  "phone": "+6421234567",
  "address": {
    "street_address": "123 Main Street",
    "suburb": "Central",
    "city": "Auckland",
    "post_code": "1010",
    "country": "NZ"
  }
}

party_type is personal (sole or joint holder) or delegate. email_address, phone and address are optional and depend on what the bank holds.

Pagination

Accounts, balances, transactions and statements are paginated.

Parameter	Default	Max	Description
`page`	1	-	Page number
`size`	500	500	Records per page

The response's pagination object holds page, size, total_pages and total_records.

Use Returned Values

Every page holds size records except the last. Stop at total_pages; a page past the end returns an empty list. If the result is too large to return (400 BDT263), narrow the date range.