Challenges

The Challenges API allows POS partners to retrieve and interact with challenge-based activations available for their connected outlets.

Challenges are activation campaigns created by brands to encourage specific behaviors, such as increasing sales of certain products, reaching volume targets, or improving performance over a defined period. Challenges are always published to groups of eligible outlets, never to individually identified locations.

At the time a challenge is created or published, brands do not know which specific outlets will participate. Outlet-level visibility and participation are controlled entirely by the outlet.

All challenge data exposed through the API is based on anonymized and aggregated information. The API does not expose raw transactional data and does not allow access to data belonging to other outlets.

How challenges are created and published

Challenges are created and published by brands or brand partners through Fyre.

When a challenge is published, it targets a group of outlets that match predefined criteria such as market segment, region, or observed sales behavior. These criteria are evaluated internally by Fyre using anonymized data. Brands do not receive the identities of individual outlets at this stage.

Once published, the challenge becomes visible to eligible outlets through Fyre-powered interfaces, including partner dashboards and integrations using the Challenges API.

Challenge lifecycle

Challenges follow a simple and consistent lifecycle.

A challenge is published and made visible to a set of eligible outlets. Each outlet then decides whether to participate by accepting the challenge. Once accepted, performance is tracked automatically based on transactional data already delivered through the integration. Progress is evaluated throughout the challenge period until the challenge is completed or expires.

All tracking, scoring, and completion logic is handled internally by Fyre.

Outlet acceptance and consent

Outlets must explicitly accept a challenge before they can participate.

Accepting a challenge serves two purposes. It confirms the outlet’s intention to participate in the activation, and it grants permission for limited outlet information to be shared with the brand only if required to fulfill the challenge outcome, such as delivering a reward or prize.

Until a challenge is accepted, brands have no visibility into which specific outlets are participating. Even after acceptance, outlet information is disclosed only when strictly necessary and only for fulfillment purposes.

This consent-based model ensures that outlet identities are protected by default and shared only with explicit approval.

Tracking and progress

Challenge progress is tracked automatically by Fyre based on transactional data received through the integration.

Outlets are not required to submit additional data or perform manual reporting. Eligibility checks, progress calculations, and completion evaluation are performed internally by Fyre.

Where supported, progress indicators and status updates are exposed through the API. These indicators are provided for informational purposes and may not represent real-time calculations.

Scope and availability

Challenge availability depends on the partner’s integration scope, market, and enabled features.

Only challenges that are relevant to the partner and applicable to their connected outlets are exposed through the API. Partners can only access challenge data for their own outlets.

The set of available endpoints, fields, and challenge types may expand over time as additional activation features are enabled.

Data privacy and safeguards

The Challenges API is built around privacy, transparency, and trust.

Brands do not know which specific outlets are targeted when a challenge is published. Outlet identities are not exposed unless an outlet explicitly accepts a challenge and disclosure is required for fulfillment. Raw transactional data is never exposed through the Challenges API, and all challenge metrics are based on aggregated and anonymized data.

This model allows brands to run effective activations while preserving outlet anonymity and control at all times.

Get location challenges

get

Retrieve a list of all challenges linked to a specific location.

Required Permission: challenges.list

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Standard API Key authentication.

Path parameters

fyre_idstringRequired

The unique Location ID.

Example: FR0100000000

Query parameters

Responses

200

Success

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

get

/locations/{fyre_id}/challenges

cURLJavaScript (Fetch)JavaScript (Axios)

curl --request GET \
  --url 'https://api.fyre.app/api/v1/locations/FR0100000000/challenges?filter[status][]=published' \
  --header 'X-API-KEY: YOUR_TOKEN'

[
  {
    "id": "00kfmzzPqP9YlLT05C40",
    "fyre_id": "FR0100000000",
    "title": "Summer Burger Sales Sprint",
    "brand_name": "Burger King",
    "brand_id": "BR-5544",
    "goal_type": "amount",
    "description": "Sell 500 units of the new spicy burger to win.",
    "contact_email": "[email protected]",
    "logo_url": "https://example.com",
    "banner_url": "https://example.com",
    "terms_and_conditions_url": "https://example.com",
    "terms_and_conditions": [
      "text"
    ],
    "location_challenge_status": "published",
    "start_date": "2024-07-24T14:39:39.447Z",
    "end_date": "2024-08-24T14:39:39.447Z",
    "goals": {
      "quantity": 500,
      "revenue": 15000.5
    },
    "products": [
      {
        "referential_ref": "PRD-998877",
        "name": "Spicy Chicken Burger",
        "image_url": "https://cdn.fyre.app/products/burger.jpg"
      }
    ],
    "sales": {
      "PRD-001": {
        "quantity": 50,
        "revenue": 500
      }
    },
    "accepted_at": "2026-02-12T23:17:28.908Z",
    "completed_at": "2026-02-12T23:17:28.908Z",
    "created_at": "2026-02-12T23:17:28.908Z",
    "updated_at": "2026-02-12T23:17:28.908Z"
  }
]

Get challenge details

get

Retrieve full details of a specific challenge, including goals, products, and terms.

Required Permission: challenges.read

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Standard API Key authentication.

Path parameters

fyre_idstringRequired

The unique Location ID.

Example: FR0100000000

challenge_idstringRequired

The unique Challenge ID.

Example: 00kfmzzPqP9YlLT05C40

Responses

200

Success

application/json

401

Unauthorized

application/json

404

Not Found

application/json

get

/locations/{fyre_id}/challenges/{challenge_id}

cURLJavaScript (Fetch)JavaScript (Axios)

curl --request GET \
  --url https://api.fyre.app/api/v1/locations/FR0100000000/challenges/00kfmzzPqP9YlLT05C40 \
  --header 'X-API-KEY: YOUR_TOKEN'

{
  "id": "00kfmzzPqP9YlLT05C40",
  "fyre_id": "FR0100000000",
  "title": "Summer Burger Sales Sprint",
  "brand_name": "Burger King",
  "brand_id": "BR-5544",
  "goal_type": "amount",
  "description": "Sell 500 units of the new spicy burger to win.",
  "contact_email": "[email protected]",
  "logo_url": "https://example.com",
  "banner_url": "https://example.com",
  "terms_and_conditions_url": "https://example.com",
  "terms_and_conditions": [
    "text"
  ],
  "location_challenge_status": "published",
  "start_date": "2024-07-24T14:39:39.447Z",
  "end_date": "2024-08-24T14:39:39.447Z",
  "goals": {
    "quantity": 500,
    "revenue": 15000.5
  },
  "products": [
    {
      "referential_ref": "PRD-998877",
      "name": "Spicy Chicken Burger",
      "image_url": "https://cdn.fyre.app/products/burger.jpg"
    }
  ],
  "sales": {
    "PRD-001": {
      "quantity": 50,
      "revenue": 500
    }
  },
  "accepted_at": "2026-02-12T23:17:28.908Z",
  "completed_at": "2026-02-12T23:17:28.908Z",
  "created_at": "2026-02-12T23:17:28.908Z",
  "updated_at": "2026-02-12T23:17:28.908Z"
}

Activate challenge

post

Accept a challenge to begin tracking sales for that location.

Required Permission: challenges.accept

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Standard API Key authentication.

Path parameters

fyre_idstringRequired

The unique Location ID.

Example: FR0100000000

challenge_idstringRequired

The unique Challenge ID.

Example: 00kfmzzPqP9YlLT05C40

Body

application/json

fyre_idstringRequired

Must match the location in the URL.

challenge_idstringRequired

Must match the challenge in the URL.

Responses

200

Challenge Accepted

application/json

401

Unauthorized

application/json

404

Not Found

application/json

post

/locations/{fyre_id}/challenges/{challenge_id}/activate

cURLJavaScript (Fetch)JavaScript (Axios)

curl --request POST \
  --url https://api.fyre.app/api/v1/locations/FR0100000000/challenges/00kfmzzPqP9YlLT05C40/activate \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_TOKEN' \
  --data '{
	"fyre_id": "FR0100000000",
	"challenge_id": "00kfmzzPqP9YlLT05C40"
}'

{
  "id": "00kfmzzPqP9YlLT05C40",
  "fyre_id": "FR0100000000",
  "title": "Summer Burger Sales Sprint",
  "brand_name": "Burger King",
  "brand_id": "BR-5544",
  "goal_type": "amount",
  "description": "Sell 500 units of the new spicy burger to win.",
  "contact_email": "[email protected]",
  "logo_url": "https://example.com",
  "banner_url": "https://example.com",
  "terms_and_conditions_url": "https://example.com",
  "terms_and_conditions": [
    "text"
  ],
  "location_challenge_status": "published",
  "start_date": "2024-07-24T14:39:39.447Z",
  "end_date": "2024-08-24T14:39:39.447Z",
  "goals": {
    "quantity": 500,
    "revenue": 15000.5
  },
  "products": [
    {
      "referential_ref": "PRD-998877",
      "name": "Spicy Chicken Burger",
      "image_url": "https://cdn.fyre.app/products/burger.jpg"
    }
  ],
  "sales": {
    "PRD-001": {
      "quantity": 50,
      "revenue": 500
    }
  },
  "accepted_at": "2026-02-12T23:17:28.908Z",
  "completed_at": "2026-02-12T23:17:28.908Z",
  "created_at": "2026-02-12T23:17:28.908Z",
  "updated_at": "2026-02-12T23:17:28.908Z"
}