Attribution and Postback
Server integration guide

Integration overview#

1. 01Share links and retain attribution

   On activation, an administrator registers the referral URL and code issued by this system. The sender stores the touchpoint and attribution, and can look up historical mappings when needed.

2. 02Send user states

   Send the complete user state after signup, the first successful Link, attribution resolution or a correction.

3. 03Verify signatures, calculate rewards and reconcile

   Received events are persisted and processed asynchronously, then reconciled against a complete snapshot of the authoritative data.

There are two server integration endpoints: GET /integration/v1/referral-links/{code} for referral lookup and POST /integration/v1/events for sending user states.

Credentials and authentication#

AMBASSADOR_API_BASE_URL=https://ambassador.tanka.ai
TANKA_EVENT_KEY_ID=<issued Key ID>
TANKA_EVENT_SECRET=<issued signing Secret>
TANKA_LINK_LOOKUP_TOKEN=<issued lookup Token>

Use credentials dedicated to this integration; the receiver's own platform admin keys are not needed. Keep production Secrets out of documentation, frontend code, shared links and browsers.

When rotating keys, switch the sender to the new Key ID / Secret. The receiver can accept the old key for a limited period. Refresh the timestamp and signature on every retry while retaining the original event_id and business-data body.

Referral lookup and attribution binding#

