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

# Contact tools

> Parameters, responses, fields, and event types for the 6 read-only tools that describe your audience.

Every contact tool is read only. None of them send a message, change a contact, or export a list. All times come back twice: `occurred_at` in UTC (ISO 8601) and `occurred_at_local` in the account's time zone.

```mermaid theme={null}
flowchart LR
  O["audience_overview<br/>totals"] --> S["search_contacts<br/>a page of cards"]
  S --> G["get_contact<br/>one full contact"]
  G --> T["contact_timeline<br/>every event, paged"]
  A["audience_activity<br/>counts across a range"]
  D["describe_contact_fields<br/>what can be known"]
```

## Audience overview

`fanaura.audience_overview` returns contact totals. No parameters.

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="total" type="number">All contacts on the account.</ResponseField>
    <ResponseField name="new_this_week" type="number">Contacts who joined in the last 7 days.</ResponseField>
    <ResponseField name="with_email" type="number">Contacts with an email address.</ResponseField>
    <ResponseField name="with_phone" type="number">Contacts with a phone number.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">
  For example, "You have 412 contacts, including 37 new this week."
</ResponseField>

## Search contacts

`fanaura.search_contacts` finds or ranks contacts. Each card holds the summary, identity fields, and the three newest timeline events. For the full story, call `get_contact`.

<ParamField body="query" type="string">
  A fragment of a name, email, phone, or Instagram handle.
</ParamField>

<ParamField body="filters" type="object">
  Map of field key to exact value, such as `{ "city": "Austin" }`. Keys come from `describe_contact_fields`. Computed fields cannot be filtered.
</ParamField>

<ParamField body="sort" type="string" default="created_at">
  A stored field key to sort by.
</ParamField>

<ParamField body="order" type="'newest' | 'oldest'" default="newest">
  Sort direction.
</ParamField>

<ParamField body="limit" type="number" default="20">
  Page size, from 1 to 50.
</ParamField>

<ParamField body="cursor" type="string">
  The `next_cursor` from the previous page.
</ParamField>

<ParamField body="journey_id" type="string">
  Only contacts who visited this journey's link.
</ParamField>

<ParamField body="source" type="string">
  Stored source code, such as `instagram_dm`.
</ParamField>

<ParamField body="after" type="string">
  ISO 8601. Contacts created at or after this time.
</ParamField>

<ParamField body="before" type="string">
  ISO 8601. Contacts created at or before this time.
</ParamField>

<ParamField body="min_visits" type="number">
  Only contacts with at least this many link visits.
</ParamField>

<ParamField body="rank_by_visits" type="boolean">
  `true` to rank contacts by journey link visits. Uses `limit`, default 5, and ignores the other filters.
</ParamField>

<ResponseField name="contacts" type="object[]">
  <Expandable title="card">
    <ResponseField name="contact_id" type="string">Fanaura contact UUID.</ResponseField>
    <ResponseField name="summary" type="string">A written paragraph about the contact.</ResponseField>
    <ResponseField name="identity" type="object">Name, Instagram handle, join date, and other identity fields that have a value.</ResponseField>
    <ResponseField name="timeline" type="object[]">The three newest events.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_cursor" type="string | null">
  Pass this back as `cursor` for the next page. `null` on the last page.
</ResponseField>

## Get contact

`fanaura.get_contact` returns one contact in full. Pass exactly one lookup.

<ParamField body="contact_id" type="string">Fanaura contact UUID.</ParamField>
<ParamField body="handle" type="string">Instagram handle, with or without `@`.</ParamField>
<ParamField body="phone" type="string">Phone number as stored.</ParamField>
<ParamField body="email" type="string">Email address. Case does not matter.</ParamField>
<ParamField body="order" type="'oldest' | 'newest'" default="oldest">Timeline order.</ParamField>

<ResponseField name="summary" type="string" required>
  A paragraph written from the contact's data: who they are, when they joined, how they found you, where they were, what they told you, how to reach them, and their engagement.
</ResponseField>

<ResponseField name="identity, acquisition, reach, location, device, profile, engagement, commerce, rewards" type="object">
  Field groups. Only fields with a value appear. Each field is `{ label, value, provenance }`, plus `local` for timestamps.
</ResponseField>

