fastify-xhubspot
contacts.list
Page through all HubSpot contacts with optional limit and cursor-based pagination.
contacts.list
Retrieve a paginated list of HubSpot contacts. Uses cursor-based pagination via the after token returned in each response.
Signature
fastify.contacts.list(options?: {
limit?: number;
after?: string;
sort?: string[];
}): Promise<{
contacts: Array<{ id: string; properties: Record<string, string> }>;
paging?: { next?: { after: string } };
}>
Params
| Name | Type | Required | Description |
|---|---|---|---|
options.limit | number | No | Maximum contacts per page. Default: 100. |
options.after | string | No | Cursor token from a previous response's paging.next.after to get the next page. |
options.sort | string[] | No | Sort order, e.g., ["-createdate"] for descending by creation date. |
Returns
| Field | Type | Description |
|---|---|---|
contacts | Array<{ id, properties }> | Contacts on this page. |
paging.next.after | string | undefined | Cursor for the next page. Absent when there are no more pages. |
Throws
Re-throws the HubSpot API error on failure.
Examples
Basic — first page
const { contacts, paging } = await fastify.contacts.list({ limit: 50 });
for (const contact of contacts) {
console.log(contact.id, contact.properties.email);
}
Realistic — paginate all contacts
async function getAllContacts(fastify) {
const all = [];
let after;
do {
const result = await fastify.contacts.list({ limit: 100, after });
all.push(...result.contacts);
after = result.paging?.next?.after;
} while (after);
return all;
}
See also
- contacts.search — filter contacts by property value instead of listing all
- contacts.batchCreate — bulk-create multiple contacts
AI Context
package: "@xenterprises/fastify-xhubspot"
method: fastify.contacts.list(options?)
use-when: Page through all HubSpot contacts with optional limit, after cursor, and properties list
returns: { results, paging }