> For the complete documentation index, see [llms.txt](https://docs.joinfoundhero.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.joinfoundhero.com/endpoints/requests.md).

# 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 %}