HTTP request tasks

Create ⚡️Claimr tasks that utilize HTTP requests to interact with your own APIs.

What are HTTP request tasks?

HTTP Request tasks allow you to integrate your own APIs into your Claimr quests, giving you greater flexibility and control over task completion logic. These tasks send HTTP requests to your API endpoints and process the responses to determine task completion or reward amounts.

Use HTTP Request tasks to:

• Leverage your existing API infrastructure

• Configure tasks without requiring specific settings within Claimr

• Define custom logic for task completion based on the response from your API

• Validate user actions through your own backend systems

For detailed information about general task settings, including task name, header, description, rewards, dependencies, and more, refer to Task settings.

Create your task

Select HTTP Request

1. From your campaign dashboard, go to the Quests tab and click on the quest where you want to add an HTTP Request task.

2. On the quest settings page, click + Create new task.

3. In the Category section, click General.

4. In the Groups section, click Common.

5. Select HTTP Request from the Tasks list.

6. Click Continue.

Task settings

This section allows you to configure the specifics of your HTTP request task.

Task settings

Completion points: Set the number of points awarded when the user completes the task.

Points multiplier (%): Add a percentage-based bonus to the total reward. For example, a 10% multiplier increases the final reward by 10%.

Recurrence: Control how often users can complete the task:

• Once – can only be completed one time per user

• 8h – available once every eight hours

• Daily – available once every 24 hours

• Weekly – available once every 7 days

• Multiple – stays open and can be completed as many times as needed, one after another, without any waiting time

Endpoint: Enter the URL of your API endpoint that Claimr will send the HTTP request to.

• Provide the correct and complete URL, including any necessary paths or parameters

• Example placeholder: "eg. https://example.com/api/v1/account/balance"

• This ensures the request reaches the intended destination on your server

Using Claimr tags in the endpoint field

Claimr provides tags that can be used to dynamically insert values into the endpoint URL. They are useful when you need to include user-specific or campaign-related information in the request.

Available tags:

• {{address}} – the user's account identifier

• {{cs_address}} – the checksum address of the user's wallet

• {{week_start_iso}} – the start of the week in ISO 8601 format (YYYY-MM-DD)

• {{week_end_iso}} – the end of the week in ISO 8601 format

• {{day_start_iso}} – the start of the day in ISO 8601 format

• {{day_end_iso}} – the end of the day in ISO 8601 format

• {{quest_id}} – the unique ID of the current quest

• {{task_id}} – the unique ID of the current task

• {{input}} – the value entered by the user in the task's input field (if enabled)

Example:

https://your-api.com/users/{{address}}/tasks/{{task_id}}

This endpoint URL will dynamically include the user's account identifier and the current task ID when the HTTP request is sent.

Request type: Select the HTTP request method that Claimr will use when communicating with your API.

• GET – Retrieve information without modifying server data (e.g., user details, account balances, campaign statistics)

• POST – Send data to create or update a resource (e.g., submitting user information, registering accounts, processing payments)

• PUT – Update existing data on your API (e.g., modifying user profiles, changing settings, replacing data)

Headers (optional): Add custom headers to enhance the security and functionality of your HTTP requests.

• Field format: key (left column) and value (right column)

• Use headers to transmit sensitive information like authentication tokens or API keys

• Verify the legitimacy of requests and prevent unauthorized access to your API

• Specify content format (e.g., JSON, XML), caching rules, or other API requirements

Request body (optional): Include a request body in your HTTP request containing data sent to your API endpoint.

• The format depends on the Request type selected

• POST and PUT requests: Use JSON to structure the data

• GET requests: Request bodies are generally not used

• Claimr tags can also be used in the request body field

Script (optional): Add a JavaScript script to process the response from your API.

• Useful when the response is complex or requires custom logic to determine task completion or calculate rewards

• The script has access to a response object containing the data returned by your API

• Use JavaScript code to extract values, perform calculations, or apply conditions

