# HTTP request tasks

## What is HTTP request task?

HTTP request tasks allow you to integrate your own APIs into your claimr quests, giving you greater flexibility and control over task completion logic.

**Use HTTP requst 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.

{% hint style="info" %}
For detailed information about general task settings, including task name, header, description, rewards, dependencies, and more, refer to [task-settings](https://claimr-io.gitbook.io/claimr-help-center/tasks/task-settings "mention").&#x20;
{% endhint %}

## **Task type**

This section allows you to choose the specific type of task you want to create for your campaign.&#x20;

<figure><img src="https://2111509621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBtEHhi1fQEriwxTxRejw%2Fuploads%2FvJxP5EKsS3o8y6QV2Pe8%2FScreenshot%202024-11-19%20at%2017.43.29.png?alt=media&#x26;token=15a8fa30-9605-4dab-a963-1f8c94ac85fa" alt="" width="375"><figcaption><p>Select Web and HTTP Request</p></figcaption></figure>

1. **Select `Web`:** This indicates that the task involves interactions with a web-based platform or service.
2. **Choose `HTTP Request`:** From the expanded list of web-based task types, select `HTTP Request`.&#x20;

Now, you are able to configure the specific settings for your task, such as the endpoint URL, request method, and response handling.

## Task settings

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

<figure><img src="https://2111509621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBtEHhi1fQEriwxTxRejw%2Fuploads%2F5VkoTyIaRXAbqyyMKuCc%2FScreenshot%202024-11-19%20at%2017.46.00.png?alt=media&#x26;token=3d42c635-056b-4247-bc24-f16c58d8d745" alt="" width="375"><figcaption><p>Task settings, part 1</p></figcaption></figure>

### Endpoint&#x20;

Enter the URL of your API endpoint that claimr will send the HTTP request to. It's essential to provide the correct and complete URL, including any necessary paths or parameters. This ensures the request reaches the intended destination on your server.

**Return value:**&#x20;

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:** \
When making an API call, 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).

### **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.

* **`{{address}}`**&#x74;he user's account identifier.
* **`{{cs_address}}`**&#x74;he 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}}`**&#x74;he end the week in ISO 8601 format.
* **`{{day_start_iso}}`**&#x74;he start 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. \
The available options are:

* **`GET`:** When you send a GET request, your API will return the requested data without modifying anything on the server. This is useful for retrieving information like user details, account balances, or campaign statistics.
* **`POST`:** A POST request sends data to your API to create or update a resource. This is often used for actions like submitting user information, registering new accounts, or processing payments.
* **`PUT`:** A PUT request updates existing data on your API. This is typically used for modifying existing resources, such as updating user profiles, changing settings, or replacing data.

### **Headers (optional)**

Headers enhance the security and functionality of your HTTP requests. Use them to transmit sensitive information like authentication tokens or API keys, which verify the legitimacy of the request and prevent unauthorized access to your API.

<figure><img src="https://2111509621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBtEHhi1fQEriwxTxRejw%2Fuploads%2F4qS6lp2jGO3fUBI8jPqJ%2FScreenshot%202024-11-19%20at%2018.09.01.png?alt=media&#x26;token=392f1f9d-7284-4775-9544-eea5cd6802ad" alt="" width="375"><figcaption><p>Example for headers</p></figcaption></figure>

The screenshot provides a visual example of how headers are added. The specific header ("x-access-token") and value shown are illustrative and don't represent an actual header used in claimr. Include custom headers in your HTTP request to provide additional context and instructions to your API.

Use headers for these purposes:

* **Authentication:** Include an authentication token or API key to verify the request's origin and prevent unauthorized access.
* **Content Negotiation:** Specify the format of the data being sent or requested (e.g., JSON, XML).
* **Caching:** Control how your API caches the request or response.

### **Request body (optional)**

Use this field to include a request body in your HTTP request. The request body contains the data sent to your API endpoint. The format of this data depends on the `Request type` you selected:

* **`POST` and `PUT` requests:** Use JSON  to structure the data in the request body. This allows you to send complex data structures to your API.
* **`GET` requests:** Request bodies are generally not used with `GET` requests.&#x20;

{% hint style="warning" %}
claimr tags mentioned in the endpoint section can also be used for the request body filed.&#x20;
{% endhint %}

### **Script (optional)**

Use this field to add a JavaScript script to process the response from your API. This is useful when the response is complex or requires custom logic to determine task completion or calculate rewards.

* **`response` object:** The script has access to a `response` object, which contains the data returned by your API. You can use JavaScript code to extract values, perform calculations, or apply conditions to this data.
* **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 example calculates the number of points to award based on the number of transactions (`tx_count`) reported by the API. Each transaction is worth 10 points, so the script multiplies the `tx_count` by 10 and returns the result.

#### Checking for transactions

```javascript
return response.tx_count > 0;
```

This example checks if the API response indicates that the user has made any transactions (`tx_count`). If the `tx_count` is greater than 0, the task is marked as complete (`true`).

### **Platform (optional)**

This field allows you to specify the platform or context for your HTTP request task. It's used in specific situations where you need to differentiate between different environments or integrate with claimr's token generation feature.

**How to specify the Platform:**

* **For external APIs:** Use a simple identifier that represents the platform. Example: Telegram
* **For claimr token generation:** Use the organization ID, followed by two colons (`::`), and then the platform name used during token generation. This helps claimr correctly identify the user account and associate it with the task.

