> For the complete documentation index, see [llms.txt](https://docs.replycorp.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.replycorp.io/integration-guide.md). # Integration Guide What your developers build, step by step — matched to the setup checklist in the ReplyCorp dashboard, with Rewards-only work clearly separated. ### TL;DR: Integration Effort | What you're setting up | Engineering work | Complexity | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------- | | **Conversion Intelligence (core)** | One server-side API call per conversion, with the buyer's social identity (X user ID, or Instagram verification code) | Easy–Moderate | | **Rewards add-on (on top of CI)** | Add one field (`commission`) to that same API call | Easy | | **Social Connect embed (optional)** | Drop-in script / GTM tag so visitors link their X or Instagram account on your site | Easy | **The core integration is identical whether or not you run a Rewards campaign.** Rewards adds dashboard configuration (reward amounts, brand profile, funding) and exactly one engineering change: sending a `commission` value on conversions that should earn rewards. *** ### How this guide maps to the dashboard The ReplyCorp dashboard walks your team through a guided setup checklist. This guide uses the **same step names**, so your product team (working from the dashboard) and your developers (working from these docs) can cross-reference directly. | Dashboard step | Who does it | Covered in | | ---------------------------------- | -------------------- | -------------- | | Add your team | Admin (dashboard) | Part 1, step 0 | | Connect brand socials | Admin (dashboard) | Part 1, step 1 | | Choose what to track | Product + developers | Part 1, step 2 | | Collect customers' social accounts | Developers | Part 1, step 3 | | Send a test conversion | Developers | Part 1, step 4 | | Check your test results | Automatic | Part 1, step 5 | | Connect your live app | Developers | Part 1, step 6 | | Activate Conversion Intelligence | Admin (dashboard) | Part 1, step 7 | | *Rewards: Set reward amounts* | Product + developers | Part 2, step 1 | | *Rewards: Set up brand profile* | Admin (dashboard) | Part 2, step 2 | | *Rewards: Add money for rewards* | Admin (dashboard) | Part 2, step 3 | | *Rewards: Activate Rewards* | Admin (dashboard) | Part 2, step 4 | *** ## Part 1 — Core integration (Conversion Intelligence) This is everything needed to get Conversion Intelligence live. **No payment setup, no commission, and no rewards configuration is required for this part.** #### Step 0: Account setup & team * **Contact ReplyCorp** to request access; ReplyCorp registers your organization and creates your account. * **Log into the dashboard** and invite the developers who will do the integration (the *Add your team* step), so they can retrieve the API key and campaign ID themselves. **What you provide to ReplyCorp:** organization name and slug, admin email address, and the brand social handle(s) to track. > **Tip:** You can also use the **@ReplyCorpBot** Telegram bot for guided setup and ongoing campaign management. See the Telegram Bot documentation. #### Step 1: Connect brand socials (dashboard) An admin connects your brand's **X and/or Instagram** account in the dashboard. This tells ReplyCorp *which posts to monitor* — it is unrelated to the buyer identities your developers send in Step 3. No engineering work. #### Step 2: Choose what to track Before writing code, decide with your product team: * Which backend event(s) represent the conversions you want to track (purchases, signups, token locks, …) * Where those events occur in your system * What value (`amount`) should be associated with each conversion, if applicable * Which social identity belongs to the converting user #### Step 3: Collect customers' social accounts ReplyCorp attributes a conversion using the **buyer's social identity** — on X, their user ID (`twitterId`); on Instagram, a **verification code** that carries their DM-verified identity. Ways to collect it: * **X — you already collect it.** If your product already stores users' X accounts (from signup, onboarding, checkout, or elsewhere), just send that existing identity with each conversion. No ReplyCorp widget or OAuth flow is required. * **X — ReplyCorp Social Connect.** Add the [Social Connect embed](#embed-widget-social-connect-optional) to signup, onboarding, checkout, or account settings — anywhere **before** the conversion events you want to attribute. Connecting can remain optional for your users, and many brands incentivize it with a discount or trial extension. * **Instagram — DM verification codes.** Instagram has no OAuth path your checkout can rely on, so ReplyCorp verifies buyers over DM instead: the buyer DMs a short keyword to a ReplyCorp-controlled account (surfaced via the Social Connect widget's Instagram provider, or a ReplyCorp-powered Shopify flow) and receives a **unique discount code** (e.g. `YOURBRAND-4F9A2C`). At checkout, your backend sends that code as `verificationCode` instead of `twitterId` — or validates it first via `POST /api/v1/codes/resolve` to apply its own discount. See [Identifying Instagram Buyers](/api-documentation.md#identifying-instagram-buyers-verification-codes) in the API documentation. **You do not need 100% coverage.** Conversions without a social identity can still be recorded; ReplyCorp doesn't need every buyer connected to produce useful attribution data. > **Brand social vs. user social:** Step 1 tells ReplyCorp *which posts to monitor*. This step tells ReplyCorp *which user converted*. They are different identities with different purposes. #### Step 4: Send a test conversion Connect your backend and send a **one-time $0 `signup` test conversion** to confirm the integration (the dashboard's *Send a test conversion* step generates this exact request pre-filled with your IDs): ```javascript const conversionResponse = await fetch( 'https://api.replycorp.io/api/v1/campaigns/{campaignId}/conversions', { method: 'POST', headers: { 'X-API-Key': 'your-api-key', 'Content-Type': 'application/json' }, body: JSON.stringify({ twitterId: '1234567890', // a valid X user ID eventType: 'signup', amount: 0 // no commission — not needed for Conversion Intelligence }) } ); const result = await conversionResponse.json(); // Attribution comes back in the same response — no follow-up GET required. ``` * Send it **from your backend**, not from a browser. * If you use the dashboard-generated request, leave `metadata.source` unchanged — ReplyCorp uses it to mark your integration complete automatically. * An empty `attributions` array is valid: it just means that test user has no qualifying social activity yet. #### Step 5: Check your test results (automatic) The dashboard's *Check your test results* step confirms automatically once ReplyCorp receives a valid test conversion containing a user social identity. Nothing to do here beyond Step 4. #### Step 6: Connect your live app Switch your deployed application to your **production configuration**: * Your organization **API key typically stays the same** — the **Campaign ID** is what changes between development testing and production. Both are shown in the dashboard's *Connect your live app* step. * Do **not** send onboarding test requests to the production campaign. ```bash # Production environment REPLY_CAMPAIGN_ID= REPLY_API_KEY= ``` #### Step 7: Activate Conversion Intelligence (dashboard) An admin activates the campaign, which starts mention monitoring on your connected brand socials. Before going fully live, you can optionally run a **monitoring test**: ReplyCorp tracks a capped number of real posts tagging your brand so you can see live data before the campaign starts. Once active, real conversions flow in from your production app and the dashboard shows per-post and per-creator attribution. **Conversion Intelligence setup is complete.** #### Production conversion call (reference) ```javascript body: JSON.stringify({ twitterId: '1234567890', eventType: 'purchase', amount: 100.00, transactionHash: '0x...' // optional: idempotency for chain transactions }) ``` When supplied, `transactionHash` is unique within the campaign. Retrying the same payload returns the original conversion with `idempotentReplay: true`; reusing the hash with different buyer, event, or amount data returns `409`. *** ## Part 2 — Additional work for Rewards campaigns If your campaign also **pays posters** (the Referrals add-on), everything in Part 1 still applies unchanged — Rewards sits **on top of** your Conversion Intelligence integration, in the **same organization, with the same API key and campaign ID**. **The only engineering change is one field:** send a `commission` value (the reward budget) on conversions that should earn rewards. Everything else in this part is dashboard configuration done by your product/ops team. #### Step 1: Set reward amounts Your conversion events are already defined (Part 1, Step 2). With your product team, choose **which of those events earn poster rewards and how much** — a fixed amount per conversion, or a percentage of its value. Then your developer includes that budget with eligible conversions: ```javascript const saleAmount = 120.00; const commission = 12.00; // e.g. a 10% reward budget, calculated in your backend body: JSON.stringify({ twitterId: '1234567890', eventType: 'purchase', amount: saleAmount, commission: commission }) ``` **How the economics work:** * `amount` ($120) is the sale value — used to calculate who influenced the sale (attribution). * `commission` ($12) is the reward budget you pay — ReplyCorp takes 15% as platform fee; the rest becomes influence points for the attributed posters (10,000 points = $1; influencers redeem points for gift cards at that face value). * An explicit `commission: 0` records attribution and purchase data but creates no charge, fee, or rewards — useful when another referral program already applies to a given conversion. * **Do not send `commission` before Rewards is activated** (Step 4). Until then, send conversions without it (or with `0`), exactly as in Part 1. #### Step 2: Set up brand profile (dashboard) Add the public profile posters see in the rewards marketplace: heading, subheading, and at least one FAQ or details blurb covering your participation guidelines. Your connected brand account carries over from CI. No engineering work. #### Step 3: Add money for rewards (dashboard) Before influence points can activate, the reward budget you've been posting must be funded. **This balance is separate from Conversion Intelligence usage credits.** Two rails — pick whichever fits your operations, configured once: **Option A: Stripe ACH (US bank account)** * Link a US bank account via Stripe Financial Connections directly from the dashboard. * ReplyCorp automatically debits accrued rewards on a recurring schedule (default every 10 days). * Good fit if you already handle USD payouts and want zero ongoing operational work. **Option B: USDC Prepaid (on-chain)** * Deposit USDC on Ethereum mainnet into ReplyCorp's `BrandPrepaidLedger` contract from your treasury wallet. * Rewards are consumed from your prepaid balance as point batches activate. * A daily email alert fires if your balance is running low for upcoming activations. * Good fit if you're crypto-native or want to avoid US banking rails. Either rail unlocks the same PENDING → ACTIVE points lifecycle. Monitor balances, upcoming activations, and recent transfers in the **Billing** tab. #### Step 4: Activate Rewards (dashboard) Once Conversion Intelligence is live (Part 1, Step 7), the brand profile is complete, and funding is ready, an admin accepts the Platform Agreement and activates Rewards. From that point, eligible conversions with a `commission` fund poster rewards automatically. #### What ReplyCorp handles for Rewards (you build none of this) * Points calculation and proportional distribution across attributed influencers * Points activation after the refund window closes * Participant onboarding — posters join automatically when they engage on X * Rewards marketplace and gift card fulfillment (Tremendous-backed catalog) * US tax compliance (W-9 / W-8BEN collection via TaxBandits, 1099 e-delivery consent, OFAC screening at redemption) * Brand payment collection on the rail you chose #### Brand content guidelines (optional) You can require posters to include specific phrases (e.g. `#ad`) or ban specific phrases to keep posts compliant with your brand voice. Configured per-campaign via `PATCH /api/v1/campaigns/{id}` (see the API documentation) or directly in the dashboard. Posts that don't meet the rules still count as engagement but won't earn points for the associated conversions. You can also maintain a per-campaign blocklist of X accounts excluded from earning points — useful for known bot accounts or banned posters. *** ### What You DON'T Need to Build ReplyCorp handles all of this automatically, for every campaign: * **Social stream monitoring** — we track mentions, replies, and engagement on X and Instagram * **Network graph construction** — we map who influenced whom * **Attribution calculations** — we determine which posts and creators drove conversions * **Everything in the Rewards list above**, when Rewards is active **Technical requirements — all you must have:** * Ability to make HTTP requests from your backend (any language/framework) * Access to the buyer's social identity when conversions occur — their X ID (yours or via Social Connect) or their Instagram verification code (entered at checkout); partial coverage is fine **What you don't need:** Twitter API credentials, database changes, background workers, or smart contract deployment. *** ### Integration Checklist **Core (Conversion Intelligence) — engineering:** * [ ] Retrieve API key and campaign ID from the dashboard * [ ] Identify conversion events in your codebase and map users to social identities — X IDs (existing data or Social Connect) and/or Instagram verification codes at checkout * [ ] Send the $0 `signup` test conversion from your backend; confirm the dashboard shows it received * [ ] Switch your deployed app to the production Campaign ID * [ ] Verify real conversions appear in the dashboard after activation **Rewards add-on — additional items:** * [ ] Engineering: add `commission` to eligible conversions **after** Rewards is activated * [ ] Dashboard: set reward amounts, complete the brand profile, fund rewards (Stripe ACH or USDC), accept the Platform Agreement, activate * [ ] Verify the first PENDING → ACTIVE point batch activates once the refund window closes and payment is verified * [ ] (Optional) Configure brand content guidelines and banned poster accounts *** ### Reporting in tokens (optional) If your sales are denominated in a supported token (e.g. ApeCoin), you can post conversion amounts in that token instead of converting to USD yourself. Add `"currency": "APE"` to the request and send `amount` / `commission` in APE: ```javascript body: JSON.stringify({ twitterId: '1234567890', eventType: 'purchase', currency: 'APE', amount: 150.0, // 150 APE commission: 3.0 // 3 APE (Rewards campaigns only) }) ``` * ReplyCorp converts to USD once, at ingest, using a [DIA](https://www.diadata.org) spot quote. The applied rate is stored on the conversion and returned in the response `fx` object for your accounting. * Points, billing, and dashboards remain USD-denominated, and reward funding stays in USD (Stripe ACH) or USDC (prepaid) — the `currency` field only changes how you *report* amounts. * Refunds posted with `originalConversionId` reuse the rate from the original conversion, so the USD reversal matches what was credited even if the token price moved. * The supported token list is published at `GET /api/v1/conversions/supported-currencies`. *** ### Embed widget: Social Connect (optional) You can load ReplyCorp's lightweight **embed script** (often via a Google Tag Manager Custom HTML tag) so visitors can link their X — and optionally Instagram — account on your site before they convert. The script: * Loads the pixel from `cdn.replycorp.io`. * Renders a connect control into any element marked `data-replycorp-connect`. For **X**, it runs an OAuth popup flow against ReplyCorp's hosted callback routes. For **Instagram** (when the provider is enabled for your brand), it shows the buyer a short keyword to DM to a ReplyCorp-controlled account and confirms automatically once the DM is verified. * Emits a `replycorp:connected` DOM event your page can listen for (e.g. to unlock UI or apply a discount after connect). Use that event to read the connected identity and pass the buyer's identity into your own backend when you call the conversion API. **Conversions are not sent from this embed.** For security, purchase and other conversion events must be posted from **your server** (or another trusted path you control) using your API key — the same as a full API integration. **Tag attributes** | Attribute | Required | Description | | --------------- | -------- | ------------------------------------------------------------- | | `data-brand-id` | Yes | Your organization slug. | | `data-api-base` | Yes | API origin the pixel calls (e.g. `https://api.replycorp.io`). | **Option A — Latest (auto-updates)** `pixel.js` is the rolling latest build and receives fixes on each ReplyCorp deploy. Its bytes change over time, so **do not** use it with Subresource Integrity. ```html ``` **Option B — Pinned + Subresource Integrity (SRI)** If your security policy requires an `integrity` attribute, load a **pinned, immutable** version (`pixel.v1.js`, `pixel.v2.js`, …). Pinned files are published once and never overwritten, so the SRI hash stays stable. `crossorigin="anonymous"` is required whenever `integrity` is set on a cross-origin script. ```html ``` Get the current pinned URL and its `integrity` value from the **GTM / Pixel** tab in the ReplyCorp dashboard (it renders both snippets pre-filled), or from the pixel package's `published-versions.json` manifest. When ReplyCorp ships a new pinned line (e.g. `pixel.v2.js`), migrate explicitly — your existing hash keeps working until you choose the new pinned URL. Per-brand options (which providers are enabled, styling hints, etc.) live in your organization's `pixelConfig`. Org admins can update them in the dashboard or via `PATCH /api/v1/organizations/me/pixel-config` (authenticated as an org admin). *** ### Legacy: two-organization dual reporting {% hint style="warning" %} **This section only applies if ReplyCorp has told you that you have two separate organizations** (an older configuration where Conversion Intelligence and Referrals ran as separate accounts with separate API keys). **New combined setups use a single organization** — Rewards is enabled as an add-on on your Conversion Intelligence organization, with one API key and one campaign ID, as described in Parts 1 and 2 above. If that's you, skip this section entirely. {% endhint %} Legacy dual-organization customers report each conversion to **both** organizations: 1. **Send every conversion event to both campaigns.** Same endpoint, same payload shape — only the `X-API-Key` header and the `{campaignId}` in the URL differ. 2. **Include `commission` in both requests.** The Referrals organization uses it to fund rewards. The CI organization ignores it. Sending an identical payload to both is correct. 3. **The two requests must be independent.** A failure (or slow response) from one must not prevent, delay, or abort the other. Do not wrap them in a shared transaction or fail-fast chain. 4. **Store both returned conversion IDs.** Each organization returns its own `conversion.id` for the same real-world event. You need the correct per-organization ID later for refunds. 5. **Send refunds to both campaigns too**, each referencing that organization's own conversion ID in `originalConversionId`. Never send organization A's conversion ID to organization B. 6. **Reuse the same `transactionHash` in both requests** (when you use one). Idempotency is scoped per campaign — `(campaignId, transactionHash)` — so the same hash is safe and correct on both, and retries of either request are deduplicated independently. 7. **Do not retry on "insufficient reward balance."** On the Referrals side, a conversion succeeds even when the brand's reward balance is empty (points stay PENDING until funded). Only retry on network errors or HTTP 5xx, and retry each organization's request independently. ```javascript // One entry per ReplyCorp organization. Same payload goes to both. const REPLYCORP_TARGETS = [ { name: 'ci', apiKey: process.env.REPLYCORP_CI_API_KEY, campaignId: process.env.REPLYCORP_CI_CAMPAIGN_ID }, { name: 'referrals', apiKey: process.env.REPLYCORP_REF_API_KEY, campaignId: process.env.REPLYCORP_REF_CAMPAIGN_ID }, ]; // Returns { ci: conversionId, referrals: conversionId }; store both with your order/tx record. async function reportConversion(payload) { const results = await Promise.allSettled( REPLYCORP_TARGETS.map(async (t) => { const res = await fetch( `https://api.replycorp.io/api/v1/campaigns/${t.campaignId}/conversions`, { method: 'POST', headers: { 'X-API-Key': t.apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify(payload), }, ); if (!res.ok && res.status >= 500) throw new Error(`${t.name}: HTTP ${res.status}`); // retryable const data = await res.json(); return { name: t.name, conversionId: data.conversion?.id }; }), ); const ids = {}; for (const r of results) { if (r.status === 'fulfilled') ids[r.value.name] = r.value.conversionId; else console.error('ReplyCorp reporting failed (retry this target only):', r.reason); } return ids; } ``` Legacy dual-org notes: only the **Referrals** organization needs payment setup and a brand profile; each organization has its own admin login (use a different email per organization); verify a test conversion appears in **both** dashboards. *** ### Support & Resources **Documentation:** * Full API docs: See [ReplyCorp API Documentation](/api-documentation.md) * Programmatic stats & AI-tool access: [Reporting API & MCP](/reporting-api-and-mcp.md) (Growth+) **Support:** * **Account Setup & Access:** Contact ReplyCorp * **Telegram Bot:** @ReplyCorpBot — AI setup assistant, campaign management, and integration guidance * **Technical Support:** Email * Response time: Typically within 24 hours *** **Bottom Line:** The core integration is one API endpoint called from your backend when conversions happen, with the buyer's X ID attached. That alone gets you Conversion Intelligence. A Rewards campaign adds exactly one field to that call (`commission`) plus dashboard configuration your product team completes in the guided checklist — no additional engineering infrastructure. ReplyCorp handles the complex parts: social monitoring, attribution, points, compliance, and payment collection. *** *Last Updated: October 2026*