Connect Easypromos to AI Agents: Sync Participations and Leaderboards

You want to connect Easypromos to an AI agent so your system can independently orchestrate promotions, validate participation requirements, sync leaderboards, and manage virtual coin transactions. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom marketing campaign integration from scratch.

Giving a Large Language Model (LLM) read and write access to your Easypromos instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Easypromos to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Easypromos to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Easypromos, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex campaign workflows. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of the Easypromos API

Giving an LLM access to external data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an @tool decorator. In production against complex promotional and loyalty systems, this approach collapses.

The Easypromos API introduces several specific integration challenges that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

The Login Token (lt) Requirement

Standard APIs operate on generic bearer tokens and static resource IDs. Easypromos introduces a secondary layer of participant-level authentication via the Login Token (lt). An AI agent cannot simply submit a code validation request using a raw user_id and a promotion_id. It must first log in or register the user via the server-side autologin flow to retrieve an ephemeral lt, which acts as a unique access code for that specific participant session. If an LLM is given direct API endpoints without an abstraction layer, it will inevitably hallucinate user_id values into the lt parameter, resulting in hard 401s or 403s.

Multi-Currency Virtual Coin Ledgers

When crediting a participant's account, agents natively assume a single balance value. However, Easypromos supports multicurrency promotions. A virtual coin transaction requires specifying the exact coin_id, not just a numerical amount. Furthermore, financial transactions in a promotional ledger are unforgiving. Credit operations must be strictly managed to prevent double-spending or redundant rewards, requiring your agent to accurately interpret whether an amount is a positive credit or negative spend, and provide a strict reason code for auditability.

Complex Participation Eligibility and Limits

Submitting a participation in an Instant Win or Spin the Wheel campaign is not a simple POST request. Easypromos enforces granular limits based on stage configurations (per promotion, per day, per week, per hour). If an LLM attempts to brute-force participations without checking availability, the API will reject the requests. The agent must first query the remaining participations limit endpoint, parse the can_participate boolean, and act conditionally before executing the write operation.

Why a Unified Tool Layer Matters for Agent Safety

Direct API tools - one tool per raw Easypromos endpoint - push provider quirks into the LLM's context. A unified tool layer collapses these complexities behind standardized schemas. Your agent sees create_a_easypromos_users_autologin and list_all_easypromos_participation_participates via Truto's Proxy APIs, which handle data normalization using the raw data from the underlying product's APIs.

This gives you three concrete safety wins:

1. Deterministic input validation. Every tool has a strict JSON schema. If the LLM tries to execute a virtual coin transaction without a valid lt, the tool layer rejects it before it hits the Easypromos API, preventing malformed state mutations.
2. Standardized Tool Fetching. Instead of maintaining 30 different JSON schemas in your codebase, your LLM framework fetches real-time, customizable tool definitions directly from the Truto /tools endpoint.
3. Transparent Rate Limit Handling. Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API returns HTTP 429, Truto passes that error to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller is responsible for retry/backoff, ensuring your agent logic retains full control over execution pausing and state rollbacks without hidden latency spikes.

Easypromos Hero Tools

To build effective AI agents for promotional workflows, you need high-leverage tools that orchestrate multi-step processes. Here are the core Easypromos tools your agent will use.

Generate Participant Login Token

Tool: create_a_easypromos_users_autologin

This is the gateway tool for almost all participant-level operations. It logs in or registers a user in a promotion via the server-side autologin flow, returning the critical Login Token (lt).

"Authenticate the user with external ID 'user-8849' for promotion 'promo-101' and securely store their login token for the next steps."

Check Stage Requirements and Balances

Tool: list_all_easypromos_participation_check_requirements

Before allowing a user to participate or spin a wheel, the agent must verify if they meet the stage's requirements (such as possessing enough Virtual Coins). This tool safely errors out if the balance is insufficient, acting as a gatekeeper.

"Verify if the user with login token 'lt_abc123' has enough virtual coins to participate in the 'Gold Tier Spin' stage of the current promotion."

Execute Stage Participation

Tool: list_all_easypromos_participation_participates

This tool submits a new participation for a registered user, consuming one of their available limits. It is specifically designed for mechanics like direct participation, spin the wheel, scratch & win, and reveal & win stages.

"Submit a spin the wheel participation for the current user in stage 'stage-442'. Tell me if they won a prize and what their available participations are now."

Create Virtual Coin Transactions

Tool: create_a_easypromos_coin_transaction

Rather than forcing the LLM to calculate ledger deltas, this tool appends a strict transaction to the user's ledger. A positive amount credits coins; a negative amount spends them. It requires a strict reason string for auditing.

"Credit 500 bonus coins to the user's wallet for completing their profile, using reason 'Profile Completion Bonus'."

Fetch Promotion Rankings

Tool: get_single_easypromos_ranking_by_id

Essential for leaderboard workflows, this tool retrieves ranked user entries ordered by position, including points and full user attributes, safely capped to prevent payload explosion.

"Pull the top 25 users from the current promotion's ranking board so we can prepare the weekly winner announcement."

Audit Assigned Prizes

Tool: list_all_easypromos_prizes

This reads the entire inventory of assigned prizes along with the user who won each one. Agents use this to verify fulfillment queues or summarize campaign outcomes.

"List all the prizes that have been awarded so far in the 'Summer Giveaway' promotion, and extract the email addresses of the winners."

For the complete tool inventory, including tools for points of sale (POS) management, segment assignment, and detailed participation limits, refer to the Easypromos integration page for full schema details.

Building Multi-Step Workflows

To see how these tools work in practice, let's architect a standard agent loop using LangChain.js and the TrutoToolManager.

Your application fetches the proxy API schemas from the /tools endpoint dynamically. Because Truto manages the underlying OAuth/API key state, the LLM only needs to provide the functional arguments.

import { ChatAnthropic } from "@langchain/anthropic";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function runEasypromosAgent() {
  // 1. Initialize the LLM
  const llm = new ChatAnthropic({
    model: "claude-3-5-sonnet-20241022",
    temperature: 0,
  });
 
  // 2. Fetch tools from Truto's Proxy APIs for the specific connected account
  const toolManager = new TrutoToolManager({
    integratedAccountId: process.env.EASYPROMOS_ACCOUNT_ID!,
    trutoApiKey: process.env.TRUTO_API_KEY!,
  });
 
  // Filter for write/read tools relevant to participations
  const tools = await toolManager.getTools();
 
  // 3. Define the agent prompt
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are a promotional campaign manager. Execute commands securely and step-by-step. If an API returns a [429 Rate Limit error](/how-to-handle-long-running-saas-api-tasks-in-ai-agent-tool-calling-workflows/), back off and retry once before alerting the user."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 4. Bind tools and execute
  const agent = createToolCallingAgent({ llm, tools, prompt });
  const executor = new AgentExecutor({ agent, tools });
 
  try {
    const result = await executor.invoke({
      input: "Log in user 'ext-998', check their remaining participations for stage 'stg-12', and if they have at least 1, submit a spin."
    });
    console.log(result.output);
  } catch (error: any) {
    // The caller is strictly responsible for handling Truto's standardized 429 headers
    if (error.response?.status === 429) {
      const resetTime = error.response.headers.get('ratelimit-reset');
      console.error(`Rate limit hit. Must back off until: ${resetTime}`);
    }
  }
}

Workflows in Action

When connected via Truto, your agent can execute domain-specific workflows that combine multiple Easypromos resources autonomously.

1. Automated Prize Distribution and Ledger Sync

Customer support bots frequently handle inquiries about contest rules, missing points, or prize status. An agent with Easypromos tools can investigate and resolve these instantly.

"A user with external ID 'user-404' is complaining they didn't get their sign-up bonus coins. Verify their balance, and if it's 0, issue them 100 coins. Then check if they have won any physical prizes."

Agent Execution Trace:

1. Calls create_a_easypromos_users_autologin to fetch the user's lt.
2. Calls list_all_easypromos_coin_users passing the promotion_id and user ID to check current balances.
3. Observes the balance is 0.
4. Calls create_a_easypromos_coin_transaction using the lt, an amount of 100, and a reason of "Support manual sign-up credit".
5. Calls list_all_easypromos_prize_users to pull the user's awarded prizes.
6. Synthesizes a human-readable response confirming the credit and summarizing the prize queue.

2. High-Volume Leaderboard Enforcement

During high-stakes competitions, fraudulent entries or manual adjustments require immediate attention. Agents can automate leaderboard audits.

"Pull the top 10 ranked users from promotion 'promo-777'. Remove the 'VIP' segment from any user in the top 10 who has zero virtual coin transactions on record."

Agent Execution Trace:

1. Calls get_single_easypromos_ranking_by_id to retrieve the top 10 user entries.
2. Iterates through the IDs, calling list_all_easypromos_coin_transaction_users for each to audit activity.
3. Identifies users with an empty transaction array.
4. For flagged users, calls create_a_easypromos_users_autologin to fetch the lt.
5. Calls delete_a_easypromos_users_segment_by_id passing the lt and the VIP segment to strip the status.
6. Returns an execution log detailing exactly which users were demoted.

sequenceDiagram
    participant LLM as Agent (LLM)
    participant Truto as Truto Tool Manager
    participant Upstream as Easypromos API
    
    LLM->>Truto: Call get_single_easypromos_ranking_by_id
    Truto->>Upstream: GET /promotions/{id}/ranking
    Upstream-->>Truto: JSON Array (Ranked Users)
    Truto-->>LLM: Normalized Ranking Schema
    
    loop For each top 10 user
        LLM->>Truto: Call list_all_easypromos_coin_transaction_users
        Truto->>Upstream: GET /promotions/{id}/users/{user_id}/transactions
        Upstream-->>Truto: JSON Array (Transactions)
        Truto-->>LLM: Parsed Activity Log
    end
    
    opt No transactions found
        LLM->>Truto: Call create_a_easypromos_users_autologin
        Truto->>Upstream: POST /promotions/{id}/autologin
        Upstream-->>Truto: Login Token (lt)
        Truto-->>LLM: lt extracted
        
        LLM->>Truto: Call delete_a_easypromos_users_segment_by_id
        Truto->>Upstream: DELETE /users/{id}/segments
        Upstream-->>Truto: Success
        Truto-->>LLM: Segment Removed
    end

Wrap-Up

Building agentic applications on top of marketing and promotional systems demands a reliable API abstraction. If your agent is forced to juggle login tokens, nested JSON API schemas, and disparate endpoint behaviors, its reasoning loops will fail. By utilizing Truto's Proxy APIs and the /tools endpoint, you provide your agent with a strictly typed, normalized operational layer.

This architecture keeps your integration logic decoupled from your agent prompting. As Easypromos updates their endpoints or introduces new promotional mechanics, Truto absorbs the API drift, meaning your agent's tools continue functioning without deploying new integration code.