Record first-touch ad-spend attribution for the current admin

POST

/api/me/attribution/

curl --request POST \
  --url http://localhost:8000/api/me/attribution/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "utm_source": "instagram", "utm_medium": "paid_social", "utm_campaign": "spring_launch_2026", "utm_content": "carousel_a", "utm_term": "runners_25_34", "fbclid": "IwAR0xExampleClickId", "landed_at": 1749038400000, "referrer": "https://l.instagram.com/", "via_share_token": "" }'

• Local development
• Production

Stamps first-touch acquisition fields (utm_*, gclid / fbclid, signup_landed_at, signup_referrer, via_share_token) on the signed-in admin. The web client posts this once after registration, from the attribution it captured at landing and persisted in localStorage. First-touch wins: each field is written only when currently empty, so a later visit on a different campaign never overwrites the original, and re-posting is an idempotent no-op (updated=false). Writes regardless of analytics-consent state — these are non-personal campaign / source values needed for ad-spend reconciliation even when GA4 telemetry is declined. An empty payload (direct / organic signup) is accepted and writes nothing.

Authorizations

• ApiKeyBearer
• localJwtAuth
• FirebaseBearer
• FirebaseSessionCookie

Request Body

First-touch ad-spend attribution posted once by the web client after registration (#101). Every field optional — a direct / organic signup posts a near-empty object. Server-side first-touch wins: the service writes a field only when the Admin’s value is still empty, so a later campaign can’t clobber the original.

object

utm_source

string

<= 64 characters

utm_medium

string

<= 64 characters

utm_campaign

string

<= 128 characters

utm_content

string

<= 128 characters

utm_term

string

<= 128 characters

gclid

string

<= 255 characters

fbclid

string

<= 255 characters

landed_at

integer

referrer

string

<= 512 characters

via_share_token

string

<= 64 characters

Examples

ExampleInstagramPaid-socialFirstTouch

First-touch attribution payload

{
  "utm_source": "instagram",
  "utm_medium": "paid_social",
  "utm_campaign": "spring_launch_2026",
  "utm_content": "carousel_a",
  "utm_term": "runners_25_34",
  "fbclid": "IwAR0xExampleClickId",
  "landed_at": 1749038400000,
  "referrer": "https://l.instagram.com/",
  "via_share_token": ""
}

First-touch ad-spend attribution posted once by the web client after registration (#101). Every field optional — a direct / organic signup posts a near-empty object. Server-side first-touch wins: the service writes a field only when the Admin’s value is still empty, so a later campaign can’t clobber the original.

object

utm_source

string

<= 64 characters

utm_medium

string

<= 64 characters

utm_campaign

string

<= 128 characters

utm_content

string

<= 128 characters

utm_term

string

<= 128 characters

gclid

string

<= 255 characters

fbclid

string

<= 255 characters

landed_at

integer

referrer

string

<= 512 characters

via_share_token

string

<= 64 characters

Example^generated

utm_source=example&utm_medium=example&utm_campaign=example&utm_content=example&utm_term=example&gclid=example&fbclid=example&landed_at=1&referrer=example&via_share_token=example

First-touch ad-spend attribution posted once by the web client after registration (#101). Every field optional — a direct / organic signup posts a near-empty object. Server-side first-touch wins: the service writes a field only when the Admin’s value is still empty, so a later campaign can’t clobber the original.

object

utm_source

string

<= 64 characters

utm_medium

string

<= 64 characters

utm_campaign

string

<= 128 characters

utm_content

string

<= 128 characters

utm_term

string

<= 128 characters

gclid

string

<= 255 characters

fbclid

string

<= 255 characters

landed_at

integer

referrer

string

<= 512 characters

via_share_token

string

<= 64 characters

Responses

200

Media typeapplication/json

updated = this call actually wrote first-touch fields; false = idempotent no-op (already attributed, or empty payload).

object

updated

required

boolean

Examples

ExampleFirstTouchRecorded

Attribution written (first touch)

{
  "updated": true
}

400

Media typeapplication/json

object

detail

required

Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).

string

Example^generated

{
  "detail": "example"
}

401

Media typeapplication/json

object

detail

required

Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).

string

Example^generated

{
  "detail": "example"
}

403

Media typeapplication/json

object

detail

required

Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).

string

Example^generated

{
  "detail": "example"
}