--- title: Easypromos API Integration on Truto slug: easypromos category: Marketing Automation canonical: "https://truto.one/integrations/detail/easypromos/" --- # Easypromos API Integration on Truto **Category:** Marketing Automation **Status:** Beta ## MCP-ready AI tools Truto exposes 31 tools for Easypromos that AI agents can call directly. - **list_all_easypromos_promotions** — List the promotions of the Easypromos account. Returns each promotion's id and attributes (the promotion's basic information fields). Supports optional status and order filters. - **get_single_easypromos_promotion_by_id** — Get the basic information of a single Easypromos promotion by id. Returns the promotion's id and attributes (the promotion fields as defined in the Easypromos Promotion schema). Required: id. - **list_all_easypromos_organizing_brands** — List the organizing brands of the Easypromos account. Returns the collection of organizing brand records, each including its id. - **get_single_easypromos_organizing_brand_by_id** — Get the basic information of a single organizing brand in Easypromos by id. Returns the organizing brand object, including its id. Required: id. - **list_all_easypromos_organizing_brand_promotions** — List the promotions of a specific organizing brand in Easypromos. Returns promotion records including id, status, created_at, and updated_at. Required: organizing_brand_id. - **get_single_easypromos_stage_by_id** — Get all data of a single participation stage in an Easypromos promotion. Returns the stage record including its id and type-specific attributes defined upstream. Required: id, promotion_id. - **list_all_easypromos_stages** — List all participation stages in an Easypromos promotion. Returns stage records including their id and type-specific attributes defined upstream. Required: promotion_id. - **get_single_easypromos_user_by_id** — Get all data of a single user registered in an Easypromos promotion. Returns the user record with its id and an attributes object whose field set is defined by the upstream UserFull schema. Required: id, promotion_id. - **list_all_easypromos_users** — List the users registered in an Easypromos promotion. Returns each user's id, first_name, last_name, email, and segments. Required: promotion_id. - **get_single_easypromos_users_logintoken_by_id** — Get the login token of a user registered in an Easypromos promotion by promotion and user id. Returns the login token object with lt, the unique access code for the participant (Login Token). Required: id, promotion_id. - **easypromos_users_segments_assign** — Assign one or multiple segments to an easypromos user. Returns: status. Segments must already exist in the promotion, organizing brand, or account. Required: promotion_id, lt, segments. - **delete_a_easypromos_users_segment_by_id** — Remove one or multiple segments from an easypromos user. Returns: status. Segments must already exist in the promotion, organizing brand, or account. Required: id, lt, segments. - **create_a_easypromos_users_autologin** — Log in or register a user in an Easypromos promotion via the server-side autologin flow. Returns the user Login Token (lt), whether the user was already registered (registered), and the Easypromos user_id. Required: promotion_id, external_id. - **get_single_easypromos_participation_by_id** — Get a single Easypromos participation by id within a promotion. Returns the participation record including its id, the user who participated, and the prize if the participation won one. Required: id, promotion_id. - **list_all_easypromos_participations** — List Easypromos participations of a promotion, ordered by creation date descending. Returns each participation's id, user, and prize if won. Required: promotion_id. - **list_all_easypromos_participation_users** — List all participations of a single user in an Easypromos promotion. Returns a paginated list of participation records including id, promotion_id, stage_id, user_id, created, points, and the data key-field array. Required: promotion_id, user_id. - **list_all_easypromos_participation_remainings** — Get the remaining participations a user has left in a specific stage of an easypromos promotion, based on the stage's configured limits (per promotion, day, week, or hour). Returns: remaining, can_participate, next_participation. Required: promotion_id, stage_id, user_id. - **list_all_easypromos_participation_check_requirements** — Check whether a user is eligible to meet a participation stage's requirement in Easypromos; currently only the Virtual Coin requirement is supported. Returns the url to complete the participation when the user has sufficient balance; the call errors when the balance is insufficient. Required: promotion_id, stage_id, lt. - **list_all_easypromos_participation_validate_codes** — Submit a code for validation so a participant can enter an Easypromos participation stage. The stage must have the code validation requirement enabled. Returns the ticket_id of the valid requirement and the url to complete the participation (with the login token included for autologin). Required: promotion_id, stage_id, lt, code. - **list_all_easypromos_participation_participates** — Submit a new participation for a registered user in an Easypromos participation stage, consuming one of the user's available participations; supported for direct participation, spin the wheel, scratch & win, and reveal & win stages, and recommended for Instant Win promotions. Returns: participation_id, available_participations, prize. Required: promotion_id, stage_id, lt. - **get_single_easypromos_prize_by_id** — List all prizes assigned in an Easypromos promotion together with the information of the user who won each one. Returns: paging. Required: promotion_id, id. - **list_all_easypromos_prizes** — List all prizes assigned in an Easypromos promotion together with the user who won each one. Returns: id, prize_type, user_id, stage_id, participation_id, created, code, download_url, redeem_url, claim_url, claim, user, attributes. Required: promotion_id. - **list_all_easypromos_prize_users** — List all prizes awarded to a single user in an easypromos promotion. Returns prize records with their id and prize attributes. Required: promotion_id, user_id. - **get_single_easypromos_prizes_inventory_by_id** — Get the prize inventory of an EasyPromos promotion by id. Returns the complete list of prize types defined in the promotion, each with its id and the prize-type fields defined upstream, including the total number of units and the number of units already given. Required: id. - **list_all_easypromos_coin_users** — Get the virtual coin balances of a single user in an Easypromos promotion. Returns each coin's id, name, and balance — one entry per coin, since promotions can be multicurrency. Required: promotion_id, user_id. - **update_a_easypromos_coin_by_id** — Update the virtual coin balance of a single user in an Easypromos promotion by id. Returns the current coin balances, each with id, name, and balance. Required: id, lt, balance, reason. - **list_all_easypromos_coin_transaction_users** — List all virtual coin transactions of a single user in an Easypromos promotion. Returns: id, user_id, promotion_id, coin_id, coin_name, amount, balance, created, transaction_type, reason, extra. Required: promotion_id, user_id. - **create_a_easypromos_coin_transaction** — Create a coin transaction in Easypromos to add or remove virtual coins for a participant in a promotion — a positive amount credits coins, a negative amount spends them. Returns the registered transaction object (id plus transaction attributes; the full field set follows the VirtualCoinTransaction definition in the Easypromos API reference). Required: promotion_id, lt, amount, reason. - **list_all_easypromos_coin_transactions** — List all virtual coin transactions recorded in an Easypromos promotion. Each item returns the transaction (id, amount, reason, created_at) and the user the transaction belongs to. Required: promotion_id. - **get_single_easypromos_ranking_by_id** — Get the ranking of an Easypromos promotion by id, ordered by ranking position. Returns ranked user entries with id, points, and the full user record (attributes). Caps the result at 500 entries (25 by default). Required: id. - **list_all_easypromos_pos** — List all points of sale in an Easypromos promotion, ordered by group and alphabetically. Returns point-of-sale records including their id, name, and group. Required: promotion_id. ## How it works 1. **Link your customer's Easypromos account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Easypromos.** The Proxy API is a 1-to-1 mapping of the Easypromos API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Embed gamified rewards in loyalty platforms** — Loyalty and retention SaaS products can offer their customers interactive mechanics like spin-the-wheel or scratch cards without building a gamification engine. End users spend native loyalty points as Easypromos virtual coins and claim prizes directly inside the host widget. - **Power in-app promotions for mobile commerce builders** — Mobile app and e-commerce platform builders can let their brand customers launch native giveaways and contests. Autologin tokens drop app users straight into a promotion webview without re-authentication, keeping the experience inside the host app. - **Trigger lifecycle campaigns from promotion outcomes** — CDPs and marketing automation tools can read participation and prize data to trigger follow-up journeys — consolation discounts for losers, VIP escalation for winners, or re-engagement for users approaching participation limits. - **Attribute offline sales to digital promotions** — Retail tech and POS platforms can map specific points of sale to prize claims and inventory movements, giving brands granular attribution between in-store activity and the digital campaigns running in Easypromos. - **Gate premium campaigns by customer segment** — CRMs and segmentation tools can push audience tags into Easypromos to unlock exclusive promotions for specific tiers, letting their customers run VIP-only contests driven by live segmentation data from the host product. ## What you can build - **Frictionless autologin into promotions** — Generate secure login tokens server-side so end users land inside an Easypromos campaign already authenticated, with no registration form. - **Virtual coin ledger sync** — Mint, update, and read virtual coin balances in response to purchases, logins, or custom events in the host product, and surface available plays natively. - **Native 'Play Now' eligibility checks** — Query participation remainings, requirement checks, and promo code validation before rendering CTAs, so users only see games they can actually play. - **Segment-driven promotion unlocks** — Assign and remove Easypromos user segments from the host app to dynamically unlock, restrict, or boost promotional experiences per audience. - **Prize and inventory dashboards** — Pull real-time prize definitions, inventory levels, and winner lists into the host product's analytics or operations UI for fulfillment workflows. - **Campaign and brand discovery UI** — List organizing brands, promotions, and stages so end users can browse and select active Easypromos campaigns to feature from inside the host dashboard. ## FAQs ### How does authentication work for end users connecting their Easypromos account? Truto handles the Easypromos API credential exchange and token storage per end user. Your product calls Truto's unified endpoints with a connection identifier, and Truto injects the correct auth on each request. ### Can we log users into a promotion without showing a login form? Yes. Use the autologin creation tool to generate a secure token server-side and redirect the user into the promotion webview pre-authenticated. This is the standard pattern for embedded experiences. ### Can we credit or debit virtual coins programmatically? Yes. You can create coin transactions, update coin balances, and list coin users and transaction history, which supports loyalty-point-to-virtual-coin sync patterns. ### How do we check if a user is allowed to participate before showing a 'Play' button? Use the participation remainings, check requirements, and validate codes endpoints to confirm eligibility, remaining plays, and promo code validity before rendering the CTA. ### How fresh is participation and prize data? Data is fetched on demand through Easypromos's REST API, so reads reflect the current state at request time. For near-real-time workflows, poll the participations and prize users endpoints at an interval that matches your use case. ### Does Truto handle pagination and rate limiting for Easypromos? Yes. Truto normalizes pagination across list endpoints and manages retry and backoff behavior against Easypromos rate limits, so you consume a consistent interface regardless of the underlying API quirks.