🎯Challenges

This page provides an exhaustive description of all the routes available for managing challenges. Each route is explained, with its parameters, required headers, possible responses and examples of use

➡️ Get all challenges from a location

➡️ Get a location challenge

➡️ Activate location challenge

💡 Models

Challenge

Parameter	Type	Explanation	Mandatory
id	string	Unique ID for the challenge	✅
fyre_id	string	Unique Location ID in Fyre system	✅
brand_id	string	Unique ID of the brand	✅
brand_name	string	Name of the brand	✅
title	string	Title of the challenge	✅
description	string	Description of the challenge	✅
contact_email	string	Brand contact email	✅
logo_url	string	Logo URL in storage	❌
banner_url	string	Banner URL in storage	❌
terms_and_conditions	Array<string>	Terms and conditions	❌
terms_and_conditions_url	string	URL to term and conditions document	❌
goal_type	ChallengeGoalType	Type of the goal	✅
goal_amount	number	Challenge goal amount depending on the goal type: this can either be amount or quantity	✅
products	Array<ChallengeProduct>	Array of product IDs for this challenge	✅
start_date	string	Challenge start date format ISO 8601	✅
end_date	string	Challenge end date format ISO 8601	✅
location_challenge_status	LocationChallengeStatus	Challenge status (see LocationChallengeStatus for more informations)	✅
sales	{ [product_id: string]: { goal_amount: number } }	Sales grouped by product ID	❌
accepted_at	string	Date when the challenge was accepted format ISO 8601	❌
completed_at	string	Date when the challenge was completed format ISO 8601	❌
published_at	string	Date when the challenge was published format ISO 8601	❌
created_at	string	Date when the challenge was created format ISO 8601	✅
updated_at	string	Date when the challenge was updated format ISO 8601	❌

ChallengeGoalType Enum

Value	Explanation
amount	Amount to reach
quantity	Quantity to sell to reach

ChallengeProduct

Parameter	Type	Explanation	Mandatory
referential_ref	string	ID of the product in brands system	✅
name	string	Name of the product	✅
image_url	string	Image URL of the product	❌

LocationChallengeStatus Enum

Value	Explanation
published	Challenge status is set as "published" once the brand published it
accepted	Challenge status is set as "accepted" if location has accepted to participate in a challenge
completed	Challenge status is set as "completed" if location has reached the challenge goal
expired	The challenge status is set to "expired" if the challenge has ended, the location did not meet the goal in time, or the location did not participate in the challenge.
disabled	The challenge status is set to "disabled" when the brand has published the challenge, but the location's access has been revoked.

LocationChallengesFilterInput

Parameter	Type	Explanation	Mandatory
status	Array<LocationChallengeStatus>	When provided, it will return only challenges that match the specified status.	❌
brand_id	Array<string>	When provided, it will return only challenges that were published by a speicifc brand	❌

📩 Get all challenges from a location

This route enables you to retrieve the challenges linked to a specific location. It provides a detailed list of all current challenges, along with their descriptions, statuses, and other relevant details.

GET https://api.fyre.app/api/v1/locations/{fyre_id}/challenges

Requires permission:

• challenges.list

HTTP headers: X-API-KEY: <your token>

Route Params⬇️

{
    fyre_id: string // Location ID
}

Query Params

Parameter	Type	Explanation	Mandatory
filter	LocationChallengesFilterInput	If provided, it will filter the location challenges by status and/or brand.	❌

📤 Responses

200 - Success

Retrieved challenges

[]

Example:

[
  {
    "id": "string",
    "fyre_id": "string",
    "brand_id": "string",
    "brand_name": "string",
    "title": "string",
    "description": "string",
    "contact_email": "string",
    "logo_url": "string",
    "banner_url": "string",
    "terms_and_conditions": [
      "string"
    ],
    "terms_and_conditions_url": "string",
    "goal_type": "amount",
    "goal_amount": 0,
    "products": [
      {
        "referential_ref": "string",
        "name": "string",
        "image_url": "string"
      }
    ],
    "start_date": "2024-07-24T14:39:39.445Z",
    "end_date": "2024-07-24T14:39:39.445Z",
    "location_challenge_status": "published",
    "sales": "string",
    "accepted_at": "2024-07-24T14:39:39.445Z",
    "completed_at": "2024-07-24T14:39:39.445Z",
    "published_at": "2024-07-24T14:39:39.445Z",
    "created_at": "2024-07-24T14:39:39.445Z",
    "updated_at": "2024-07-24T14:39:39.445Z"
  }
]