#### **Example**

<figure><img src="https://2111509621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBtEHhi1fQEriwxTxRejw%2Fuploads%2FjM3p5Mj65FgUQOaJdBuu%2FScreenshot%202024-11-19%20at%2019.51.25.png?alt=media&#x26;token=2ceb31a1-b079-4659-b00d-c6c6bf4f5750" alt="" width="375"><figcaption><p>Example of a Platform field</p></figcaption></figure>

In the screenshot, the platform is specified as `ExamplE1::my_platform`. This indicates that the task is associated with the organization ID `ExamplE1` and the platform `my_platform`, which was likely used during token generation.

**When to leave blank:**

* **web3 as the platform:** If you're using claimr's built-in functionality and not interacting with an external API, you should leave this field blank.

### **Regular expression (optional)**

You can define a regular expression (regex) to validate user input. This is useful when you want to ensure that users provide data in a specific format or pattern.

<figure><img src="https://2111509621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBtEHhi1fQEriwxTxRejw%2Fuploads%2Fkfx0rxpbBwl8CWEW3lQu%2FScreenshot%202024-11-19%20at%2022.22.46.png?alt=media&#x26;token=23f84ade-93bf-412d-a26e-9238ca9530f8" alt="" width="375"><figcaption><p>Example of regular expression</p></figcaption></figure>

In the screenshot, the regex is used to validate Twitter links. This regex will ensure that any input provided by the user matches the expected format of a Twitter URL.

### **Task button text (optional)**

Customize the text displayed on the button that users click to submit their input for the task. This can help provide clearer instructions or context to the user. **Example:** Send link.

### **Show input (optional)**

Enable an input field for the user to provide data for the task. If the toggle is disabled, the task will not require any user input.

### **Input label (optional)**

Provide a label for the input field. This label helps users understand what kind of information they need to enter. **Example:** "Twitter link" clearly indicating that the user needs to provide a Twitter link in the input field.

### **Input placeholder (optional)**

Provide placeholder text within the input field. This text can provide further guidance or examples to the user. **Example:** "Enter your Twitter link here" or "e.g., [https://twitter.com/claimr](https://www.google.com/url?sa=E\&source=gmail\&q=https://twitter.com/claimr)".

### **Use cases**

* **Gift code:** Ask users to enter a gift code they received and use your API to verify its validity.
* **Link:** Ask users to submit a link to their social media profile or a specific webpage and use a regex to ensure the link is in the correct format.

## **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. This tool allows you to simulate a user attempting the task and see the response from your API.

<figure><img src="https://2111509621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBtEHhi1fQEriwxTxRejw%2Fuploads%2FS2WSV1GVpeDHMOH1TSj2%2FScreenshot%202024-11-19%20at%2023.03.42.png?alt=media&#x26;token=569993f6-845d-4d3a-9b05-f94e299170dc" alt="" width="375"><figcaption><p>Task testing section</p></figcaption></figure>

1. **Access the test section:** Within the task settings, you'll find a section labeled Test. This section provides fields and a button for testing your task.
2. **Provide test data:**
   * **Test address:** Enter a test address or value that will be used in the HTTP request. This could be a user's wallet address, a test API key, or any other relevant data that your API expects.
   * **Test input value:** If your task requires user input, enter a test value here. This value will be included in the HTTP request as if a user had submitted it.
3. **Run the script:** Click [<mark style="color:green;">**Run script**</mark>](#user-content-fn-1)[^1] button to simulate the task execution. claimr will send the HTTP request to your API endpoint, using the provided test data and any configured headers or scripts.
4. **View the response:** The testing tool will display the response received from your API. This allows you to verify that your API is responding correctly and that your task script (if any) is processing the response as expected.

## **Recurrence**

This setting determines how often users can complete the HTTP request task.

* **Once:** This is the default setting. Users can only complete the task once.
* **Daily:** The task resets every day, allowing users to complete it again each day.
* **Weekly:** The task resets every week, allowing users to complete it again each week.

While setting up your HTTP request task, it's important to double-check your settings to avoid errors. Ensure that you have entered the correct endpoint URL and selected the appropriate request type. If you're using any claimr tags, make sure they are correctly formatted.

## **Example of an HTTP request task: KYC verification**

Let's say a user needs to complete a KYC (Know Your Customer) verification on your platform. This could involve verifying their identity using their wallet address. Create an HTTP request task in claimr to check if the user has successfully completed KYC. Here's how it works:

1. **KYC Verification on your platform:** The user goes through the KYC process on your platform, which likely involves verifying their identity through their wallet.
2. **API endpoint for KYC status:** Your platform has an API endpoint that allows you to check the KYC status of a user based on their wallet address.
3. **HTTP request task in claimr:** You create an HTTP request task in claimr with the following settings:
   * **Endpoint:** The URL of your KYC status API endpoint.
   * **Request Type:** `GET` (since you're retrieving information).
   * **Headers:** Any necessary headers for authentication or authorization to your API.
4. **Dynamic wallet address:** In the endpoint URL, use a tag to dynamically insert the user's wallet address into the request.&#x20;
5. **API response:** When a user attempts the task, claimr sends a GET request to your API endpoint, including the user's wallet address. Your API checks its database and returns a response indicating whether the user has passed KYC verification.
6. **Task completion:** claimr checks the API response. If the response confirms that the user has passed KYC, the task is marked as complete. If not, the task remains incomplete.

[^1]:
