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.

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.

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.

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 endpoints.

Related endpoints

• /api-reference/contacts/list — list contacts
• /api-reference/contacts/get — retrieve a single contact
• /api-reference/contacts/notes — add or delete contact notes