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

# Common use cases

> Examples of how to use the Allo API to answer business questions and automate workflows

## Getting started

<AccordionGroup>
  <Accordion title="Discover what your API key can do">
    Always start by calling the capabilities endpoint:

    ```bash theme={null}
    GET /v2/api/me
    ```

    The response lists your scopes, available endpoints, team, and rate limits. Use the `endpoints` array to know which API calls you can make.
  </Accordion>
</AccordionGroup>

## Syncing data

<AccordionGroup>
  <Accordion title="CRM sync (incremental)">
    Fetch only new activity since your last sync — no need to re-fetch everything.

    ```bash theme={null}
    GET /v2/api/conversations?allo_number=%2B14155550100&last_activity_since=2026-04-20T10:00:00Z
    ```

    Store the `last_activity` timestamp from the response and use it as `last_activity_since` on the next sync.
  </Accordion>

  <Accordion title="Export all outbound calls from this quarter">
    Paginate through all results:

    ```bash theme={null}
    POST /v2/api/conversations/items/search
    {
      "date": { "from": "2026-01-01", "to": "2026-03-31" },
      "direction": "OUTBOUND",
      "type": "CALL",
      "page": 1,
      "size": 100
    }
    ```

    Increment `page` until `pagination.has_more` is `false`.
  </Accordion>
</AccordionGroup>

## Searching conversations

<AccordionGroup>
  <Accordion title="Find calls where customers mentioned billing issues">
    Keyword search across all call transcripts and summaries:

    ```bash theme={null}
    POST /v2/api/conversations/items/search
    {
      "search": "billing issues",
      "type": "CALL",
      "sort": "RELEVANCE"
    }
    ```

    Search terms are AND'd and use prefix matching — `"bill"` matches "billing", "billed", etc.
  </Accordion>

  <Accordion title="Search what we discussed about refunds with a contact">
    ```bash theme={null}
    POST /v2/api/conversations/items/search
    {
      "contact_number": "+14155551234",
      "search": "refunds",
      "sort": "RELEVANCE"
    }
    ```
  </Accordion>

  <Accordion title="Show all interactions with a contact">
    ```bash theme={null}
    POST /v2/api/conversations/items/search
    {
      "contact_number": "+14155551234"
    }
    ```

    Returns the full timeline of calls and SMS with a contact, including matched contacts, company, and deals.
  </Accordion>

  <Accordion title="Get full context on a specific call">
    ```bash theme={null}
    GET /v2/api/conversations/items/cll-abc123?extend=transcript
    ```

    Returns the call with summary, tags, recording URL, and full transcript. `transcript` is the only supported extend value.
  </Accordion>

  <Accordion title="How many calls were missed last week?">
    Use the search endpoint with `size=1` to get just the count:

    ```bash theme={null}
    POST /v2/api/conversations/items/search
    {
      "date": { "from": "2026-04-14", "to": "2026-04-21" },
      "result": "VOICEMAIL",
      "type": "CALL",
      "size": 1
    }
    ```

    Read `pagination.total_count` from the response — no need to fetch all results.
  </Accordion>

  <Accordion title="Show me qualified leads from cold calls this month">
    First, check what tags exist:

    ```bash theme={null}
    GET /v2/api/tags
    ```

    Then filter conversations by tag:

    ```bash theme={null}
    POST /v2/api/conversations/items/search
    {
      "date": { "from": "2026-04-01", "to": "2026-04-21" },
      "tags": ["qualified"],
      "direction": "OUTBOUND"
    }
    ```
  </Accordion>

  <Accordion title="Find all unread conversations on a line">
    ```bash theme={null}
    GET /v2/api/conversations?allo_number=%2B14155550100&unread=true
    ```

    The `allo_number` parameter is required. List your numbers with `GET /v2/api/numbers` to find the right one.
  </Accordion>
</AccordionGroup>

## Taking actions

