useCapxulAddressBook

Query hook for an actor's address book — every counterparty the person or org has a payment relationship with.

Lists the address book of an actor scope: every counterparty the person or organization has paid, been paid by, requested money from, or added by hand. Read a single entry with useCapxulAddressBookEntry; write with useCapxulAddAddressBookEntry, useCapxulHideAddressBookEntry, useCapxulUnhideAddressBookEntry, and useCapxulLabelAddressBookEntry.

Capability status

The address book family is graded SDK-ready: published and tested, but not yet proven end-to-end by a product surface. Build against it with that expectation — see Capability status.

Import

import { capxulAccountScope, useCapxulAddressBook } from "@capxul/sdk-react";

Usage

"use client";

import { capxulAccountScope, useCapxulAddressBook } from "@capxul/sdk-react";

function ContactsList() {
  const addressBook = useCapxulAddressBook(capxulAccountScope);

  if (addressBook.isLoading) return <p>Loading contacts…</p>;
  if (addressBook.error) return <p>{addressBook.error.message}</p>;

  const visible = addressBook.data.filter((entry) => !entry.hidden);
  return (
    <ul>
      {visible.map((entry) => (
        <li key={entry.id}>
          {entry.label} — {entry.relationship.join(", ")}
        </li>
      ))}
    </ul>
  );
}

The same component reads an organization's address book by swapping the scope:

const addressBook = useCapxulAddressBook(capxulOrgScope(orgId));

The actor scope whose address book to read — capxulAccountScope for the signed-in user, capxulOrgScope(orgId) for an organization. The query stays disabled while the scope is undefined, so you can pass capxulOrgScope(orgs.data?.[0]?.orgId) directly — no manual gating.

options

{ enabled?: boolean } | undefined

Set enabled: false to hold the query even when the scope is ready.

Return type

import { type UseCapxulAddressBookReturn } from "@capxul/sdk-react";
// UseQueryResult<readonly AddressBookEntry[], CapxulError>

data is an array of AddressBookEntry:

Prop

Type

ref is the typed counterparty reference (a handle, email, org handle, payee id, or Capxul user id). relationship lists how the counterparty relates to the actor, derived from actual history — paid, paidBy, requested, member, employee. hidden is the display flag toggled by the hide/unhide mutations; filter on it in your UI.

The hook returns TanStack Query's UseQueryResult. The most-used fields:

Field	Description
`data`	The query data (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last fetch failed, otherwise `null`.
`status`	`'pending'` \| `'error'` \| `'success'`.
`isLoading`	`true` during the first fetch (no data yet).
`isFetching`	`true` whenever a fetch is in flight, including background refetches.
`refetch`	Manually refetch the query.

Capxul query hooks stay pending until the provider finishes bootstrapping — you do not need to gate them on useCapxul() yourself. The full field list is in the TanStack Query useQuery reference; see also the TanStack Query integration guide.

Query key

["capxul", "actor", "account", "addressBook"]      // personal scope
["capxul", "actor", "org", orgId, "addressBook"]   // org scope

("pending" replaces the actor segment while the scope is undefined.) Invalidated — for the same scope only — by every address-book mutation, by every payment-requests and inbox mutation (issuing, approving, or declining a request touches relationship edges), and by money mutations that create a new counterparty relationship (for example useCapxulPay and payroll runs).

Client method

This hook wraps client.account.addressBook.list() for the personal scope, or client.org(orgId).addressBook.list() for an org scope.