# Fingerprint Integration

## When to use

Use this skill whenever a task requires visibility into anonymous or identified website visitors tracked by Fingerprint — deanonymized companies (accounts whose employees are browsing a site), individual visitor sessions, ICP (ideal customer profile — the set of firmographic/behavioral traits that define a good-fit buyer) fit scores, or account-level activity timelines. Reach for it to answer "who is visiting our site," to feed high-intent accounts into outbound or alerting workflows, to configure ICP scoring criteria or alert rules, or to fulfill a GDPR (General Data Protection Regulation) data-subject request (export or delete a visitor's data). Do not use it to send outbound messages to visitors — Fingerprint only tracks and identifies, it does not deliver.

## Tools

- `http-get` — read events, visitors, sessions, companies, timelines, and settings
- `http-post` — ingest events and create new ICP criteria or alert rules
- `http-request` — reserved for update/delete calls, notably deleting a visitor's data
- `write-file` — stage large result sets (visitor lists, company timelines) before further processing
- `send-message` — escalate auth failures or missing Integration configuration to a human

## Playbook

1. To find out who is actively visiting or has recently visited the site, call `http-get` against `/api/v1/visitors` to list identified visitors ordered by last-seen time, with `limit`/`offset` for pagination. Each record includes company, confidence, and ICP fit score.
2. To go deeper on one visitor, call `http-get` on `/api/v1/visitors/:id` for their profile plus recent sessions.
3. For a GDPR right-of-access request, call `http-get` on `/api/v1/visitors/:id/export` to retrieve the visitor's full data (all sessions and events), and `write-file` the result before handing it off.
4. For a GDPR right-to-erasure request, call `http-request` with DELETE on `/api/v1/visitors/:id` to permanently remove the visitor and all associated data. Confirm the request is a genuine erasure request before doing this — it is irreversible.
5. To inspect browsing behavior directly, call `http-get` on `/api/v1/sessions` for the org's sessions list, or `/api/v1/sessions/:id` for one session's detail.
6. To find which companies (deanonymized accounts) are engaging with the site, call `http-get` on `/api/v1/companies`, ordered by last-seen time.
7. For account-level intent analysis, call `http-get` on `/api/v1/companies/:id/timeline` to get the full activity timeline (sessions and events) plus a summary — total sessions, unique visitors, average intent score, and top pages. Use this to decide whether an account should be escalated (for example, into a CRM or alerting workflow).
8. To ingest new tracking events on behalf of an integration, call `http-post` on `/api/v1/events` with a `visitor_token` and an `events[]` array (each with `event_type`, `url`, `page_title`, `occurred_at`, `properties`). Events are processed asynchronously.
9. To review or extend ICP scoring, call `http-get` on `/api/v1/settings/icp_criteria` to list current criteria, or `http-post` on the same path to add a new one.
10. To review or extend alerting, call `http-get` on `/api/v1/settings/alert_rules` to list current rules, or `http-post` on the same path to add a new one (for example, to notify on high-intent company activity).
11. When a result set is large (bulk visitor lists, full company timelines spanning many sessions), use `write-file` to stage it before summarizing or passing it downstream, rather than holding it all in context.

## Failure modes

If any call returns 401 or 403, or if the org has no Integration row configured for Fingerprint, stop immediately. Do not retry with guessed credentials and do not ask the user for an API key — credentials are injected automatically by the Integration row. Instead, use `send-message` to escalate to a human, naming "Fingerprint" as the app and stating that a working Integration with the correct API key scope is needed. If a DELETE request fails, do not silently move on — escalate via `send-message`, since a failed erasure request may carry compliance implications.

## Done when

The requested visitor, session, company, or timeline data has been retrieved and (if large) staged with `write-file`; or a settings change (ICP criterion, alert rule) has been created and confirmed via a follow-up `http-get`; or a GDPR export/erasure has been completed and confirmed; or a blocking auth/configuration issue has been escalated via `send-message`.