Skip to main content

Querying basics

Most list queries in the External API are exposed as Relay-style connections with cursor-based pagination, projection, filtering, and sorting. Once you understand the shape on one query, the others all follow the same pattern.

All examples on this page require a JWT — get one from the homepage first.

Projection: ask only for what you need​

GraphQL only returns the fields you request, and the server only loads the database columns and navigations needed to fulfil the request. Asking for more fields makes the response bigger and the underlying SQL more expensive — keep selections tight.

query currentBankInformation {
bank {
  id
  name
}
}

bank returns the authenticated bank's own record. The bank ID is taken from your JWT — there's no argument.

Connection shape: nodes, pageInfo, totalCount​

List queries don't return a flat array — they return a connection object. The most useful fields:

  • nodes — a flattened list of the returned entities. Use this when you don't need cursors.
  • edges — [{ node, cursor }]. Use this when you want the cursor for each row.
  • pageInfo — { hasNextPage, hasPreviousPage, startCursor, endCursor }.
  • totalCount — the total number of rows matching the query (regardless of paging).
query firstOrganizations($first: Int) {
organizations(first: $first) {
  totalCount
  nodes {
    id
    name
  }
  pageInfo {
    hasNextPage
    endCursor
  }
}
}

Pagination: cursor-based, not offset​

Use first: N to fetch the first N rows, then after: "<endCursor>" to fetch the next page using the endCursor returned from the previous response. There is no skip / take / page argument — cursors are the only paging mechanism.

query nextOrganizationsPage($first: Int, $after: String) {
organizations(first: $first, after: $after) {
  nodes {
    id
    name
  }
  pageInfo {
    hasNextPage
    endCursor
  }
}
}

To paginate backwards through a list, use last: N together with before: "<startCursor>". Mixing forward and backward args (first with before, etc.) is invalid.

Filtering​

Connection queries accept a where argument with the operators GraphQL clients expect: eq, neq, contains, startsWith, gt, lt, in, and, or. Only fields the schema explicitly allows can be filtered — an unbound field returns a schema error at parse time. The per-query guides in this section list the bound fields for each query.

query searchOrganizations($where: OrganizationFilterInput) {
organizations(where: $where, first: 20) {
  totalCount
  nodes {
    id
    name
    vatNumber
  }
}
}

Sorting​

Connection queries accept order — an array of { field: ASC | DESC } objects. As with where, only declared fields can be sorted.

query orderedOrganizations($order: [OrganizationSortInput!]) {
organizations(order: $order, first: 5) {
  nodes {
    id
    name
  }
}
}

Combine them​

where, order, first/after are all independent — combine them freely.

query findRecentAcme($where: OrganizationFilterInput, $order: [OrganizationSortInput!], $first: Int) {
organizations(where: $where, order: $order, first: $first) {
  totalCount
  nodes {
    id
    name
    vatNumber
  }
  pageInfo {
    hasNextPage
    endCursor
  }
}
}

Single-entity lookups​

A few queries return a single object or a flat list rather than a connection — bank, usersBySsn, userById, usersById, bankReportById, reviewSectionById, businessVolumeRevision. They take their arguments directly and have no nodes / pageInfo. For example:

query singleBankReport($id: UUID!) {
bankReportById(id: $id) {
  id
  publishedTime
}
}

Some single-entity lookups (notably bankReportById, userById, usersById, usersBySsn) return a list, not a single object — typically with zero or one element. Treat them as lists in your client code.

Bank scoping is automatic​

Every query that returns bank-owned data filters to your bank automatically — derived from the bankId claim on your JWT. You can't (and don't need to) pass a bankId argument. A query for "all organizations" returns your bank's organizations, never another bank's data.

Schema-level reference​

The other pages in this section list each query's sortable and filterable fields. For everything else — every field on every type — open /graphql to browse the live schema in Nitro.