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

# Contacts

> Search, read, import, and merge organization contacts through the consolidated Contacts API.

Contacts hold a person's names, summary, stable identities, facts, and conversation history inside one organization. The verified credential supplies the organization; requests never accept an `orgId` that can switch tenants.

## Search and browse

Use `listContacts` for both browsing and free-text search. Pass `query` to match names, summary text, phone numbers, email addresses, or document identities. Matching is case- and accent-insensitive.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --fail-with-body \
  --get "${ARBOL_API_BASE}/contacts" \
  --header "Authorization: Bearer ${ARBOL_ACCESS_TOKEN}" \
  --data-urlencode "query=ana.munoz@example.com" \
  --data-urlencode "limit=25"
```

Continue with `nextCursor` using the same query, sort, and filters. See [Pagination](/guides/pagination).

## Read a contact and its timeline

`getContact` returns the contact, its identities and facts, and the first page of its conversation timeline. Set `timelineLimit` to control that embedded page and use `timelineCursor` to request the next one.

This keeps the contact and its recent activity in one read. There is no separate public timeline operation.

## Import a remote CSV

`importContacts` accepts two inputs:

* `csvUrl`: a direct HTTPS URL to a CSV file;
* `fieldMapper`: the exact CSV headers that map to Contact fields.

At least one stable identity column—`phone`, `email`, or `document`—is required. Each source column can map to only one field. Keys inside `facts` are active Contact Definition identifiers; their values are CSV headers.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "csvUrl": "https://files.example.com/contacts-2026-08.csv",
  "fieldMapper": {
    "givenName": "first_name",
    "familyName": "last_name",
    "phone": "phone_number",
    "email": "email",
    "summary": "notes",
    "facts": {
      "insurance-plan": "insurance_plan"
    }
  }
}
```

The API returns `202 Accepted` with an `importId` and `status: "queued"`. A durable Workflow downloads and validates the file, then imports at most 500 rows and 2 MB. Existing contacts are matched within the organization by normalized phone, email, or document identity; ambiguous matches are not guessed.

<Info>
  The source URL must return the CSV directly without redirects and remain available while the Workflow starts. Keep the `importId` for support and request correlation.
</Info>

## Merge duplicates

Use `mergeContacts` only after choosing one primary and one secondary Contact. The operation moves compatible identities and facts to the primary Contact, redirects owned relationships, and retires the secondary Contact. An identity conflict returns `409` instead of choosing an owner implicitly.