---
title: "Record how this account first arrived (first touch)"
method: POST
path: "/v1/auth/attribution"
tags: ["auth"]
---

# Record how this account first arrived (first touch)

`POST /v1/auth/attribution`

## Request

- Base URL: `https://api.hyperresearch.ai`
- URL: `https://api.hyperresearch.ai/v1/auth/attribution`
- Auth: API key in cookie `hr_session`

Session + CSRF required. The console posts the utm_* parameters and Google click id (gclid, gbraid, wbraid) the visitor first arrived with, once, after the account exists. Write-once: the first post wins and later posts return `recorded: false`. Accepted only within 24 hours of the account being created, so a later ad click never rewrites how an existing account came to us.

## Request body

- AuthAttributionRequest
  - `utm_source` string, nullable
  - `utm_medium` string, nullable
  - `utm_campaign` string, nullable
  - `utm_term` string, nullable
  - `utm_content` string, nullable
  - `gclid` string, nullable
  - `gbraid` string, nullable
  - `wbraid` string, nullable
  - `landing_path` string, nullable
  - `first_seen_at` string, nullable

## Response `200`

What was stored

- AuthAttributionResult
  - `recorded` boolean, required
  - `reason` 'already_recorded' | 'account_too_old' | 'nothing_to_record'

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `403`: Insufficient scope or plan
- `404`: Not found
- `429`: Rate limited or over quota
- `500`: Internal error

---

[API](https://skmtc.dev/hyperresearch/apis/hyperresearch-cloud-api.md) · [All operations](https://skmtc.dev/hyperresearch/apis/hyperresearch-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hyperresearch/apis/hyperresearch-cloud-api/revisions/726ef831ebf4?raw)