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

# Contacts and call data

> Screen-pop by number, keep contacts in step with your CRM, and export calls.

## Who is calling: screen-pop

```bash theme={null}
curl "https://api.your-host/api/v1/contacts/lookup?number=0412345678" \
  -H "authorization: Bearer $FIRETONE_KEY"
```

The number can be in any form: national (`0412 345 678`) or international
(`+61412345678`). The response contains:

* the contact, including your `external_ref`;
* their open tickets;
* the last five conversation summaries;
* the last call.

An unknown number returns `404`.

Pair it with the `call.ringing` or `call.answered` webhook to pop the record
as the phone rings.

## Keep contacts in step with your CRM

Use your own id for the contact in the URL:

```bash theme={null}
curl -X PUT https://api.your-host/api/v1/contacts/by-reference/crm-4411 \
  -H "authorization: Bearer $FIRETONE_KEY" -H 'content-type: application/json' \
  -d '{ "e164": "+61412345678", "name": "Sam Taylor", "attributes": { "tier": "gold" }, "dnc": false }'
```

* **Already known by that reference:** it's updated, and `attributes` merge
  into the ones it has.
* **New reference, but someone already has the number:** that contact takes
  the reference, so nothing is duplicated.
* **Otherwise:** it's created (`201`), and `contact.created` is sent.
* **A number that belongs to a contact with a different reference** is
  refused with `409`.

## Export calls

```bash theme={null}
curl "https://api.your-host/api/v1/cdrs/export?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z&format=csv" \
  -H "authorization: Bearer $FIRETONE_KEY" -o september.csv
```

* **Formats:** CSV with a header row, or `format=ndjson` for one JSON object
  per line.
* **At most 31 days per request**, streamed oldest first.
* **Columns:**
  * the call: `call_uuid`, direction, the numbers, `started_at`,
    `answered_at`, `ended_at`, `duration_sec`, `billsec`, `hangup_cause`;
  * who handled it: agent, extension and team;
  * links: `contact_id`, `campaign_id` and your `reference`;
  * whether it was `recorded`;
  * the charge (`sell_amount`), which is empty unless the key may see
    billing.
* **Scope:** narrowed like the call list, so a supervisor's key gets their
  teams' calls.