# Contacts tools

> Every contacts tool in the developer API, with arguments and examples: search, list and read contacts.

**Needs:** Google, Outlook or iCloud Contacts. 3 tools.

These tools appear in `GET /v1/tools` only when the API key's MCP server includes a connection of this kind. Call each one with `POST /v1/tools/\<name>`, sending its arguments as a JSON object. See [Calling tools](https://docs.plugsight.app/developers/calling-tools.md) for the request and response format.

| Tool                                  | What it does    | Kind |
| ------------------------------------- | --------------- | ---- |
| [`contacts_search`](#contacts_search) | Search contacts | Read |
| [`contacts_list`](#contacts_list)     | List contacts   | Read |
| [`contacts_get`](#contacts_get)       | Get a contact   | Read |

The example requests fill in only the required arguments, with placeholder values.

## contacts_search

**Search contacts** · Read

Finds people by name, email, phone or company. Google also searches 'other contacts' (people you've emailed); iCloud and Outlook search the whole address book. Returns { contacts, note }: a note means some contacts couldn't be searched, and says why.

| Argument  | Type    | Required | What it is                                                                     |
| --------- | ------- | -------- | ------------------------------------------------------------------------------ |
| `query`   | string  | Yes      | Name, email, phone number or company                                           |
| `limit`   | integer | No       | Most results to return. Default `20`.                                          |
| `account` | string  | No       | Connection id from list_accounts (optional when there's only one of this type) |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/contacts_search \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "…"}'
```

## contacts_list

**List contacts** · Read

Saved contacts with paging (Google: most recently changed first; iCloud and Outlook: by name). A note means the list isn't complete, and says why.

| Argument     | Type    | Required | What it is                                                                     |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------ |
| `limit`      | integer | No       | Most results to return. Default `100`.                                         |
| `page_token` | string  | No       | next_page_token from the previous page                                         |
| `account`    | string  | No       | Connection id from list_accounts (optional when there's only one of this type) |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/contacts_list \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## contacts_get

**Get a contact** · Read

Everything saved for one contact: emails, phones, organisation, addresses, notes, birthday and links.

| Argument  | Type   | Required | What it is                                                                     |
| --------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `id`      | string | Yes      | Contact id from contacts_search or contacts_list                               |
| `account` | string | No       | Connection id from list_accounts (optional when there's only one of this type) |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/contacts_get \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "…"}'
```

## Related articles

- [Calling tools](https://docs.plugsight.app/developers/calling-tools.md)
- [Errors](https://docs.plugsight.app/developers/errors.md)
- [Authentication](https://docs.plugsight.app/developers/authentication.md)

---

Web version: https://docs.plugsight.app/developers/contacts-tools
