# Requests

The Found Hero API allows you to programmatically manage your requests. A location is a lost item request where a guest claim that he lost an item in a specific location

### Available requests status

|    Status    |
| :----------: |
| `INCOMPLETE` |
|   `PENDING`  |
|   `MATCHED`  |
|  `REJECTED`  |

## Retrieve a Request

<mark style="color:blue;">`GET`</mark> `https://api.joinfoundhero.com/v1/locations/:lid/requests/:id`

Retrieves the details of a request that has previously been created. Supply `lid` that is the unique ID of location and  `id` that is the id of the request

#### Path Parameters

| Name | Type   | Description            |
| ---- | ------ | ---------------------- |
| lid  | string | The unique location ID |
| id   | string | The unique request ID  |

{% tabs %}
{% tab title="200 " %}

```
{
    "status": true,
    "data": {
        "_id": "60e99edfcb90adfe2658a42d",
        "archived": false,
        "location": {
            "_id": "5ff8a9d374334bcad6a44140",
            "pickupTime": {
                "from": "08:00",
                "to": "17:00"
            },
            "storageDuration": 30,
            "active": true,
            "account": "5f608dee4565e4a213cd5c07",
            "name": "Demo US Hotel (Marriott)",
            "permalink": "demo-us-hotel",
            "identifier": "zguUfC5SqYVy",
            "website": "",
            "description": "",
            "type": "hotel",
            "contact": {
                "name": "Greg Bessoni",
                "email": "hello@joinfoundhero.com",
                "email2": "",
                "phone": "8609649001"
            },
            "storagePlace": "Reception",
            "address1": "220 Old Boston Post Rd.",
            "address2": "",
            "city": "Old Saybrook",
            "state": "CT",
            "zipCode": "06475",
            "country": "US",
            "createdAt": "2021-01-08T18:52:03.989Z",
            "updatedAt": "2021-03-11T16:51:43.168Z",
            "__v": 0,
            "featured": false,
            "hidden": false,
            "noindex": false,
            "logoUrl": "https://cdn.joinfoundhero.com/l/7473d225-64c5-4b4f-b8c7-23a33582680e.png",
            "latitude": null,
            "longitude": null
        },
        "identifier": "7jXm9EW8VGZh",
        "description": "test",
        "lostPlace": "test",
        "checkoutDate": "2021-07-06T00:00:00.000Z",
        "owner": {
            "firstName": "test",
            "lastName": "test",
            "email": "test@test.com",
            "phone": "3333333333"
        },
        "status": "PENDING",
        "proof": "test",
        "createdAt": "2021-07-10T13:21:35.026Z",
        "updatedAt": "2021-07-10T13:21:35.026Z",
        "__v": 0
    }
}
```

{% endtab %}
{% endtabs %}

## Retrieve all requests

<mark style="color:blue;">`GET`</mark> `https://api.joinfoundhero.com/v1/locations/:lid/requests`

Retrieve all requests created previously. By default, this method returns a set of top 10 requests.\
\
This method also supports pagination. You can use `limit` and `page` query parameters to control pagination.&#x20;

#### Path Parameters

| Name | Type   | Description            |
| ---- | ------ | ---------------------- |
| lid  | string | The unique location ID |

#### Query Parameters

| Name  | Type    | Description                                                                                          |
| ----- | ------- | ---------------------------------------------------------------------------------------------------- |
| page  | integer | The current page number. the default value is 1                                                      |
| limit | integer | the number of results per page. The value must be between `10` and `100`. The default value is `10`. |

{% tabs %}
{% tab title="200 " %}

