Campaigns API

Examples below show the wire-format Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE header. To compute the signature in your code, use the signedRequest helper in Authentication.

The Campaigns API lets your backend read your company’s incentive campaigns in SalesOS — which ones are running, what the reward catalog offers, how much each collaborator has to spend, and how many rewards they already qualify for. It was built for composing your own screens before the user ever opens the SalesOS module. It is a read-only, server-to-server API: you look collaborators up by CPF or email, in batch, and SalesOS answers with the running campaigns and each person’s state in them.

A campaign is configured by your company: name, catalog, prices in points, categories, level rules and even the currency name. This API returns whatever is configured — it knows no specific campaign.

How It Works

You get an API Key with the campaigns:read scope (Admin > Integrations > API Keys)
Your backend asks for the state of one or many collaborators (by CPF or email)
SalesOS answers with the running campaigns — campaign data once, then each collaborator’s state

Campaign metadata comes back once at the top, not repeated per person. On a 500-collaborator batch that is the difference between a lean response and a multi-megabyte one.

This endpoint does not redeem rewards or accept terms. It is read-only — pair it with the campaign page (access.url) for the action itself — see Opening the campaign page.

Authentication

Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE

See the Authentication page to create and manage API Keys.

Property	Details
Header	`Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`
Scope required	`campaigns:read`
Rate limit	Configurable per key (default: 1000 requests/hour)
Key format	`sk_live_` (production) or `sk_test_` (testing)

Environments

Production
Staging

Base URL: https://api.play2sell.com

Base URL: https://api-staging.play2sell.com

Endpoint Reference

POST https://api.play2sell.com/functions/v1/campaigns-partner-api

Two actions via the action field: campaign_status and campaign_catalog. Each collaborator is identified by CPF (any format — digits are normalized) or email. When both are sent, CPF wins.

Action: campaign_status

Your company’s running campaigns and each collaborator’s state in them.

Request Schema

string

required

Must be "campaign_status"

array

required

Array of collaborator references (max 500)

string

CPF, any format (52998224725 or 529.982.247-25). Must contain exactly 11 digits.

string

Email — used only when cpf is absent

string

Filter to a single campaign. Absent = every running campaign.

string

Language for the configurable texts. Absent = the campaign’s default.

Example

curl -X POST https://api.play2sell.com/functions/v1/campaigns-partner-api \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "campaign_status",
    "collaborators": [{ "cpf": "529.982.247-25" }]
  }'

Response (200):

{
  "data": {
    "timezone": "America/Sao_Paulo",
    "reference_date": "2026-08-12",
    "campaigns": [
      {
        "id": "aaaaaaaa-0000-0000-0000-000000000001",
        "slug": "your-campaign",
        "name": "Your Campaign",
        "tagline": "Your reward catalog",
        "status": "active",
        "default_locale": "pt",
        "locales": ["pt"],
        "currency": { "label": "Moedas", "label_singular": "Moeda", "icon": "🪙" },
        "access": {
          "url": "https://app.play2sell.com/campanha",
          "path": "/campanha",
          "requires_session": true,
          "return_param": "next",
          "login_url": "https://app.play2sell.com/login/sso?connection=your-company-connection&next=%2Fcampanha"
        },
        "catalog": {
          "rewards": 22,
          "awarded_only": 2,
          "categories": 6,
          "cheapest_points": 200,
          "priciest_points": 22000
        }
      }
    ],
    "collaborators": [
      {
        "cpf": "52998224725",
        "found": true,
        "user_id": "8f14e45f-0000-0000-0000-000000000001",
        "name": "Maria Santos",
        "membership_status": "active",
        "balance": {
          "spendable": 1500,
          "source": "playcoin",
          "wallet_enabled": true
        },
        "score": {
          "xp": 1800,
          "level": 3,
          "level_detail": {
            "order": 3, "key": "level_03", "name": "Avançado",
            "description": "Você já pegou o ritmo.",
            "appearance": { "color": "#7B2D8E", "image_url": "/storage/v1/object/public/level-assets/…/….png", "image_alt": "Avançado" }
          },
          "note": "diverges_from_balance"
        },
        "campaigns": [
          {
            "campaign_id": "aaaaaaaa-0000-0000-0000-000000000001",
            "slug": "your-campaign",
            "eligible_rewards": 18,
            "affordable_rewards": 7,
            "next_reachable_points": 2000,
            "redemptions": { "open": 1, "fulfilled": 3 }
          }
        ]
      }
    ],
    "total": 1,
    "found": 1
  },
  "meta": {
    "request_id": "1f6c1b2e-0000-4a1b-8c2d-000000000001",
    "timestamp": "2026-08-12T13:45:00.000Z"
  }
}

