Challenges

Challenges API

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
Improving performance over a defined period

Challenges are always published to groups of eligible outlets, never to individually identified locations.

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

How Challenges Are Created and Published

Creation
- Challenges are created by brands or brand partners via Fyre.
Publication
- Challenges target a group of outlets matching predefined criteria, such as market segment, region, or observed sales behavior.
- Criteria are evaluated internally using anonymized data.
- Brands do not see individual outlet identities at this stage.
Visibility
- Eligible outlets see published challenges via:
  - Partner dashboards
  - Integrations using the Challenges API

Challenge Lifecycle

Challenges follow a consistent lifecycle:

Published – Visible to eligible outlets.
Acceptance – Outlets explicitly choose to participate.
Tracking – Fyre automatically tracks performance based on transactional data already delivered.
Completion – Progress is evaluated until the challenge ends or expires.

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

Outlets must explicitly accept a challenge to participate.
Acceptance confirms the outlet’s intention and grants limited permission for information to be shared with the brand only if required (e.g., to deliver a reward).
Until accepted, brands cannot see which outlets participate.
Outlet information is disclosed only when strictly necessary and with consent.

This ensures outlet identities are protected by default.

Tracking and Progress

Challenge progress is tracked automatically by Fyre using the transactional data already integrated.
Outlets do not submit additional data.
Fyre performs:
- Eligibility checks
- Progress calculations
- Completion evaluation
Progress indicators may be exposed through the API for informational purposes but may not be real-time.

Scope and Availability

Challenges are available depending on:
- Partner’s integration scope
- Market
- Enabled features
Partners can only access challenge data for their connected outlets.
Available endpoints, fields, and challenge types may expand as new activation features are introduced.

Data Privacy and Safeguards

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

Brands do not know which specific outlets are targeted at publication.
Outlet identities are never exposed unless:
- The outlet accepts the challenge
- Disclosure is required for fulfillment
Raw transactional data is never exposed.
All metrics are aggregated and anonymized.

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

X-API-KEYstringRequired

Standard API Key authentication.

Path parameters

fyre_idstringRequired

The unique Location ID.

Example: FR0100000000

Query parameters

Responses

200

Success

application/json

idstringRead-onlyRequiredExample: 00kfmzzPqP9YlLT05C40

fyre_idstringRead-onlyRequiredExample: FR0100000000

titlestringRequiredExample: Summer Burger Sales Sprint

brand_namestringRequiredExample: Burger King

brand_idstringRequiredExample: BR-5544

goal_typestring · enumRequired

The metric used to determine challenge completion.

amount - Revenue target.
quantity - Unit sales target.
uplift - Growth percentage vs previous year.

Possible values:

descriptionstringOptionalExample: Sell 500 units of the new spicy burger to win.

contact_emailstring · emailOptionalExample: [email protected]

logo_urlstring · uriOptional

banner_urlstring · uriOptional

terms_and_conditions_urlstring · uriOptional

terms_and_conditionsstring[]Optional

location_challenge_statusstring · enumRequired

Current lifecycle status of the challenge.

Possible values:

start_datestring · date-timeRequiredExample: 2024-07-24T14:39:39.447Z

end_datestring · date-timeRequiredExample: 2024-08-24T14:39:39.447Z

accepted_atstring · date-timeOptional

completed_atstring · date-timeOptional

created_atstring · date-timeRequired

updated_atstring · date-timeOptional

400

Bad Request

application/json

401

Unauthorized

application/json

get

/locations/{fyre_id}/challenges

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-03-30T14:44:26.701Z",
    "completed_at": "2026-03-30T14:44:26.701Z",
    "created_at": "2026-03-30T14:44:26.701Z",
    "updated_at": "2026-03-30T14:44:26.701Z"
  }
]

Get challenge details

get

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

Required Permission: challenges.read

Authorizations

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

idstringRead-onlyRequiredExample: 00kfmzzPqP9YlLT05C40