Return value: The script must return a value that Claimr will use to determine the task outcome:

• Boolean (true or false): Indicates whether the task is completed

• Number: Specifies the number of points to award for completing the task

Examples:

Calculating rewards based on transactions:

javascript

return response.tx_count * 10;

This calculates points based on the number of transactions. Each transaction is worth 10 points.

Checking for transactions:

javascript

return response.tx_count > 0;

This checks if the user has made any transactions. If yes, the task is marked as complete.

Platform (optional): Specify the platform or context for your HTTP request task.

• For external APIs: Use a simple identifier (e.g., "Telegram")

• For Claimr token generation: Use the format organization_id::platform_name

  • Example: "ExamplE1::my_platform"

  • This helps Claimr correctly identify the user account and associate it with the task

• Leave blank when using Claimr's built-in functionality with web3 as the platform

Task button text (optional): Customize the text displayed on the button that users click to submit their input.

• Example: "Verify"

• Provides clearer instructions or context to the user

Show input (optional): Toggle this on to enable an input field for users to provide data for the task.

• If disabled, the task will not require any user input

Input label (optional): Provide a label for the input field.

• Helps users understand what kind of information they need to enter

• Only appears if "Show input" is enabled

Input placeholder (optional): Provide placeholder text within the input field.

• Provides further guidance or examples to the user

• Only appears if "Show input" is enabled

Regular Expression (optional): Define a regular expression (regex) to validate user input.

• Ensures that users provide data in a specific format or pattern

• Example placeholder: "eg. ^[a-zA-Z0-9_]+$"

• Example for Twitter links: Validate that input matches the expected format of a Twitter URL

Response in points (optional): Toggle this on to use the API response value directly as the number of points to award.

Is continous (optional): Toggle this on to enable continuous checking of the task status.

Return value handling

HTTP 200 Status Code: Indicates that the request was successfully received, understood, and accepted by the server.

Exceptions (0, "0", false): Even if the status code is 200, the actual content of the response is checked. If the response body is 0, "0", or false, it is treated as a failure or an invalid response despite the successful status code.

Example use case: Your application might consider the request successful only if:

• The server responds with a status code of 200

• The response body contains meaningful data (not 0, "0", or false)

Testing your task

Claimr provides a built-in testing tool to help you verify that your HTTP request task is configured correctly and functions as expected.

How to test:

1. Within the task settings, find the Test section

2. Enter test data:

   • Test address: Enter a test address or value for the HTTP request

   • Test input value: If your task requires user input, enter a test value

3. Click Run script to simulate task execution

4. View the response from your API to verify correct configuration

Use cases

Gift code verification: Ask users to enter a gift code and use your API to verify its validity.

Link validation: Ask users to submit a link to their social media profile or specific webpage and use regex to ensure the link is in the correct format.

KYC verification: Check if a user has completed KYC verification on your platform using their wallet address.

Save and configure

Back: Click to return to the previous screen without saving

Advance settings: Click to configure additional task settings like dependencies, completion pop-ups, and metadata

Create task: Click to save your task and add it to your quest

Pro tip: Double-check your endpoint URL and request type before launching. Use the built-in testing tool to verify your API integration works correctly. If using Claimr tags, ensure they are correctly formatted with double curly braces.

Example: KYC verification task

Scenario: Users need to complete KYC verification on your platform.

Setup:

1. KYC on your platform: Users verify their identity through their wallet

2. API endpoint: Your platform has an endpoint to check KYC status by wallet address

3. HTTP Request task configuration:

   • Endpoint: https://your-platform.com/api/kyc/{{address}}

   • Request Type: GET

   • Headers: Include authentication token for API access

   • Dynamic address: The {{address}} tag inserts the user's wallet address

Flow:

• When a user attempts the task, Claimr sends a GET request with their wallet address

• Your API checks its database and returns KYC verification status

• Claimr checks the response: if KYC is passed, the task is marked complete