Campaign fields

Field	Meaning
`slug` · `name` · `tagline`	Identification and texts configured by your company
`currency.label`	The currency name, as your company configured it. Render this value — never hardcode a name in your app
`currency.label_singular` · `currency.icon`	Singular form and icon of the currency, when your company configured them. Absent otherwise
`access.url`	Where the campaign page opens in the SalesOS app of this environment — see Opening the campaign page
`access.path` · `access.return_param`	The page path and the name of the return parameter (`next`) of SalesOS entry links
`access.login_url`	Link to sign in through your company’s identity provider and land on the campaign page. `null` when sign-in through your provider is not set up in this environment — see Signing in again through your company’s provider
`catalog.rewards`	Rewards that can be redeemed with balance
`catalog.awarded_only`	Rewards that are granted (by ranking or trigger) and are not for sale
`catalog.categories`	Distinct categories in the catalog
`catalog.cheapest_points` / `priciest_points`	Price range of the catalog
`terms`	Present only when the campaign requires acceptance, with the current version

The currency name is resolved in this order: the label configured on the campaign, then the currency registered for your company (with singular form and icon), then pontos. It is the same name the campaign page shows.

Collaborator fields

Field	Meaning
`balance.spendable`	The balance available to spend right now
`balance.wallet_enabled`	Whether the wallet is enabled for your company — read this before showing a zero
`score.xp` · `score.level`	Score and level. The level decides which rewards the collaborator qualifies for
`score.level_detail`	The level as your company configured it: `name`, `description`, and `appearance` (color and badge). Absent when the level has no step on the ladder
`score.note`	`diverges_from_balance` when score and balance do not match
`campaigns[].eligible_rewards`	Rewards they qualify for (level rule satisfied)
`campaigns[].affordable_rewards`	Rewards they can pay for with the current balance
`campaigns[].next_reachable_points`	What the next out-of-reach reward costs — the “X to go”
`campaigns[].terms_accepted`	Present only when the campaign requires acceptance
`campaigns[].redemptions`	Open and fulfilled redemptions

spendable: 0 does not mean “no points”. The wallet is enabled per company; until it is, the balance comes back as zero even for people who have a score. Always read wallet_enabled before writing “no balance” on the screen — otherwise it states an absence that isn’t true.

Qualifying and affording are different counts. A reward can be unlocked by level and still cost more than the collaborator has. That is why eligible_rewards and affordable_rewards are separate fields.

Action: campaign_catalog

The same content with the catalog cut. Because the catalog grows per collaborator, the batch limit drops to 100.

curl -X POST https://api.play2sell.com/functions/v1/campaigns-partner-api \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "campaign_catalog",
    "collaborators": [{ "cpf": "529.982.247-25" }],
    "campaign_slug": "your-campaign"
  }'

Opening the campaign page

Every campaign comes with an access block: where its page lives in the SalesOS app and how to get the user there. The page is where the user browses the catalog and redeems rewards, and it requires a signed-in user. There are two ways in:

Way	How
Sign-in and password	Open `access.url`. A user without a session goes through the SalesOS sign-in and comes back to the page
Your company’s identity provider	Open `access.login_url` when it is filled in. The user signs in through your company’s provider, with no SalesOS password, and lands on the campaign page

Read access.url and access.login_url from the response — do not hardcode them. The URL changes per environment (production and staging have different apps).

The return parameter only accepts a path inside the SalesOS app. A full URL, another host or anything else is ignored and the user lands on the home screen.

Signing in again through your company’s provider

The full guide to this sign-in (both ways, what to send and the refusals) is in SSO (Single Sign-On). When your company signs users in with its own identity provider (OAuth 2.0 / OpenID Connect) and Play2sell connects that provider to SalesOS, the response includes access.login_url. Use it as the default link to the campaign page. It covers the case where the user has to sign in again:

User’s situation	What happens when opening `access.login_url`
Already has a SalesOS session	Opens the campaign page directly
SalesOS session expired, still signed in to your provider	Goes through your provider without typing anything and comes back to the page
No session anywhere	Signs in to your provider and comes back to the page

https://app.play2sell.com/login/sso?connection=<connection>&next=%2Fcampanha

A user who came in this way and whose session expires inside the app is also sent back through your provider, to the same page, instead of the SalesOS password screen.

Read access.login_url from the response — do not build the URL in your code. It changes per environment and is only filled in when the link to your provider is active in that environment. With null, use one of the other ways in.

To turn it on: your company registers Play2sell as an OAuth 2.0 client in your provider, one client per environment, with the callback address we send (https://auth.play2sell.com/login/callback in production). We need the authorization and token endpoints, the client ID and secret (over a secure channel) and each user’s stable identifier: your provider’s internal id, the CPF or CNPJ, or the email. With CPF or CNPJ, the user stays the same person in SalesOS even after changing email.

Signing in through your provider does not open the account of someone outside your company: a SalesOS account tied to another company, a Play2sell staff account or an access your manager deactivated is refused with a message that says what to do.

Self mode (SSO user token)

With the token of a user who signed in through SSO, send Authorization: Bearer <jwt> and omit collaborators. The answer covers only the token’s own user.

Sending collaborators with a user token is rejected with SELF_MODE_NO_COLLABORATORS. Batch lookups require a partner API key — otherwise any signed-in user could read other people’s balance by CPF.

Error Handling

{ "error": { "code": "ERROR_CODE", "message": "Human-readable description", "details": [] } }

Two shapes, not one. The block above is the endpoint error. Failures in the authentication layer answer before the endpoint runs, with error as a string:

{ "error": "Missing Authorization header", "code": "header_missing" }

Code that assumes error.code reads undefined on every auth failure. Branch on the type — see API Conventions.

400 — VALIDATION_ERROR

Invalid body, batch over the limit, CPF without 11 digits, an item with neither cpf nor email, or a malformed campaign_slug. The details array points to the item index.

400 — SELF_MODE_NO_COLLABORATORS

A collaborators list was sent together with a user token.

401 — UNAUTHORIZED

API key is missing, invalid, or expired, or the signature does not match.

403 — FORBIDDEN

API key is valid but lacks the campaigns:read scope.

405 — METHOD_NOT_ALLOWED

Only POST is accepted.

429 — RATE_LIMITED

Too many requests this hour. Wait retry_after seconds.

500 — SERVER_ERROR

Internal server error. Retry with exponential backoff (2s, 4s, 8s).

No running campaign is not an error. The response comes back with campaigns: [] and status 200 — the company may simply have nothing live.

Rate Limits

Limit	Value
Default requests per hour	1000
Max collaborators per `campaign_status`	500
Max collaborators per `campaign_catalog`	100

Security

Read-only: this API never creates redemptions, accepts terms, or changes balances
Each key is scoped to a single company — a CPF from another company answers found: false, and other companies’ campaigns never appear
Requests are HMAC-signed (P2S-SIGN-V1) and logged for audit; documents are never written to logs

Never expose your API key in client-side code. This API must only be called from your backend server.

Overview

Integrations

Campaigns API

Campaigns API

How It Works

Authentication

Environments

Endpoint Reference

Action: campaign_status

Request Schema

Example

Campaign fields

Collaborator fields

Action: campaign_catalog

Opening the campaign page

Signing in again through your company’s provider

Self mode (SSO user token)

Error Handling

Rate Limits

Security

Next Steps

Missions API

Authentication

​Campaigns API

​How It Works

​Authentication

​Environments

​Endpoint Reference

​Action: campaign_status

​Request Schema

​Example

​Campaign fields

​Collaborator fields

​Action: campaign_catalog

​Opening the campaign page

​Signing in again through your company’s provider

​Self mode (SSO user token)

​Error Handling

​Rate Limits

​Security

​Next Steps

Missions API

Authentication

Campaigns API

How It Works

Authentication

Environments

Endpoint Reference

Action: campaign_status

Request Schema

Example

Campaign fields

Collaborator fields

Action: campaign_catalog

Opening the campaign page

Signing in again through your company’s provider

Self mode (SSO user token)

Error Handling

Rate Limits

Security

Next Steps