> ## Documentation Index
> Fetch the complete documentation index at: https://bluebubbles.anmho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts API reference — BlueBubbles SDK

> Fetch and query contacts stored on the macOS device running BlueBubbles Server. Look up contact details by one or more phone numbers or email addresses.

The contacts service gives you access to the Contacts app data on the macOS machine running BlueBubbles Server. You can retrieve all contacts at once or query for specific contacts by passing one or more phone numbers or email addresses. This is useful for resolving display names, profile photos, and other contact metadata alongside your iMessage data.

Access the service through `client.contacts`.

<Note>
  Contacts are read directly from the macOS device. The server must have
  permission to access the system Contacts app. If the permission has not been
  granted, these calls will return empty results or an error.
</Note>

***

## Fetch all contacts

### `getContacts()`

Returns all contacts stored on the macOS device running BlueBubbles Server.

**Signature**

```typescript theme={null}
client.contacts.getContacts(): CancelablePromise<any>
```

**Example**

```typescript theme={null}
const contacts = await client.contacts.getContacts();

for (const contact of contacts.data) {
  console.log(contact.displayName, contact.phoneNumbers);
}
```

<Tip>
  For large contact lists, consider using `queryContacts()` with specific
  addresses instead of loading every contact on each request.
</Tip>

***

## Query contacts by address

### `queryContacts()`

Queries for contacts matching a list of addresses (phone numbers or email addresses). Use this when you already have addresses from a message or handle and want to resolve their contact information.

**Signature**

```typescript theme={null}
client.contacts.queryContacts({
  requestBody,
}: {
  requestBody?: Record<string, any>;
}): CancelablePromise<any>
```

**Request body parameters**

<ParamField body="addresses" type="string[]">
  A list of one or more phone numbers or email addresses to look up. Each entry
  should match the format stored in the Contacts app (e.g. `+12125551234` or
  `user@icloud.com`).
</ParamField>

**Example**

```typescript theme={null}
// Look up contacts for a set of known addresses
const result = await client.contacts.queryContacts({
  requestBody: {
    addresses: ["+12125551234", "alice@icloud.com", "+14155550199"],
  },
});

for (const contact of result.data) {
  console.log(contact.displayName, contact.addresses);
}
```

```typescript theme={null}
// Resolve a single address after receiving a message
const senderAddress = message.handle.address;

const result = await client.contacts.queryContacts({
  requestBody: {
    addresses: [senderAddress],
  },
});

const contact = result.data[0];
console.log(`Message from: ${contact?.displayName ?? senderAddress}`);
```