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 a deep link into the SalesOS module for the action itself.

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": "pontos" },
        "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, "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
`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

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.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"
  }'

Self mode (federated session)

With a federated user token, 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

Self mode (federated session)

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

​Self mode (federated session)

​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

Self mode (federated session)

Error Handling

Rate Limits

Security

Next Steps