<AccordionGroup>
  <Accordion title="Tag a call and then find all calls with that tag">
    ```bash theme={null}
    # 1. Tag the call
    POST /v2/api/conversations/items/cll-abc123/tags
    { "tags": ["qualified"] }

    # 2. Find all calls with that tag
    POST /v2/api/conversations/items/search
    { "tags": ["qualified"] }
    ```

    Adding a tag that already exists returns `409 TAG_ALREADY_EXISTS` — no duplicate is created.
  </Accordion>

  <Accordion title="Mark a conversation as read">
    ```bash theme={null}
    PUT /v2/api/conversations/%2B14155551234/action
    { "action": "READ" }
    ```

    To scope to a specific Allo number:

    ```bash theme={null}
    PUT /v2/api/conversations/%2B14155551234/action
    { "action": "READ", "allo_number": "+14155550100" }
    ```

    All actions are idempotent — calling `READ` on an already-read conversation is a no-op.
  </Accordion>

  <Accordion title="Archive a conversation">
    ```bash theme={null}
    PUT /v2/api/conversations/%2B14155551234/action
    { "action": "ARCHIVE" }
    ```

    This archives the contact and marks all items as read.
  </Accordion>

  <Accordion title="Send an SMS follow-up">
    SMS sending uses the v1 API endpoint:

    ```bash theme={null}
    POST /v1/api/sms
    {
      "to": "+14155551234",
      "allo_number": "+14155550100",
      "content": "Thanks for your call! Let me know if you have any other questions."
    }
    ```

    Requires the `SMS_SEND` scope. See [Send SMS](/en/v2/api-reference/sms/send-sms) for details.
  </Accordion>
</AccordionGroup>

## Analytics and reporting

<AccordionGroup>
  <Accordion title="What is my cold calling performance this week compared to last?">
    ```bash theme={null}
    # 1. Get the outbound funnel with week-over-week comparison
    POST /v2/api/analytics/outbound
    {
      "date": { "from": "2026-04-14", "to": "2026-04-21" },
      "compare_date": { "from": "2026-04-07", "to": "2026-04-14" },
      "tags": ["meeting_booked"],
      "granularity": "DAY"
    }
    ```

    The response includes the full funnel (dials, connected, conversations, conversions) with change vs last week, daily time series, heatmap, and leaderboard.

    ```bash theme={null}
    # 2. Drill into the calls that converted (use extend=items)
    POST /v2/api/analytics/outbound
    {
      "date": { "from": "2026-04-14", "to": "2026-04-21" },
      "tags": ["meeting_booked"],
      "granularity": "DAY",
      "extend": "items",
      "stage": "CONVERSION"
    }

    # 3. Get full details (summary, transcript, tags)
    POST /v2/api/conversations/items/batch
    { "ids": ["cll-abc123", "cll-def456"] }
    ```
  </Accordion>

  <Accordion title="Get team performance for last month">
    ```bash theme={null}
    POST /v2/api/analytics/overview
    {
      "date": { "from": "2026-03-01", "to": "2026-03-31" },
      "compare_date": { "from": "2026-02-01", "to": "2026-02-28" }
    }
    ```

    Returns total calls, talk time, answer rate, and per-user breakdown — all with change vs the comparison period.
  </Accordion>

  <Accordion title="Compare two reps' performance">
    ```bash theme={null}
    POST /v2/api/analytics/overview
    {
      "date": { "from": "2026-04-01", "to": "2026-04-21" },
      "compare_date": { "from": "2026-03-01", "to": "2026-03-31" },
      "user_ids": ["usr-abc123", "usr-def456"]
    }
    ```

    The breakdown in the response includes both users with their individual metrics and change vs the comparison period.
  </Accordion>

  <Accordion title="Cold calling performance for a specific line">
    ```bash theme={null}
    POST /v2/api/analytics/outbound
    {
      "date": { "from": "2026-04-01", "to": "2026-04-21" },
      "allo_numbers": ["+14155550100"],
      "tags": ["meeting_booked"],
      "granularity": "WEEK"
    }
    ```
  </Accordion>
</AccordionGroup>

## Team and setup

<AccordionGroup>
  <Accordion title="Resolve a team member name to filter conversations">
    ```bash theme={null}
    # 1. Find the user
    GET /v2/api/users

    # 2. Use their ID to filter
    POST /v2/api/conversations/items/search
    { "user_id": "usr-abc123", "type": "CALL" }
    ```
  </Accordion>

  <Accordion title="Find which Allo number to use for a country">
    ```bash theme={null}
    GET /v2/api/numbers
    ```

    Filter the response by `country` and check `capabilities` to find a number that supports the channel you need (VOICE, SMS, MMS).
  </Accordion>

  <Accordion title="List all available tags before building a report">
    ```bash theme={null}
    GET /v2/api/tags
    ```

    Use the tag names in conversation search filters or as conversion tags in analytics.
  </Accordion>
</AccordionGroup>