401 - Unauthorized

Unauthorized

{
  "status": 401,
  "message": "Unauthorized, missing permission",
  "code": "UNAUTHORIZED_MISSING_PERMISSION",
  "value": ""
}

📖 Route Params Example

{
    fyre_id: "FR0100000000"
}

📩 Get a location challenge

This route allows you to retrieve details of a specific challenge linked to a location. By accessing this route, you will obtain full information on the challenge, such as its status, requirements and the results associated with the location concerned.

GET https://api.fyre.app/api/v1/locations/{fyre_id}/challenges/{challenge_id}

Requires permission:

• challenges.read

HTTP headers: X-API-KEY: <your token>

Route Params⬇️

{    
    fyre_id: string //Location ID
    challenge_id: string // Challenge ID
}

📤 Responses

200 - Success

Retrieved challenge

Example:

{
  "id": "string",
  "fyre_id": "string",
  "brand_id": "string",
  "brand_name": "string",
  "title": "string",
  "description": "string",
  "contact_email": "string",
  "logo_url": "string",
  "banner_url": "string",
  "terms_and_conditions": [
    "string"
  ],
  "terms_and_conditions_url": "string",
  "goal_type": "amount",
  "goal_amount": 0,
  "products": [
    {
      "referential_ref": "string",
      "name": "string",
      "image_url": "string"
    }
  ],
  "start_date": "2024-07-24T14:39:39.447Z",
  "end_date": "2024-07-24T14:39:39.447Z",
  "location_challenge_status": "published",
  "sales": "string",
  "accepted_at": "2024-07-24T14:39:39.447Z",
  "completed_at": "2024-07-24T14:39:39.447Z",
  "published_at": "2024-07-24T14:39:39.447Z",
  "created_at": "2024-07-24T14:39:39.447Z",
  "updated_at": "2024-07-24T14:39:39.447"
}

401 - Unauthorized

Unauthorized

{
  "status": 401,
  "message": "Unauthorized, missing permission",
  "code": "UNAUTHORIZED_MISSING_PERMISSION",
  "value": ""
}

📖 Params example

{
    fyre_id: "FR0100000000",
    challenge_id: "00kfmzzPqP9YlLT05C40"
}

📫 Activate location challenge

This route allows you to accept a challenge associated with a specific location. Once accepted, the challenge will begin tracking sales for that location in real time

POSThttps://api.fyre.app/api/v1/locations/{fyre_id}/challenges/{challenge_id}/activate

Requires permission:

• challenges.accept

HTTP headers: X-API-KEY: <your token>

Payload ⬇️

{ 
    fyre_id: string // Location ID
    challenge_id: string // Challenge ID
}

📤 Responses

200 - Success

Challenge accepted

Example:

{
  "id": "string",
  "fyre_id": "string",
  "brand_id": "string",
  "brand_name": "string",
  "title": "string",
  "description": "string",
  "contact_email": "string",
  "logo_url": "string",
  "banner_url": "string",
  "terms_and_conditions": [
    "string"
  ],
  "terms_and_conditions_url": "string",
  "goal_type": "amount",
  "goal_amount": 0,
  "products": [
    {
      "referential_ref": "string",
      "name": "string",
      "image_url": "string"
    }
  ],
  "start_date": "2024-07-24T14:39:39.449Z",
  "end_date": "2024-07-24T14:39:39.449Z",
  "location_challenge_status": "published",
  "sales": "string",
  "accepted_at": "2024-07-24T14:39:39.449Z",
  "completed_at": "2024-07-24T14:39:39.449Z",
  "published_at": "2024-07-24T14:39:39.449Z",
  "created_at": "2024-07-24T14:39:39.449Z",
  "updated_at": "2024-07-24T14:39:39.449Z"
}

401 - Unauthorized

Unauthorized

{
  "status": 401,
  "message": "Unauthorized, missing permission",
  "code": "UNAUTHORIZED_MISSING_PERMISSION",
  "value": ""
}

📖 Payload example

{
    fyre_id: "FR0100000000",
    challenge_id: "00kfmzzPqP9YlLT05C40"
}