> ## Documentation Index
> Fetch the complete documentation index at: https://reach-owl.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts: Leads Generated by Your Campaigns

> Contacts are created automatically when campaigns interact with people. You can list, view, and annotate contacts but cannot create or update them directly.

Contacts are the people ReachOwl discovers and interacts with during outreach. Every time a campaign scans a group, sends a friend request, or delivers a message, ReachOwl records the resulting person as a contact. Contacts are read-only: you cannot create or update them through the API because they are generated automatically from platform activity. This page shows how to list, inspect, annotate, and manage contacts.

## How contacts are created

Contacts are created when campaigns discover and interact with people on Facebook. Each contact record includes profile information such as name, platform ID, bio, and the campaign that sourced the contact. Because contacts reflect real social profiles, the API does not support direct create or update operations.

## List contacts

To list contacts, send a `GET` request with your `team_id` and optional pagination parameters.

```bash theme={null}
curl -X GET "{{baseUrl}}/api/v1/contacts?team_id=1&page=1" \
  -H "Authorization: Bearer {{token}}"
```

The response includes a paginated list of contacts with details such as `id`, `name`, `platform_id`, and `campaign_id`.

## Get a contact

Retrieve a single contact by ID if you need full details or conversation history.

```bash theme={null}
curl -X GET "{{baseUrl}}/api/v1/contacts/{id}" \
  -H "Authorization: Bearer {{token}}"
```

## Notes

You can add free-text notes to a contact to record context, follow-up reminders, or internal annotations. Send a `POST` request to the contact's notes endpoint.

```bash theme={null}
curl -X POST "{{baseUrl}}/api/v1/contacts/{id}/notes" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Follow up next Tuesday about the demo."
  }'
```

You can also delete notes when they are no longer needed.

## Stages

Stages help you track where a contact sits in your pipeline. ReachOwl can move contacts between stages automatically based on campaign events, such as when a contact accepts a friend request or replies to a message. You can also view and filter contacts by stage.

For more about automating stage transitions, see the [CRM stages and templates](/api-reference/stages) endpoints.

## Related endpoints

* [`/api-reference/contacts/list`](/api-reference/contacts/list) — list contacts
* [`/api-reference/contacts/get`](/api-reference/contacts/get) — retrieve a single contact
* [`/api-reference/contacts/notes`](/api-reference/contacts/notes) — add or delete contact notes