# Humans

> Humans is Cooper's people directory. Use it to add, find, edit and remove the people you work with (teammates, client contacts, vendor contacts and leads) and to see everything that has happened with each one.

Source: https://docs.cooperbuild.ai/connect/humans
Last updated: 2026-10-05
Keywords: humans, contacts, people, address book, crm, directory, clients, vendors, leads, employees, team members, contact list

**Humans** is the people directory in Cooper. Every person your company deals with gets a human record: your own team members, client contacts, vendor and subcontractor contacts, leads and partners. Office admins, project managers and estimators use it to look someone up, keep contact details current, link people to their [organizations](https://docs.cooperbuild.ai/connect/organizations.md) and see the full history with a person in one place.

Each human has a detail panel. It shows their contact details, their organization, open action items, activities, a timeline of everything that happened with them, their text messages and their email threads.

![The Humans list showing the directory tabs, filters, search and the Add Human button](https://docs.cooperbuild.ai/screenshots/connect/humans-list.png)

*Screenshot: The Humans list. 1: directory tabs, 2: filters, 3: search, 4: Add Human, 5: a human's row.*

## Key concepts

| Term | Meaning |
|---|---|
| **Human** | One person in your directory. A human has a name and, optionally, contact details, an organization, a relationship stage and a relationship type. |
| **Internal human** | A human marked as part of your own team. Internal humans appear under **Our Team** and show a **Team Member** badge. |
| **External organization** | The company a human works for, such as a client, vendor or subcontractor. See [Organizations](https://docs.cooperbuild.ai/connect/organizations.md). |
| **Relationship stage** | Where the relationship stands: **Lead**, **Prospect**, **Opportunity**, **Counterparty**, **Dormant** or **Inactive**. New humans start as **Lead**. |
| **Relationship type** | A category your company defines, such as Client or Subcontractor. Admins manage the list in Connect settings. |
| **Services** | The labor services a person provides. You pick them from the labor items in your catalog. |
| **System user** | A human who has a login to your Cooper workspace. A system user cannot be deleted from Humans. |
| **Action item** | Something somebody still owes, such as a document to send or an approval to give. See [Action items](https://docs.cooperbuild.ai/connect/action-items.md). |

## Open Humans

1. In the sidebar, open **Connect**.
2. Click **Humans**.

The page lives at `/connect/allHumans`. You see it only if your role has access to Humans. If your company's plan does not include Humans, you see a plan-locked screen instead.

A link that ends in `?humanId=<id>` opens Humans with that person's detail panel already open. When you close the panel, the `humanId` part is removed from the address.

## Switch between all humans, your team and clients

Three tabs sit at the top of the page. Hover over a tab to see what it holds.

| Tab | What it shows |
|---|---|
| **All Humans** | Everyone in your directory: team members, clients and partners. |
| **Our Team** | Internal humans, the members of your own team. |
| **Clients & Partners** | External people who have a login to your workspace, such as portal users, client users and members from other organizations. |

The page title changes to match the tab. Your search and filters stay applied when you switch tabs.

## Read the Humans list

Each row shows one human:

- **Contact**: the photo or initials, the display name, and a line with their title, relationship type and organization.
  - A small colored dot on the photo shows how recently the record was updated. Hover over the photo to read it, for example "Updated today", "Getting stale" or "Dormant — 90+ days". Team members show "Team member".
  - A **Draft** badge marks a human saved with Draft status.
- **Organization**: the organization name, logo and up to two industries. Hover over it for a summary card. Click the name to open the organization's details.
- **Contact Info**: email and phone. A highlighted icon marks the preferred contact method.
- **Context**: a summary that adapts to the person. Team members show **Team Member**. Leads and prospects show their stage. Dormant and inactive humans show a warning pill.
- **Activity**: when the record was created and last modified, and by whom.

More rows load as you scroll down.

### Sort the list

Click the **Contact**, **Organization** or **Activity** column header to sort by that column.

### Show or hide columns

Click the **Toggle Columns** button (the columns icon) and tick or untick columns. Cooper remembers your choice in this browser.

### Group humans by organization

Drag the **Organization** column header into the bar above the list that says **Drag a column header here to group rows**. To remove the grouping, click the **x** on the **Grouped by** chip.

## Search for a human

1. Click the **Search** icon in the toolbar.
2. Type in the **Search humans…** box.

The search matches first name, display name and email address. It works together with any filters you have applied.

## Filter the Humans list

Use the filter buttons in the toolbar:

| Filter | What it does |
|---|---|
| **Relationship Stage** | Show humans in one or more stages. |
| **Relationship Type** | Show humans with one or more relationship types. |
| **Organization** | Show only humans who belong to one organization. |

Active filters appear as chips under the toolbar, after **Filtered by**. Click the **x** on a chip to remove that filter, or click **Clear all** to remove every filter. Filters are saved in the page address, so you can bookmark or share a filtered view.

## Add a human

You need permission to add humans. Without it, the **Add Human** button does not appear.

### Step 1: Open the form
Click **Add Human** at the top right. The **Add Human** panel opens. If you are on the **Our Team** tab, **Internal Human** is already switched on.

### Step 2: Enter the essentials
Type a **First Name**. This is the only required field. Add **Last Name**, **Title**, **Email** and **Phone Number** if you have them.

### Step 3: Link an organization
In **External Organization**, start typing and pick the person's company from the list. Leave it empty for someone with no company.

### Step 4: Set the stage and team status
Click the stage chip at the top of the form (it starts at **Lead**) to pick a different stage. Switch on **Internal Human** if this person is part of your team.

### Step 5: Add optional details
Open the collapsible sections to add more:
- **More contact options**: **Alternate Email**, **Alternate Number**, **Preferred Contact Method**.
- **Relationship**: **Relationship Type** and **Services**.
- **Address**: **Street**, **City**, **State**, **Postal Code**, **Country**.

To add a photo, click the round avatar at the top of the form and choose an image.

### Step 6: Save
Click **Submit**. The human appears in the list. Click **Cancel** to close without saving. If you entered anything, Cooper asks you to confirm before it discards your changes.

> **Note: One active human per email address**
>
> Two active humans in your company cannot share an email address. If the email is already in use, Cooper shows "An active human with email … already exists in this organization" and names the existing person. Open that person instead of creating a duplicate.

![The Add Human panel with the essentials filled in](https://docs.cooperbuild.ai/screenshots/connect/humans-add-form.png)

*Screenshot: The Add Human panel. 1: photo, 2: stage chip, 3: Internal Human switch, 4: required First Name, 5: collapsible sections.*

## Edit a human

1. Hover over the human's row and click the **⋯** menu at the start of the row.
2. Click **Edit**. The **Update Human** panel opens.
3. Change any field.
4. Click **Submit**.

After you save, the row updates in place and is highlighted briefly. If you edit your own human record, your name and profile picture in Cooper update too.

If you do not have permission to edit, the **Edit** option is hidden.

![The row menu on a human, showing Edit, View and Delete](https://docs.cooperbuild.ai/screenshots/connect/humans-row-actions.png)

*Screenshot: The row menu. 1: Edit, 2: View, 3: Delete.*

> **Note: Stage comes from the organization**
>
> When a human belongs to an organization, Cooper shows the organization's relationship stage for that person. In the edit form the stage chip is locked, with the note "This human is associated with an organization and the stage cannot be changed." Change the stage on the [organization](https://docs.cooperbuild.ai/connect/organizations.md) instead.

## Delete a human

You need delete permission. Without it, the **Delete** option is hidden.

**Delete one human**

1. Open the **⋯** menu on the human's row.
2. Click **Delete**.
3. Confirm in the dialog.

**Delete several humans at once**

1. Tick the checkbox on each row you want to remove. To select every loaded row, tick the checkbox in the header.
2. Click **Delete** at the bottom of the list. The footer shows how many rows are selected. **Clear Selection** unticks them all.
3. Confirm in the dialog.

Deleting archives the human. The human disappears from Humans and from search, and their email address becomes free to use on a new record.

> **Warning: You cannot delete people who have a login**
>
> A human who is a user of your Cooper workspace cannot be deleted. Cooper shows "You dont have permission to delete this human as this is a system user." In a bulk delete, Cooper names the system users and deletes nothing. Remove or archive the person's access in your team settings first.

## Copy a human's contact details

- In the list, hover over the name and click the **Copy contact info** icon. The details are copied to your clipboard.
- In the detail panel, click the **Copy profile** icon next to the name. A formatted profile is copied to your clipboard.
- In the detail panel, hover over **Email**, **Phone** or another field and click its copy icon to copy just that value.

## Email, call or text a human

From the list:

- Click an email address, or the **Email from Cooper** icon, to open Cooper's email composer addressed to that person. When the email is sent, Cooper logs an **Email** activity on the human's record.
- Click a phone number, or the **Open in Cooper Phone** icon, to open the [Phone](https://docs.cooperbuild.ai/connect/phone.md) keypad with the number ready. The call starts only when you press call.

From the detail panel, use the **Email**, **Call** and **Text** buttons under the name. **Text** opens the **Messages** tab. **Text** is disabled when:

- The person has opted out of SMS. The tooltip says they must text START to resubscribe.
- You do not have permission to send messages from Humans.

## Invite a human to Cooper

You can turn a human into a user of your workspace.

1. In the list, hover over the human's name.
2. Click the **Invite to Cooper** icon. It appears only for humans who have an email address and are not users yet.
3. In the **Invite a teammate** panel, check **Email** and **Full name**, which are filled in from the human record.
4. Choose a **Role** and the **Access** type: **Web & mobile** or **Mobile only**.
5. Click **Send invite**.

The person gets an email to verify their address and set a password. They show as **Invited** in your team list until they accept. If the person is already a member, Cooper tells you so.

## View a human's details

Click a human's row, or choose **View** from the row's **⋯** menu. The detail panel opens on the right with the person's name, stage, relationship type, organization and title at the top. It has four tabs: **Overview**, **Timeline**, **Messages** and **Emails**.

![A human's detail panel on the Overview tab](https://docs.cooperbuild.ai/screenshots/connect/humans-detail-overview.png)

*Screenshot: The detail panel. 1: quick actions, 2: tabs, 3: contact details, 4: open items, 5: activities.*

### Overview tab

The **Overview** tab shows:

- **Contact**: **Email**, **Phone**, **Preferred**, **Title**, **Alt Email**, **Alt Phone** and **Address**.
- **Organization**: the linked organization with its stage and contact details.
- **Services**: the services this person provides.
- **Open items**: up to three open action items in each direction, with a **See timeline** link.
- **Activities**: logged meetings, calls, emails and other activities. See [Log an activity](#log-an-activity-with-a-human).
- **Created by** and **Modified by**, with how long ago.

### Timeline tab

The **Timeline** tab lists everything that happened with this person, newest first and grouped by day: money, projects, conversations, meetings, actions, documents and more.

- Click a category chip, such as **Money**, **Meetings** or **Documents**, to show only that category. The chips show counts. Click **All** to see everything again.
- Type in **Search** to find rows by their text.
- Switch **Include their company** on or off to include or leave out rows about the person's organization. It is on by default.
- Click **Details** on a row to expand it.
- More rows load as you scroll. You can also click **Load more**.

If nothing has happened yet, you see "Nothing yet with *name*."

![The Timeline tab filters: category chips, the Include their company switch and search](https://docs.cooperbuild.ai/screenshots/connect/humans-detail-timeline.png)

*Screenshot: Filtering the Timeline. 1: category chips, 2: Include their company, 3: search.*

### Messages tab

The **Messages** tab shows your text conversation with the person on your company's Cooper phone numbers. Type in the **Text *name*…** box and press Enter to send. Use **From** to pick which of your lines sends the text.

- If texting is not set up for your company yet, you see "Texting isn't set up for this organization yet" with a link to see progress.
- If no line can send texts, you see "No phone line can send texts yet" with a link to set one up.

See [Phone](https://docs.cooperbuild.ai/connect/phone.md) for setting up lines.

### Emails tab

The **Emails** tab lists the email threads with this person from the mailboxes you have connected to Cooper. Click a thread to read it. You can start a new email to the person from here.

## Track what a human owes or is waiting for

The **Timeline** tab starts with **Open items**, the open [action items](https://docs.cooperbuild.ai/connect/action-items.md) that involve this person, in two columns:

- **_Name_ has to do**: items this person owns.
- **_Name_ is waiting for**: items somebody else owes this person.

To add one:

1. Click **Add item**. You need permission to edit Humans.
2. In **What needs doing**, describe the task, for example "Send John the updated drawings".
3. In **Who does it**, pick a teammate.
4. Optionally set **Due**.
5. Click **Add action item**.

The new item is linked to this person. Depending on your rights on an item, you can tick it done, reopen it, or use its **More** menu to **Set due date** or dismiss it as **Already done** or **No longer needed**. For everything else, open [Action items](https://docs.cooperbuild.ai/connect/action-items.md).

## Log an activity with a human

1. Open the human's **Overview** tab.
2. In **Activities**, click **Add**.
3. Pick the **Activity Type**: **Meeting**, **Call**, **Email**, **Task**, **Other**, **Follow Up** or **Converted**.
4. Set the **Date**, the **Participants** and, if you want, the **Duration**.
5. Type a **Description**. It is required.
6. To make it repeat, switch on **Recurring Activity** and choose a **Recurring Period**.
7. Optionally add **Attachments**, such as photos or paperwork.
8. Click **Save**.

To change or remove an activity, open its **⋯** menu and click **Edit** or **Delete**.

## Fields reference

| Field | Required | What it means |
|---|---|---|
| Photo | No | The person's picture. Click the avatar to upload an image. |
| Stage | No | **Lead** (default), **Prospect**, **Opportunity**, **Counterparty**, **Dormant** or **Inactive**. Locked when the human belongs to an organization. |
| Internal Human | No | Marks the person as a member of your own team. |
| First Name | **Yes** | 2 to 30 characters. Cannot start with a special character. |
| Last Name | No | Up to 30 characters. |
| Title | No | Job title, up to 100 characters. |
| Email | No | Must be a valid email address. Must not belong to another active human in your company. |
| Phone Number | No | Includes a country picker. Defaults to the United States. |
| External Organization | No | The company the person works for. |
| Alternate Email | No | A second email address. Must be valid. |
| Alternate Number | No | A second phone number. |
| Preferred Contact Method | No | Free text, for example Email, Phone or WhatsApp. |
| Relationship Type | No | One of the relationship types your admin set up. |
| Services | No | Labor services from your catalog that this person provides. |
| Street, City, State, Postal Code, Country | No | The person's address. **Country** starts as United States. |

The display name is built from the first and last name.

## Permissions

Access to Humans is set by your role, under **Connect** > **Humans**:

| Permission | What it allows |
|---|---|
| **Read** | Open Humans, search, filter and view details. |
| **Write** | Add humans, edit them, add action items from a person's page and send texts from the **Messages** tab. |
| **Delete** | Delete (archive) humans. |

Workspace owners have full access. An admin can also limit a role to certain relationship types or relationship stages. People in that role then see only the humans that match.

Only humans in your own company are visible or editable.

## Tips and best practices

- Search before you add someone. Each email address can belong to only one active human.
- Link every external contact to their organization. Their stage, organization filter and timeline then work from the organization too.
- Set the relationship type for clients and vendors. It feeds the **Relationship Type** filter and the row subtitle.
- Use the freshness dot on the photo to spot contacts you have not touched in a while.
- Log calls and meetings as activities so the **Timeline** tells the full story.

## Troubleshooting

### I can't see Humans in the sidebar

Your role does not have Read access to Humans, or your company's plan does not include it. Ask an admin to grant **Connect** > **Humans** > **Read** to your role.

### There is no Add Human button

Your role does not have Write access to Humans. Ask an admin for **Connect** > **Humans** > **Write**.

### 'An active human with email … already exists in this organization'

Another active human already uses that email address. The message names that person. Search for them and edit the existing record, or use a different email address.

### 'You dont have permission to delete this human as this is a system user'

The person has a login to your Cooper workspace. System users cannot be deleted from Humans. Manage their access from your team settings instead.

### I can't change the stage of a human

The human belongs to an organization, so the stage comes from the organization. Change the stage on the organization.

### Someone I know exists does not show up

Check that no filter is active. Look for chips under **Filtered by** and click **Clear all**. Check that you are on **All Humans** and not **Our Team** or **Clients & Partners**. Your role may also be limited to certain relationship types or stages.

### The Invite to Cooper icon is missing

The icon appears only when the human has an email address and is not already a user. Add an email address to the human first.

### The Text button is greyed out

Either the person has opted out of texts (they must text START to resubscribe), or your role cannot send messages from Humans.

## For AI agents

Agents work with humans through the CooperBuild MCP server.

| Tool | What it does | Key parameters |
|---|---|---|
| `search_humans` | Finds people. Available to every user and returns summary fields only. | `search` (name, email, phone, title or organization), `id`, `email`, `phone`, `orgName`, `externalOrgId`, `type` (`member`, `employee`, `client`, `vendor`, `lead`, `guest`, `contact`), `humanCategory`, `limit` (1–50, default 15), `includeAccess` |
| `person_status_brief` | One plain-language answer to "where are we with X": who they are, open items both ways, money position, last contact, next meeting. | `humanId` (preferred) or `query` |
| `person_timeline` | Everything that happened with one person or company, newest first, with category counts and open action items. This is the same data as the **Timeline** tab. | `humanId`, `externalOrgId` or `query`; `categories` (`MONEY`, `PROJECTS`, `CONVERSATIONS`, `MEETINGS`, `ACTIONS`, `DOCUMENTS`, `OTHER`); `since`; `until`; `includeCompany`; `search`; `limit` (max 50); `pageNo` |
| `crm_relationship_brief` | A summary of the relationship: last outbound touch versus last inbound engagement, open follow-ups and open action items. Read-only. | `humanId` or `externalOrgId` |
| `crm_interaction_list` | Lists logged meetings, calls, emails, texts and follow-ups row by row. | `humanId`, `externalOrgId`, `projectId`, `activityTypes`, `direction`, `lifecycle`, `followUpStatus` |
| `crm_interaction_log` | Logs one interaction. Previews first; pass `confirm: true` to save. | `activityType`, `direction` (required: `outbound`, `inbound`, `conversation` or `internal`), `summary`, `durationMinutes` |
| `invite_user` | Invites a person to the workspace. | See the tool schema. |

Rules and common errors:

- `person_timeline`, `person_status_brief`, `crm_relationship_brief` and `crm_interaction_list` need **Humans** Read. `crm_interaction_log` needs **Humans** Write.
- To find a colleague, use `search_humans` with `type: "member"`. That matches people with a workspace login. `type: "employee"` matches only humans marked internal.
- An empty `data` with a `note` from `search_humans` means a type filter removed the matches. The person exists.
- To check whether someone is already a user, call `search_humans` with `includeAccess: true`. Do not send an invitation to find out.
- An ambiguous name passed as `query` returns candidates. Ask the user which one they mean. Never guess.
- In `crm_interaction_log`, `durationMinutes` is in minutes. Logging an `inbound` interaction stops the person's scheduled campaign sends. The preview reports this under `cadenceStop`.
- There is no dedicated tool to create or edit a human. The generic record tools (`db_create`, `db_update`) on the `Human` model need **Humans** permission. Creating a human with an email already used by an active human fails with "An active human with email … already exists in this organization". Find the existing human with `search_humans` and use that one.

## Related

- [Organizations](https://docs.cooperbuild.ai/connect/organizations.md): the companies your humans work for. Stage and industries come from here.
- [Action items](https://docs.cooperbuild.ai/connect/action-items.md): what each person owes you and what you owe them.
- [Teams](https://docs.cooperbuild.ai/connect/teams.md): groups of humans you assign together.
- [Phone](https://docs.cooperbuild.ai/connect/phone.md): calls and texts with your humans on Cooper numbers.