```
{
    "status": true,
    "data": {
        "requests": [
            {
                "_id": "60e99edfcb90adfe2658a42d",
                "archived": false,
                "location": "5ff8a9d374334bcad6a44140",
                "identifier": "7jXm9EW8VGZh",
                "description": "test",
                "lostPlace": "test",
                "checkoutDate": "2021-07-06T00:00:00.000Z",
                "owner": {
                    "firstName": "test",
                    "lastName": "test",
                    "email": "test@test.com",
                    "phone": "3333333333"
                },
                "status": "PENDING",
                "proof": "test",
                "createdAt": "2021-07-10T13:21:35.026Z",
                "updatedAt": "2021-07-10T13:21:35.026Z",
                "__v": 0
            },
            {
                "_id": "60e99e97cb90adfe2658a42c",
                "archived": false,
                "location": "5ff8a9d374334bcad6a44140",
                "identifier": "zZ3kVF7hdNyB",
                "description": "LALALALAL",
                "lostPlace": "sjsjsjsjsjs",
                "checkoutDate": "2021-07-10T00:00:00.000Z",
                "owner": {
                    "firstName": "Test",
                    "lastName": "Test",
                    "email": "imadharilla@gmail.com",
                    "phone": "29292929"
                },
                "status": "PENDING",
                "createdAt": "2021-07-10T13:20:23.197Z",
                "updatedAt": "2021-07-10T13:20:23.197Z",
                "__v": 0
            }
        ],
        "page": 1,
        "limit": 10,
        "count": 22,
        "totalPages": 3,
        "hasMore": true
    }
}
```

{% endtab %}
{% endtabs %}

## Update Request Status

<mark style="color:orange;">`PUT`</mark> `https://api.joinfoundhero.com/v1/locations/:lid/requests/:id/update-status`

Using this endpoint  you can accept/reject a request by sending a body parameters `type` .

#### Path Parameters

| Name | Type   | Description            |
| ---- | ------ | ---------------------- |
| id   | string | The unique request ID  |
| lid  | string | The unique location ID |

#### Request Body

| Name | Type   | Description          |
| ---- | ------ | -------------------- |
| type | string | `reject` or `accept` |

{% tabs %}
{% tab title="200 " %}

```
{
    "status": true,
    "message": "Lost item request is updated",
    "data": {
        "owner": {
            "firstName": "test",
            "lastName": "test",
            "email": "test@test.com",
            "phone": "3333333333"
        },
        "archived": false,
        "_id": "60e99edfcb90adfe2658a42d",
        "location": "5ff8a9d374334bcad6a44140",
        "identifier": "7jXm9EW8VGZh",
        "description": "test",
        "lostPlace": "test",
        "checkoutDate": "2021-07-06T00:00:00.000Z",
        "status": "REJECTED",
        "proof": "test",
        "createdAt": "2021-07-10T13:21:35.026Z",
        "updatedAt": "2021-07-13T10:39:21.431Z",
        "__v": 0,
        "matchDate": "2021-07-13T10:39:21.428Z"
    }
}
```

{% endtab %}
{% endtabs %}

## Create new lost item request

<mark style="color:green;">`POST`</mark> `https://api.joinfoundhero.com/v1/locations/:lid/requests`

#### Path Parameters

| Name | Type   | Description            |
| ---- | ------ | ---------------------- |
| lid  | string | The unique location ID |

#### Request Body

| Name         | Type   | Description                                                    |
| ------------ | ------ | -------------------------------------------------------------- |
| proof        | string | Describe why this item is yours                                |
| owner        | object | an object containing : `firstName`  `lastName` `email` `phone` |
| checkoutDate | string | Request lost date                                              |
| lostPlace    | string | Request last known place                                       |
| description  | string | Request description                                            |

{% tabs %}
{% tab title="200 " %}

```
{
    "status": true,
    "message": "Lost item request created successfully",
    "data": {
        "archived": false,
        "_id": "60ed7c70cb90adfe2658a433",
        "location": "5ff8a9d374334bcad6a44140",
        "identifier": "iMelZWZdi4rp",
        "description": "test",
        "lostPlace": "test",
        "checkoutDate": "2021-07-06T00:00:00.000Z",
        "owner": {
            "firstName": "test",
            "lastName": "test",
            "email": "test@test.com",
            "phone": "3333333333"
        },
        "status": "PENDING",
        "createdAt": "2021-07-13T11:43:44.706Z",
        "updatedAt": "2021-07-13T11:43:44.706Z",
        "__v": 0
    }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.joinfoundhero.com/endpoints/requests.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.