List contacts

View as MarkdownOpen in Claude
Every phone number your lines have exchanged a message or a call with, newest activity first. A contact is derived, not stored — there is no address book to add anyone to. Dial reads your message and call history and reports one row per counterparty, so a number appears here the moment it first texts or calls one of your lines, or one of your lines first reaches it, and never needs to be created or deleted. **Counts span every line on the account.** Two of your numbers talking to the same person is one contact with the totals added together, not two rows — the contact is the person, not the pairing. **Group conversations are not contacts.** A group message is addressed to the group rather than to a person, so it is counted under neither the group nor the participant who sent it. List groups is where those live. **Pagination** is Stripe-style and matches List billing activity: pass `limit` for the page size and `starting_after` set to the `lastAt` of the last contact you received to fetch the next page (only contacts whose activity is strictly older are returned). `hasMore` tells you whether to ask again. Most accounts get everything in one call.

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Query parameters

limitintegerOptional1-1000Defaults to 100

Max contacts per page (clamped to 1-1000).

starting_afterdatetimeOptional

Exclusive cursor — an exact ISO timestamp (the lastAt of the last contact from the previous page). Only contacts with strictly older activity are returned.

Response

One page of contacts, newest activity first.
contactslist of objects
hasMoreboolean
True when more contacts exist with activity older than the last one returned.

Errors

400
Bad Request Error
401
Unauthorized Error