Develop Integration

Developer Integration Guide

This document outlines the API integration required to track creator-led acquisitions for the sticky user acquisition campaign. We are utilizing a No-SDK, Probabilistic Matching approach to attribute sticky users to specific creators.

Overview of the Logic

1. Web Click: A user clicks a creator's link (e.g., getcultd.com/lambo/[creator_id]). CULTD captures their "fingerprint" (IP + User Agent) and redirects them to the App Store/Google Play or webpage.
2. The Handshake: When the user opens your app for the first time, the app pings CULTD via endpoints (see below). We match the app user to the web click.
3. The Conversion: When the user completes the action (KYC, subscription, in-app purchase), the app notifies CULTD via endpoints (see below) to trigger the creator bounty.

1. The Handshake (Identity Match)

Endpoint: POST https://api.getcultd.com/api/sticky/v1/identify

When to call: Execute this request on the first app launch after installation, or sign up.

Request Body:

{
  "deviceModel": "iPhone15,3",
  "osVersion": "17.4"
}

Note: Our backend automatically extracts the Public IP from the request headers (X-Forwarded-For).

Note on IP Matching: You do not need to pass an "ip" field in the request body. Our system automatically captures the public IP from the request header. However, do not proxy this request through your own backend; the call must come directly from the user's device so we can see their true connection IP.

Important: This request must be sent directly from the mobile client to our API. If you route this call through your own server, we will see your server's IP instead of the user's, and the match will fail.

Why we do it this way

• Reduces Friction: Your developer doesn't have to integrate a third-party service just to find the user's IP address.
• Accuracy: It ensures the IP we see from the app is the exact same one the web browser saw, reducing "mismatches" caused by different lookup methods.

Processing Requirements

• Storage: If the response returns a clickId, you must save this ID in Persistent Local Storage (iOS Keychain or Android SharedPreferences).
• Persistence: This ID must survive app kills and re-installs to ensure the conversion is tracked when the purchase eventually happens.

Response

• Success (Match found): { "clickId": "uuid-string-123" }
• No Match: { "clickId": null }

2. Conversion Reporting

Endpoint: POST https://api.getcultd.com/api/sticky/v1/conversion

When to call: Execute only after a successful $100 subscription payment is confirmed.

Headers:

X-CULTD-SECRET: [Your_Provided_Shared_Secret]
Content-Type: application/json

Request Body:

{
  "clickId": "uuid-string-123",
  "email": "user@email.com"
}

Security & Validation

• Unique Constraint: Our system will only accept one conversion per clickId to prevent duplicate bounty claims.
• Anti-Gaming: Transactions occurring less than 60 seconds after the identify call may be flagged for manual review.

3. Cancellations Handling

Endpoint: POST https://api.getcultd.com/api/sticky/v1/cancelled

Purpose: Trigger this when a subscription gets cancelled within a 30 days window.

Business use: Your users can cancel their subscriptions as per Apple/Google market policies, request a refund, or make another action that cancels their target action. Use this endpoint to decrease rewards to the influencer.

Headers:

X-CULTD-SECRET: [Your_Provided_Shared_Secret]
Content-Type: application/json

Request Body:

{
  "clickId": "uuid-string-123"
}

Security & Validation

• Unique Constraint: Our system will only accept one cancellation per clickId to prevent duplicate cancellation claims.
• Anti-Gaming: Transactions occurring less than 60 seconds after the identify call may be flagged for manual review.