This system issues the referral URL and code (for example https://jp.tanka.ai/?ref=JP-XXXX-XXXX), and an administrator registers them on activation. TANKA can use any code that follows the format as-is. The URL is displayed exactly as registered. Allowed domains: *.tanka.ai. The referral parameter ref is used to pre-fill the code when an administrator registers the link.

Campaign URLs issued by TANKA (for example https://t.tanka.ai/campaign/example-token) can also be registered. The trailing token is the referral code itself and is registered manually by an administrator. When sending attribution for a user who signed up through such a URL, put the token unchanged in referral_code. Do not send users of unregistered tokens; send only users tied to a registered code. The attribution rules and reward conditions are the same as for every other referral link.

This lookup API is optional. Supply the actual click time in at to check whether the historical touchpoint was valid.

curl --get "$AMBASSADOR_API_BASE_URL/integration/v1/referral-links/$REFERRAL_CODE" \
  --header "Authorization: Bearer $TANKA_LINK_LOOKUP_TOKEN" \
  --data-urlencode "at=$TOUCHED_AT"

When using lookup, the path parameter code and query parameter at are both required. In the example, set REFERRAL_CODE to the shared link's actual code and TOUCHED_AT to the click time in RFC3339 with a timezone, for example 2026-09-08T00:01:00+09:00. --data-urlencode correctly encodes the plus sign in the timezone.

{
  "program_id": "tanka-jp-ambassador",
  "ambassador_id": "11111111-1111-4111-8111-111111111111",
  "referral_link_id": "22222222-2222-4222-8222-222222222222",
  "referral_code": "JP-example-only",
  "campaign_id": "33333333-3333-4333-8333-333333333333",
  "valid": true,
  "checked_at": "2026-09-08T00:01:00+09:00",
  "model": "last_click",
  "window_days": 30,
  "rule_version": "attr-v1",
  "qualification_rule": "first-link-v1"
}

• A touchpoint is valid only when valid=true. HTTP 200 can also contain valid=false. An invalid code must not overwrite a previously valid attribution.
• The submitted referral_code is matched against the registered attribution. The three internal IDs may be omitted or null. If supplied, they must match the registration; a mismatch is held for review as mapping_mismatch.
• The sender stores a consistent touch_id and touched_at, binds them to the product's user_id when signup completes, and records bound_at.
• Retain attribution across domains, email verification and App/Web transitions. Existing-user logins, joining another team and clicking a different link after signup do not count as new signups.
• Validity is evaluated at the touchpoint time. Disabling a link does not remove attribution established before it was disabled. However, if the link is disabled or the ambassador is suspended at the time of the first Link, the reward is held as inactive_at_qualification for administrator review rather than voided.

Examples use the initial defaults last_click / 30 days / attr-v1. Use the lookup response for the mapping and rules that actually apply.

Send the complete user state#

Content-Type application/json is recommended. The UTF-8 body limit is 65,536 bytes. Send a complete snapshot with the fixed field structure each time, using null for empty values. Count increments and partial patches are not supported.

The IDs, timestamps and link_type below illustrate the structure. Replace them with actual events and registered data. This page never sends these examples to the production API automatically.

The first example, codeOnly.json, sets all three internal IDs to null. IDs shown in other examples illustrate optional fields and must be replaced with actual lookup results.

{
  "schema_version": "1.0",
  "event_id": "example.first-link.code-only",
  "event_type": "first_link_completed",
  "environment": "production",
  "program_id": "tanka-jp-ambassador",
  "user_id": "example-user-001",
  "state_version": 2,
  "occurred_at": "2026-09-08T00:05:00+09:00",
  "state_updated_at": "2026-09-08T00:05:00+09:00",
  "data": {
    "is_new_user": true,
    "registration_email": "[email protected]",
    "counting_status": "valid",
    "reason_code": null,
    "attribution": {
      "status": "attributed",
      "ambassador_id": null,
      "referral_code": "JP-example-only",
      "referral_link_id": null,
      "campaign_id": null,
      "touch_id": "example-touch-001",
      "touched_at": "2026-09-08T00:01:00+09:00",
      "bound_at": "2026-09-08T00:03:00+09:00",
      "model": "last_click",
      "window_days": 30,
      "rule_version": "attr-v1"
    },
    "milestones": {
      "signup_at": "2026-09-08T00:03:00+09:00",
      "first_link_completed_at": "2026-09-08T00:05:00+09:00"
    },
    "first_link": {
      "event_id": "example-link-success-001",
      "link_type": "calendar"
    },
    "qualification_rule_version": "first-link-v1",
    "correction": null
  }
}

{
  "schema_version": "1.0",
  "event_id": "example.signup.001",
  "event_type": "signup_completed",
  "environment": "production",
  "program_id": "tanka-jp-ambassador",
  "user_id": "example-user-001",
  "state_version": 1,
  "occurred_at": "2026-09-08T00:03:00+09:00",
  "state_updated_at": "2026-09-08T00:03:00+09:00",
  "data": {
    "is_new_user": true,
    "registration_email": "[email protected]",
    "counting_status": "valid",
    "reason_code": null,
    "attribution": {
      "status": "attributed",
      "ambassador_id": "11111111-1111-4111-8111-111111111111",
      "referral_code": "JP-example-only",
      "referral_link_id": "22222222-2222-4222-8222-222222222222",
      "campaign_id": "33333333-3333-4333-8333-333333333333",
      "touch_id": "example-touch-001",
      "touched_at": "2026-09-08T00:01:00+09:00",
      "bound_at": "2026-09-08T00:03:00+09:00",
      "model": "last_click",
      "window_days": 30,
      "rule_version": "attr-v1"
    },
    "milestones": {
      "signup_at": "2026-09-08T00:03:00+09:00",
      "first_link_completed_at": null
    },
    "first_link": null,
    "qualification_rule_version": "first-link-v1",
    "correction": null
  }
}

{
  "schema_version": "1.0",
  "event_id": "example.first-link.001",
  "event_type": "first_link_completed",
  "environment": "production",
  "program_id": "tanka-jp-ambassador",
  "user_id": "example-user-001",
  "state_version": 2,
  "occurred_at": "2026-09-08T00:05:00+09:00",
  "state_updated_at": "2026-09-08T00:05:00+09:00",
  "data": {
    "is_new_user": true,
    "registration_email": "[email protected]",
    "counting_status": "valid",
    "reason_code": null,
    "attribution": {
      "status": "attributed",
      "ambassador_id": "11111111-1111-4111-8111-111111111111",
      "referral_code": "JP-example-only",
      "referral_link_id": "22222222-2222-4222-8222-222222222222",
      "campaign_id": "33333333-3333-4333-8333-333333333333",
      "touch_id": "example-touch-001",
      "touched_at": "2026-09-08T00:01:00+09:00",
      "bound_at": "2026-09-08T00:03:00+09:00",
      "model": "last_click",
      "window_days": 30,
      "rule_version": "attr-v1"
    },
    "milestones": {
      "signup_at": "2026-09-08T00:03:00+09:00",
      "first_link_completed_at": "2026-09-08T00:05:00+09:00"
    },
    "first_link": {
      "event_id": "example-link-success-001",
      "link_type": "calendar"
    },
    "qualification_rule_version": "first-link-v1",
    "correction": null
  }
}

{
  "schema_version": "1.0",
  "event_id": "example.signup.pending",
  "event_type": "signup_completed",
  "environment": "production",
  "program_id": "tanka-jp-ambassador",
  "user_id": "example-user-pending",
  "state_version": 1,
  "occurred_at": "2026-09-08T00:03:00+09:00",
  "state_updated_at": "2026-09-08T00:03:00+09:00",
  "data": {
    "is_new_user": true,
    "registration_email": "[email protected]",
    "counting_status": "hold",
    "reason_code": "attribution_unverified",
    "attribution": {
      "status": "pending",
      "ambassador_id": null,
      "referral_code": null,
      "referral_link_id": null,
      "campaign_id": null,
      "touch_id": null,
      "touched_at": null,
      "bound_at": null,
      "model": "last_click",
      "window_days": 30,
      "rule_version": "attr-v1"
    },
    "milestones": {
      "signup_at": "2026-09-08T00:03:00+09:00",
      "first_link_completed_at": null
    },
    "first_link": null,
    "qualification_rule_version": "first-link-v1",
    "correction": null
  }
}

{
  "schema_version": "1.0",
  "event_id": "example.attribution.confirmed",
  "event_type": "attribution_updated",
  "environment": "production",
  "program_id": "tanka-jp-ambassador",
  "user_id": "example-user-pending",
  "state_version": 2,
  "occurred_at": "2026-09-08T00:04:00+09:00",
  "state_updated_at": "2026-09-08T00:04:00+09:00",
  "data": {
    "is_new_user": true,
    "registration_email": "[email protected]",
    "counting_status": "valid",
    "reason_code": null,
    "attribution": {
      "status": "attributed",
      "ambassador_id": "11111111-1111-4111-8111-111111111111",
      "referral_code": "JP-example-only",
      "referral_link_id": "22222222-2222-4222-8222-222222222222",
      "campaign_id": "33333333-3333-4333-8333-333333333333",
      "touch_id": "example-touch-001",
      "touched_at": "2026-09-08T00:01:00+09:00",
      "bound_at": "2026-09-08T00:04:00+09:00",
      "model": "last_click",
      "window_days": 30,
      "rule_version": "attr-v1"
    },
    "milestones": {
      "signup_at": "2026-09-08T00:03:00+09:00",
      "first_link_completed_at": null
    },
    "first_link": null,
    "qualification_rule_version": "first-link-v1",
    "correction": null
  }
}

{
  "schema_version": "1.0",
  "event_id": "example.correction.001",
  "event_type": "user_state_corrected",
  "environment": "production",
  "program_id": "tanka-jp-ambassador",
  "user_id": "example-user-001",
  "state_version": 3,
  "occurred_at": "2026-09-08T00:08:00+09:00",
  "state_updated_at": "2026-09-08T00:08:00+09:00",
  "data": {
    "is_new_user": true,
    "registration_email": "[email protected]",
    "counting_status": "invalid",
    "reason_code": "internal_test",
    "attribution": {
      "status": "attributed",
      "ambassador_id": "11111111-1111-4111-8111-111111111111",
      "referral_code": "JP-example-only",
      "referral_link_id": "22222222-2222-4222-8222-222222222222",
      "campaign_id": "33333333-3333-4333-8333-333333333333",
      "touch_id": "example-touch-001",
      "touched_at": "2026-09-08T00:01:00+09:00",
      "bound_at": "2026-09-08T00:03:00+09:00",
      "model": "last_click",
      "window_days": 30,
      "rule_version": "attr-v1"
    },
    "milestones": {
      "signup_at": "2026-09-08T00:03:00+09:00",
      "first_link_completed_at": "2026-09-08T00:05:00+09:00"
    },
    "first_link": {
      "event_id": "example-link-success-001",
      "link_type": "calendar"
    },
    "qualification_rule_version": "first-link-v1",
    "correction": {
      "reason_code": "internal_test",
      "reference_id": "example-audit-001",
      "supersedes_state_version": 2
    }
  }
}

Fields and business rules#

Every event JSON field is listed below with key presence, null rules and its source. Unknown fields are rejected. OpenAPI JSON, generated from the same validation schema, specifies types, lengths and basic formats.

OpenAPI JSON

• For attributed, referral_code, touch_id, touched_at and bound_at are required. ambassador_id, referral_link_id and campaign_id may be omitted or null.
• first_link and first_link_completed_at must both have values or both be null. The first Link must be at or after signup.
• Use RFC3339 timestamps with an explicit offset. T and Z are uppercase, the offset includes a colon (for example +09:00), and fractional seconds have at most 6 digits. +0900, +09, a lowercase z and 7 or more fractional digits are rejected with 400. Cross-field comparisons (touched_at ≤ signup_at ≤ bound_at ≤ state_updated_at, and state_updated_at ≥ first Link) are evaluated at second precision, so mixed precision within one event is tolerated. state_updated_at must never decrease for a user; a value older than the stored state is quarantined even with a correction. occurred_at and state_updated_at may be up to 300 seconds ahead of the receiver's current time. Backfill may contain actual historical business times.
• All ID-like fields share one character set. event_id, user_id, program_id, touch_id, referral_link_id, ambassador_id, campaign_id, rule_version, qualification_rule_version, first_link.event_id and correction.reference_id contain 1–160 letters, digits, underscores, periods, colons or hyphens ([A-Za-z0-9_.:-]) and are case-sensitive. Values containing |, @, / or spaces are rejected with 400. referral_code uses the same characters with length 1–64. Optional internal IDs must be actual UUIDs obtained from lookup.
• The first supplied registration_email is saved. Ordinary omission or null does not erase a known registration email. Replacing a known value requires a higher state version and correction. Explicit null for this key in a correction clears an incorrectly recorded email. A different email in an ordinary (non-correction) event is ignored; the first recorded value is kept. Later account email changes do not change the registration-time record. For the same user and state_version, the webhook and the backfill feed must carry byte-identical data. A different offset spelling (+09:00 versus Z) or a difference in optional-key presence alone quarantines the feed copy as VERSION_CONFLICT.
• registration_email is used by administrators to verify referrals and is not returned to ambassadors. User identity and reward deduplication continue to use user_id. Names, bank details, payment amounts and subscription information are rejected as undefined fields. Reward rates are selected using the business time.

Generate signatures and send requests#

The three headers X-Tanka-Key-Id, X-Tanka-Timestamp and X-Tanka-Signature are required. Content-Type application/json is recommended. The receiver reads the raw body bytes rather than the declared type and verifies the signature over those bytes. Set a product User-Agent (for example ambassador-postback/1.0): the edge network rejects some default library agents (for example Python-urllib/3.x) with HTTP 403 before the request reaches the receiver.

message = ASCII(timestamp) + ASCII(".") + raw_body_bytes
signature = lowercase_hex(HMAC_SHA256(UTF8(secret), message))

Send exactly the bytes that were signed. Do not change JSON formatting, line breaks, field order or encoding after signing. The clock tolerance is 300 seconds; keep server clocks synchronized. HTTPS protects transport, while HMAC verifies key possession and body integrity. Duplicate deliveries are deduplicated per event.

// Node.js 20+ / ESM. Run: node postback.mjs approved-real-event.json
import { readFileSync } from "node:fs";
import { createHmac } from "node:crypto";

function required(name) {
  const value = process.env[name];
  if (!value) throw new Error("Missing environment variable: " + name);
  return value;
}
if (!process.argv[2]) throw new Error("Pass the path to a real event JSON file");
const url = new URL("/integration/v1/events", required("AMBASSADOR_API_BASE_URL"));
if (url.protocol !== "https:") throw new Error("HTTPS is required");
const keyId = required("TANKA_EVENT_KEY_ID");
const secret = required("TANKA_EVENT_SECRET");
const body = readFileSync(process.argv[2]);
JSON.parse(body.toString("utf8")); // Keep the ORIGINAL bytes for signing and sending.
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = createHmac("sha256", secret)
  .update(timestamp).update(".").update(body).digest("hex");

const response = await fetch(url, {
  method: "POST",
  redirect: "error",
  signal: AbortSignal.timeout(15000),
  headers: {
    "Content-Type": "application/json",
    // Send an explicit product User-Agent: the edge blocks a few generic library agents (e.g. Python-urllib).
    "User-Agent": "ambassador-postback/1.0",
    "X-Tanka-Key-Id": keyId,
    "X-Tanka-Timestamp": timestamp,
    "X-Tanka-Signature": signature,
  },
  body,
});
console.log("HTTP " + response.status + " " + (await response.text()).slice(0, 4096));
if (![200, 202].includes(response.status)) process.exitCode = 1;
// Queue retries outside this example. Keep event_id/body, refresh timestamp/signature.

# Python 3.10+, standard library. Run: python3 postback.py approved-real-event.json
import hashlib
import hmac
import json
import os
from pathlib import Path
import sys
import time
import urllib.error
import urllib.parse
import urllib.request

def required(name):
    value = os.environ.get(name)
    if not value:
        raise SystemExit("Missing environment variable: " + name)
    return value

if len(sys.argv) != 2:
    raise SystemExit("Pass the path to a real event JSON file")
url = urllib.parse.urljoin(required("AMBASSADOR_API_BASE_URL"), "/integration/v1/events")
if urllib.parse.urlparse(url).scheme != "https":
    raise SystemExit("HTTPS is required")
key_id = required("TANKA_EVENT_KEY_ID")
secret = required("TANKA_EVENT_SECRET")
body = Path(sys.argv[1]).read_bytes()
json.loads(body)  # Keep the ORIGINAL bytes for signing and sending.
timestamp = str(int(time.time()))
signature = hmac.new(secret.encode("utf-8"), timestamp.encode("ascii") + b"." + body,
                     hashlib.sha256).hexdigest()

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(url, data=body, method="POST", headers={
    "Content-Type": "application/json",
    # Explicit product User-Agent: the edge rejects urllib's default "Python-urllib/x.y" with HTTP 403.
    "User-Agent": "ambassador-postback/1.0",
    "X-Tanka-Key-Id": key_id,
    "X-Tanka-Timestamp": timestamp,
    "X-Tanka-Signature": signature,
})
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=15)
except urllib.error.HTTPError as error:
    response = error
with response:
    status = response.code
    print("HTTP", status, response.read(4096).decode("utf-8", errors="replace"))
if status not in (200, 202):
    raise SystemExit(1)
# Queue retries outside this example. Keep event_id/body, refresh timestamp/signature.

The examples read the body from a file and credentials from server environment variables, then send once. Production senders need a persistent queue, failure alerts and retry handling. OpenAPI's security definitions describe the headers; the sender must implement signing.

Responses, retries and corrections#

Persist business data and the send task before background delivery. Increase retry delays progressively, for example 5 seconds, 30 seconds, 2 minutes and 10 minutes, with jitter. Move expired failures to a review queue. A timeout alone is not a reason to generate a new event ID.

An older version cannot overwrite a newer state for the same user. Different content at the same version is quarantined during asynchronous processing. HTTP 202 does not guarantee a reconciliation match. A new event ID does not create duplicate rewards for the same user. Corrections require a new event_id, a higher state_version and a traceable correction. Confirmed line items may be adjusted through a later difference entry. Attribution is fixed at signup. An ordinary event without a correction that moves an attributed user to pending / unattributed, or changes the referral_code, is quarantined as FACT_CONFLICT.

Backfill and reconciliation API#

The ambassador system periodically retrieves the integration partner's API with GET. The receiver is configured with the full feed URL and the dedicated Bearer Token you provide.

GET <partner feed URL>?program_id=tanka-jp-ambassador&limit=500&cursor=<next cursor>
Authorization: Bearer <backfill Token>

{
  "items": [
    {
      "schema_version": "1.0",
      "event_id": "example.first-link.001",
      "event_type": "first_link_completed",
      "environment": "production",
      "program_id": "tanka-jp-ambassador",
      "user_id": "example-user-001",
      "state_version": 2,
      "occurred_at": "2026-09-08T00:05:00+09:00",
      "state_updated_at": "2026-09-08T00:05:00+09:00",
      "data": {
        "is_new_user": true,
        "registration_email": "[email protected]",
        "counting_status": "valid",
        "reason_code": null,
        "attribution": {
          "status": "attributed",
          "ambassador_id": "11111111-1111-4111-8111-111111111111",
          "referral_code": "JP-example-only",
          "referral_link_id": "22222222-2222-4222-8222-222222222222",
          "campaign_id": "33333333-3333-4333-8333-333333333333",
          "touch_id": "example-touch-001",
          "touched_at": "2026-09-08T00:01:00+09:00",
          "bound_at": "2026-09-08T00:03:00+09:00",
          "model": "last_click",
          "window_days": 30,
          "rule_version": "attr-v1"
        },
        "milestones": {
          "signup_at": "2026-09-08T00:03:00+09:00",
          "first_link_completed_at": "2026-09-08T00:05:00+09:00"
        },
        "first_link": {
          "event_id": "example-link-success-001",
          "link_type": "calendar"
        },
        "qualification_rule_version": "first-link-v1",
        "correction": null
      }
    }
  ],
  "next_cursor": null,
  "watermark": "2026-09-08T00:06:00+09:00",
  "snapshot_id": "example-snapshot-001",
  "complete": true
}

• Return the complete state of every user related to this program as of watermark, including pending attribution, invalidated, revoked and corrected states. Aggregate counts or a list of valid users alone cannot be reconciled. Every user_id ever reported must keep appearing in the feed. Express a deleted or merged user as a correction with counting_status=invalid. A missing known user results in RECONCILE_DIFFERENCE and blocks monthly confirmation.
• items contains at most 500 entries per page. Return complete events, or complete user states containing environment / program_id / user_id / state_version / state_updated_at / data. A single invalid item (an unknown key, a different environment or program_id, or a business time further ahead of the receiver's current time than the tolerance) fails the whole run with FEED_ITEM_REJECTED, and retrieval restarts from the beginning of the snapshot.
• next_cursor=null marks the end. Even on the final page, do not omit the next_cursor key; return an explicit null (a missing key fails the whole page). Omit cursor on the first request and pass the returned cursor unchanged for subsequent pages. Returning the same cursor value again fails with REPEATED_CURSOR. An empty page is not an end marker.
• Keep watermark and the snapshot identifier fixed throughout retrieval of a snapshot. Every state update time must be at or before watermark to prevent omissions caused by changes during pagination.
• The page envelope is strict. The only allowed top-level keys are items, next_cursor, watermark, snapshot_id and complete; any other key fails the whole page. snapshot_id is optional; when omitted, watermark identifies the snapshot. complete is also optional, but if present it must agree with whether this is the final page.
• Each page is limited to 4 MiB, with at most 2,000 pages. If another page exists beyond this limit, reconciliation fails with FEED_TOO_LONG. Requests time out after 30 seconds and do not follow redirects. After failure, retrieval restarts at the beginning of the snapshot and already received data is deduplicated.
• Monthly confirmation requires a complete reconciliation within the last 24 hours and a watermark covering the end of the previous month. Ordinary CSV/JSON imports do not establish completeness.