fyre_idstringRead-onlyRequiredExample: FR0100000000

titlestringRequiredExample: Summer Burger Sales Sprint

brand_namestringRequiredExample: Burger King

brand_idstringRequiredExample: BR-5544

goal_typestring · enumRequired

The metric used to determine challenge completion.

amount - Revenue target.
quantity - Unit sales target.
uplift - Growth percentage vs previous year.

Possible values:

descriptionstringOptionalExample: Sell 500 units of the new spicy burger to win.

contact_emailstring · emailOptionalExample: [email protected]

logo_urlstring · uriOptional

banner_urlstring · uriOptional

terms_and_conditions_urlstring · uriOptional

terms_and_conditionsstring[]Optional

location_challenge_statusstring · enumRequired

Current lifecycle status of the challenge.

Possible values:

start_datestring · date-timeRequiredExample: 2024-07-24T14:39:39.447Z

end_datestring · date-timeRequiredExample: 2024-08-24T14:39:39.447Z

accepted_atstring · date-timeOptional

completed_atstring · date-timeOptional

created_atstring · date-timeRequired

updated_atstring · date-timeOptional

401

Unauthorized

application/json

404

Not Found

application/json

get

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

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-03-30T14:44:26.701Z",
  "completed_at": "2026-03-30T14:44:26.701Z",
  "created_at": "2026-03-30T14:44:26.701Z",
  "updated_at": "2026-03-30T14:44:26.701Z"
}

Activate challenge

post

Accept a challenge to begin tracking sales for that location.

Required Permission: challenges.accept

Authorizations

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

fyre_idstringRequired

Must match the location in the URL.

challenge_idstringRequired

Must match the challenge in the URL.

Responses

200

Challenge Accepted

application/json

idstringRead-onlyRequiredExample: 00kfmzzPqP9YlLT05C40

fyre_idstringRead-onlyRequiredExample: FR0100000000

titlestringRequiredExample: Summer Burger Sales Sprint

brand_namestringRequiredExample: Burger King

brand_idstringRequiredExample: BR-5544

goal_typestring · enumRequired

The metric used to determine challenge completion.

amount - Revenue target.
quantity - Unit sales target.
uplift - Growth percentage vs previous year.

Possible values:

descriptionstringOptionalExample: Sell 500 units of the new spicy burger to win.

contact_emailstring · emailOptionalExample: [email protected]

logo_urlstring · uriOptional

banner_urlstring · uriOptional

terms_and_conditions_urlstring · uriOptional

terms_and_conditionsstring[]Optional

location_challenge_statusstring · enumRequired

Current lifecycle status of the challenge.

Possible values:

start_datestring · date-timeRequiredExample: 2024-07-24T14:39:39.447Z

end_datestring · date-timeRequiredExample: 2024-08-24T14:39:39.447Z

accepted_atstring · date-timeOptional

completed_atstring · date-timeOptional

created_atstring · date-timeRequired

updated_atstring · date-timeOptional

401

Unauthorized

application/json

404

Not Found

application/json

post

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

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-03-30T14:44:26.701Z",
  "completed_at": "2026-03-30T14:44:26.701Z",
  "created_at": "2026-03-30T14:44:26.701Z",
  "updated_at": "2026-03-30T14:44:26.701Z"
}

PreviousHeadless Authentication (SSO)NextChallenges

Last updated 24 days ago

hashtagChallenges API

hashtagHow Challenges Are Created and Published

hashtagChallenge Lifecycle

hashtagOutlet Acceptance and Consent

hashtagTracking and Progress

hashtagScope and Availability

hashtagData Privacy and Safeguards

hashtagGet location challenges

hashtagGet challenge details

hashtagActivate challenge

Challenges API

How Challenges Are Created and Published

Challenge Lifecycle

Outlet Acceptance and Consent

Tracking and Progress

Scope and Availability

Data Privacy and Safeguards

Get location challenges

Get challenge details

Activate challenge