<ResponseField name="missing" type="object" required>
  <Expandable title="properties">
    <ResponseField name="asked_unanswered" type="object[]">Fields a journey asked for that the contact has not answered.</ResponseField>
    <ResponseField name="not_asked" type="object[]">Fields no journey has asked this contact for yet.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timeline" type="object[]" required>
  Every event. See the [event shape](#event-shape).
</ResponseField>

<ResponseExample>
  ```json get_contact theme={null}
  {
    "success": true,
    "summary": "Jordan Lee joined Tue, Mar 3, 8:14 PM. They found you by commenting on Instagram. They were in Austin, TX, US on iPhone. You can reach them at jordan@example.com. Their engagement score is 32, across 3 link visits.",
    "identity": {
      "first_name": { "label": "First name", "value": "Jordan", "provenance": "self_reported" },
      "instagram_handle": { "label": "Instagram handle", "value": "@jordan", "provenance": "enriched" },
      "created_at": { "label": "Joined", "value": "2026-03-04T02:14:00.000Z", "provenance": "enriched", "local": "Tue, Mar 3, 8:14 PM" }
    },
    "location": {
      "city": { "label": "City", "value": "Austin", "provenance": "inferred" }
    },
    "missing": {
      "asked_unanswered": [{ "key": "phone", "label": "Phone" }],
      "not_asked": [{ "key": "birthday", "label": "Birthday" }]
    },
    "timeline": [
      {
        "id": "entry:91c...",
        "type": "instagram_comment",
        "label": "Commented on Instagram",
        "occurred_at": "2026-03-04T02:13:41.000Z",
        "occurred_at_local": "Tue, Mar 3, 8:13 PM",
        "journey": { "id": "2f6c...", "name": "Free Guide" },
        "channel": "Commented on Instagram",
        "visit_number": null,
        "details": [{ "label": "Started journey", "value": "Free Guide" }]
      }
    ]
  }
  ```
</ResponseExample>

## Contact timeline

`fanaura.contact_timeline` pages through a long history, 50 events at a time.

<ParamField body="contact_id" type="string" required>Fanaura contact UUID.</ParamField>
<ParamField body="after" type="string">ISO 8601. Events at or after this time.</ParamField>
<ParamField body="before" type="string">ISO 8601. Events at or before this time.</ParamField>
<ParamField body="types" type="string[]">Event types to keep, such as `["link_returned", "journey_submitted"]`.</ParamField>
<ParamField body="order" type="'oldest' | 'newest'" default="oldest">Event order.</ParamField>
<ParamField body="cursor" type="string">The `next_cursor` from the previous page.</ParamField>

<ResponseField name="timeline" type="object[]">Up to 50 events.</ResponseField>
<ResponseField name="next_cursor" type="string | null">The next page, or `null`.</ResponseField>

### Event shape

<ResponseField name="id" type="string">Stable event ID.</ResponseField>
<ResponseField name="type" type="string">Event type from the table below.</ResponseField>
<ResponseField name="label" type="string">Plain action, such as "Came back to your link".</ResponseField>
<ResponseField name="occurred_at" type="string">ISO 8601 in UTC.</ResponseField>
<ResponseField name="occurred_at_local" type="string">The same time in the account's time zone.</ResponseField>
<ResponseField name="journey" type="object | null">`{ id, name }` when the event belongs to a journey.</ResponseField>
<ResponseField name="channel" type="string | null">How the contact reached you, on entry events.</ResponseField>
<ResponseField name="visit_number" type="number | null">1 for the first link visit, 2 for the next, and so on.</ResponseField>

<ResponseField name="details" type="object[]">
  Every detail from that moment, as `{ label, value }`. Link visits include place, referring site, the app they came from, device, language, and "Visit 2 of 5". Journey submissions include each answer.
</ResponseField>

## Audience activity

`fanaura.audience_activity` counts activity across the whole audience. It returns numbers, not people.

<ParamField body="after" type="string">ISO 8601 start of the range.</ParamField>
<ParamField body="before" type="string">ISO 8601 end of the range.</ParamField>
<ParamField body="field" type="string">A stored field key to break down, such as `city` or `vip_status`.</ParamField>

<ResponseField name="new_contacts_per_day" type="object[]">`{ key: "2026-09-14", count: 12 }`, largest first.</ResponseField>
<ResponseField name="events_by_type" type="object[]">Counts by event label.</ResponseField>
<ResponseField name="by_journey" type="object[]">Link visits by journey ID.</ResponseField>
<ResponseField name="by_source" type="object[]">Link visits by the app people came from.</ResponseField>
<ResponseField name="by_city" type="object[]">Link visits by city.</ResponseField>
<ResponseField name="by_device" type="object[]">Link visits by device.</ResponseField>
<ResponseField name="by_field" type="object">Present when `field` is passed: `{ field, values }`.</ResponseField>
<ResponseField name="truncated" type="boolean">`true` when a range held more than 5,000 rows. Narrow the range for exact counts.</ResponseField>

## Describe contact fields

`fanaura.describe_contact_fields` lists every field Fanaura can hold, with `contacts_with_value` for stored fields, and every event type. Use it to answer "What can I know about my fans?" No parameters.

<ResponseField name="fields" type="object[]">
  `{ key, label, category, type, privacy, provenance, contacts_with_value }`. Computed fields return `contacts_with_value: null`.
</ResponseField>

<ResponseField name="events" type="object[]">
  `{ type, label, sheet }`. `sheet: true` marks the main events shown on a contact's timeline in the Fanaura iPhone app.
</ResponseField>

## Field reference

<Tabs>
  <Tab title="Identity">
    | Key | Label | Provenance |
    | - | - | - |
    | `first_name`, `middle_name`, `last_name` | Name | self\_reported |
    | `instagram_handle` | Instagram handle | enriched |
    | `instagram_display_name` | Instagram display name | enriched |
    | `instagram_follower_count` | Instagram followers | enriched |
    | `instagram_is_verified` | Instagram verified | enriched |
    | `instagram_follows_artist` | Follows you on Instagram | enriched |
    | `instagram_biography`, `instagram_website` | Instagram bio and website | enriched |
    | `created_at` | Joined | enriched |
  </Tab>

  <Tab title="Reach">
    | Key | Label | Provenance |
    | - | - | - |
    | `email`, `secondary_email` | Email | self\_reported |
    | `phone` | Phone | self\_reported |
    | `preferred_contact` | Preferred contact method | self\_reported |
    | `email_opt_in`, `sms_opt_in`, `whatsapp_opt_in`, `marketing_opt_in` | Opt-ins | self\_reported |
    | `phone_verified`, `verified_email` | Verified | enriched |
    | `phone_line` | Phone line, such as mobile | enriched, computed |
    | `email_type` | Email type, such as personal | enriched, computed |
  </Tab>

  <Tab title="Location and device">
    | Key | Label | Provenance |
    | - | - | - |
    | `city`, `state`, `country` | Place | inferred, or self\_reported when typed |
    | `timezone` | Time zone | inferred |
    | `device` | Device | enriched, computed |
    | `language` | Language | enriched, computed |
  </Tab>

  <Tab title="Profile">
    | Key | Label | Provenance |
    | - | - | - |
    | `birthday` | Birthday | self\_reported |
    | `tshirt_size` | T-shirt size | self\_reported |
    | `favorite_song` | Favorite song | self\_reported |
    | `preferred_streaming_platform` | Streaming service | self\_reported |
    | Custom journey questions | Your own label | self\_reported |
  </Tab>

  <Tab title="Acquisition">
    | Key | Label | Provenance |
    | - | - | - |
    | `source` | Source, such as "Commented on Instagram" | enriched |
    | `referrer` | Referring site | enriched, computed |
    | `campaign` | Campaign | enriched, computed |
    | `referral_code` | Referral code | imported |
  </Tab>

  <Tab title="Engagement and more">
    | Key | Label | Provenance |
    | - | - | - |
    | `engagement_score` | Engagement score, 0 to 100 | enriched |
    | `total_interactions` | Interactions | enriched |
    | `last_interaction_date` | Last interaction | enriched |
    | `total_presaves`, `total_rsvps`, `total_merch_orders` | Commerce counts | enriched |
    | `vip_status`, `rewards_status`, `token_balance` | Rewards | imported |
  </Tab>
</Tabs>

## Event types

The main events, shown on a contact's timeline in the Fanaura iPhone app:

| Type | Label |
| - | - |
| `instagram_comment` | Commented on Instagram |
| `instagram_dm` | Sent an Instagram message |
| `sms_received` | Sent a text |
| `email_received` | Sent an email |
| `link_opened` | Opened your link |
| `link_returned` | Came back to your link |
| `journey_submitted` | Filled out your journey |

Other recorded events include `music.presave` (Pre-saved a release), `qr.scanned` (Scanned a QR code), `merch.purchased` (Bought merch), `capture.submitted` (Submitted a capture form), `fan.email_clicked` (Tapped an email link), and `sms.link_clicked` (Tapped a text link). Call `describe_contact_fields` for the complete list.

<Note>
  Session tokens, one-time codes, and platform tokens are never returned by any tool. Read [Data and privacy](/mcp-server/data-and-privacy).
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.