# Overview Found Hero provides a simple yet powerful API to build and automate a lost and found solution into your management software. The Found Hero API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support [cross-origin resource sharing](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing), allowing you to interact securely with our API from a client-side web application (though you should never expose your secret access token in any public website's client-side code). ### API Keys Before you start using our RESTful API services, you'll need to [create an account](https://app.joinfoundhero.com/signup) on Found Hero to obtain an API key. Once your account is approved, you can use the API key to [authenticate](/authentication#login) with Found Hero API and then make HTTP requests. To obtain an API key, do the following: 1. [Login](https://app.joinfoundhero.com/login) to your Found Hero account. 2. Go to the [account settings](https://app.joinfoundhero.com/dashboard/settings#api-keys) page and then open the "API Keys" tab to view and manage your API keys. Found Hero also provides a sandbox environment that you can use for development and testing. This environment acts the same way as production. All user accounts, passwords, and locations are independent of the production environment. To use our sandbox environment, you'll need to [create a sandbox account](https://demo.joinfoundhero.com/signup) as well. ### Requests The API accepts only HTTP requests with `Content-Type` set to `application/json` and a [JSON](http://json.org/) body depending on the operation to be performed. The Found Hero API is served over HTTPS and unencrypted HTTP connections are not supported. For the production environment, all HTTP requests should use the following base URL: ```bash https://api.joinfoundhero.com/v1/ ``` If you are using the Found Hero API within the sandbox environment, use the following base URL: ```bash https://sandbox-api.joinfoundhero.com/v1/ ``` ### Responses All API requests return a JSON-encoded response with `Content-Type` set to `application/json`. If the request is successful, the HTTP status code returned is `200` and the JSON content contains appropriate result according to the operation. For a typical HTTP request, the returned JSON object has the following properties: | Property | Type | | Description | | --------- | ------- | -------- | ------------------------------------------------------------------------------------------------ | | `status` | boolean | required | A `true` or `false` value indicating the outcome of the operation. | | `message` | string | optional | A human-readable string that provides additional information about the outcome of the operation. | | `data` | object | optional | The actual JSON content containing the result of the operation. | ### Support If you encounter any issue with the API, have any questions, or want to share your feedback, please send us an email at . # Authentication The Found Hero API uses [API keys](/#api-keys) to authenticate requests. You can view and manage your API keys in the [account settings](https://app.joinfoundhero.com/dashboard/settings#api-keys) page. Each request you make to the API must include the following HTTP header in order to authenticate with Found Hero API: ```bash fh-api-key: {YOUR_API_KEY} ``` Replace the `YOUR_API_KEY` with your own API key. All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. API requests without the above `fh-api-key` header will also fail. {% hint style="warning" %} **Keep Your API Keys Secure** Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Make sure to familiarize yourself with security best practices around storing and using API keys. Never ever hard-code the API key into source control systems like Git, but extract this information into environment variables instead. In the event, your API key is compromised, immediately revoke it from your account dashboard and create a new API key. {% endhint %} # Errors The Found Hero API uses standard HTTP error and status codes to communicate errors. There are multiple HTTP status codes for different types of errors: * `200 Ok` — The request was performed successfully. * `400 Bad Request` — The request was unacceptable, often due to missing a required parameter. * `401 Unauthorized` — No valid access token provided. The access token was either missing or expired. * `403 Forbidden` — The access token doesn't have permission to perform the request. * `404 Not Found` — The requested resource doesn't exist. * `422 Unprocessable Entity` — The request was malformed. * `500 Internal Server Error` — An unexpected error ocurred on our server. In most cases, such an error represents a bug on our side. We automatically log such errors and fix them quickly. If anything like this persists, feel free to directly [contact us](/#support). In case of an error, `status` is set to `false` in the returned JSON object. The `message` property contains an explanation specific to that error. This is the property that is most useful to a human. Here is an example JSON response for `401 Unauthorized`: ```javascript { "status": false, "message": "Authentication failed. Wrong password." } ``` # Webhooks Found Hero uses webhooks to notify your application when the status of the lost item changes. You can subscribe to our webhooks to receive important updates related to your lost items. ### Setting up webhooks To subscribe to Found Hero webhooks, follow the following steps: 1. Create a webhook endpoint at your server. 2. [Login](https://app.joinfoundhero.com/login) to your Found Hero account. 3. Go to the [account settings](https://demo.joinfoundhero.com/dashboard/settings#webhooks) page and then open the "Webhooks" tab. 4. Register the webhook endpoint with Found Hero. 5. By ready to receive notifications. {% hint style="warning" %} When you register a webhook endpoint, Found Hero sends an HTTP POST request to the URL to verify if it is valid. For a valid webhook URL, Found Hero expects HTTP 200 status code. {% endhint %} ### Event types At the moment, Found Hero supports the following events: | Event | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------- | | `pickup` | This event is sent when the owner chooses to pick up the lost item by himself. | | `discard` | This event is sent when the owner decides to leave the lost item behind. | | `donate` | This event is sent when the owner asks to donate the lost item to a charity of your own choice. | | `shipping-label` | This event is sent when the owner pays the shipping fees to get the lost item back. | | `request` | This event is sent when a user creates a lost item request and claim that he lost an item in a specific location. | ### Receiving notifications Whenever a new event happens, Found Hero will send an HTTP POST request to the webhook URL that you have configured in your [account settings](https://demo.joinfoundhero.com/dashboard/settings#webhooks). The `Content-Type` of the request is set to `application/json` and the body of the request is a [JSON](http://json.org/) object that has the following properties: | Property | Type | | Description | | ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------- | | `eventType` | string | required | The type of event (`pickup`, `donate`, `discard`, `request`, or `shipping-label`) | | `eventTime` | string | required | The date and time the event occurred in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format. | | `payload` | object | required | A JSON object that contains information about the event. | The `payload` object contains the following properties: | Property | Type | | Description | | -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `item` | object | required | The [lost item](/endpoints/items#retrieve-an-item) object | | `pickupDate` | String | optional | The pick-up date in `YYYY-MM-DD` format. Only available for `pickup` events. | | `pickupTime` | String | optional | The pick-up time in `HH:mm` format. Only available for `pickup` events. | | `shippingDate` | String | optional | Ship date in `YYYY-MM-DD` format. Only available for `shipping-label` events. | | `serviceName` | string | optional | The name of the courier service. Only available for `shipping-label` events. | | `files` | object | optional | A JSON object containing information about the shipping label and payment invoice. Only available for `shipping-label` events. | For a typical `shipping-label` event notification, the HTTP POST request body looks like the following: ```javascript { "eventType": "shipping-label", "eventTime": "2020-09-15T15:28:44.677Z", "payload": { "item": {/* lost item object */}, "shippingDate": "2020-09-20", "serviceName": "DHL Express", "files": { "label": { "paper_size": "default", "url": "https://sandbox-download.postmen.com/label/2020-08-06/5d52b9a2-7bc7-4ac6-9201-e59144bb15ec.pdf", "file_type": "pdf" }, "invoice": { "paper_size": "a4", "url": "https://sandbox-download.postmen.com/invoice/2020-08-06/63add3a5-2856-48d0-bab3-6e33000af393.pdf", "file_type": "pdf" } } } } ``` Here is another example of the request body for `pickup` event notification: ```javascript { "eventType": "pickup", "eventTime": "2020-09-15T15:28:44.677Z", "payload": { "item": {/* lost item object */}, "pickupDate": "2020-09-15", "pickupTime": "14:00" } } ``` ### Securing webhooks Each webhook request includes a secret signature in the `fh-signature` header. You should use this HTTP request header to verify that the events were sent by Found Hero, and not by a third-party. You can find your own secret signature under the "Webhooks" tab of your [account settings](https://demo.joinfoundhero.com/dashboard/settings#webhooks). Make sure that you treat this signature as a secret password and never hard-code it into source control systems like Git. ### Retrying webhooks If the webhook endpoint does not return a 200 HTTP response code, Found Hero will attempt to deliver the event again up to 5 times in increasing interval: 2^number\_of\_fail x 15s. For example, if the first attempt fails, Found Hero will retry the 2nd attempt after 15 seconds. If the second attempt fails, the next attempt will be made after 60 seconds and so on. # Locations The Found Hero API allows you to programmatically manage your locations. A location can be a hotel, airport, airline, amusement park, shopping mall, zoo, event, etc. ### Available location types Found Hero currently supports the following location types: | Value | Description | | ----------------- | ------------------------ | | `airline` | Airline | | `airport` | Airport | | `amusement-park` | Amusement Park | | `event` | Event/Festival | | `city-government` | City & Government | | `golf-course` | Golf Course | | `hospital` | Hospital | | `hotel` | Hotel/Resort (Default) | | `transportation` | Public Transportation | | `restaurant` | Restaurant | | `shopping-mall` | Shopping Mall | | `zoo` | Zoo/Animal Park/Aquarium | | `other` | None of the above | ## Create a location `POST` `https://api.joinfoundhero.com/v1/locations` This endpoint allows you to create a new location. #### Request Body | Name | Type | Description | | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | The name of the location | | website | string | The website URL of the location | | logoUrl | string | The logo URL of the location | | description | string | A brief description of the location | | type | string |

The type of location. e.g. hotel, airline, airport, etc. Refer to the above table to see all available location types.
Default value is hotel

| | storageDuration | integer | The number of days the location stores a lost item | | storagePlace | string | The place where lost items are stored | | address1 | string | Address line 1 | | address2 | string | Address line 2 for additional information | | city | string | The name of the city | | state | string | The name of the state | | zipCode | string | Zipcode/postal code for this location | | country | string | A 2-letter country code e.g. `US` | | contact | object | A JSON object containing the contact information | | contact.name | string | Full name of the person in charge of lost and found | | contact.email | string | The primary email address of the person in charge of lost and found | | contact.email2 | string | The secondary email address for receiving shipping labels | | contact.phone | string | The phone number with country code for the contact person | | pickupTime | object | A JSON object containing from and to times during which the lost items can be picked up by the guests | | pickupTime.from | string | From pick-up time (HH:mm format) e.g. `10:00` | | pickupTime.to | string | To pick-up time e.g. `14:00` | {% tabs %} {% tab title="200 Location is created successfully." %} ```javascript { "status": true, "message": "Location is created", "data": { "pickupTime": { "from": "10:00", "to": "14:00" }, "storageDuration": 45, "active": true, "_id": "5f29a6a2af7c9568fe1437f7", "user": "5f1c11c77431601b2fff7459", "name": "Four Seasons Hotel Chicago", "permalink": "four-seasons-hotel-chicago-TIqfTF", "identifier": "8LiwV5xppI3s", "website": "https://www.fourseasons.com/chicago/", "type": "hotel", "contact": { "name": "David Backem", "email": "david.backem@gmail.com", "phone": "+1 (455) 4567-8974" }, "storagePlace": "House Keeping", "address1": "120 E. Delaware Place", "city": "Chicago", "state": "IL", "zipCode": "60611", "country": "US", "createdAt": "2020-08-04T18:19:14.471Z", "updatedAt": "2020-08-04T18:19:14.471Z" } } ``` {% endtab %} {% tab title="400 Missing required fields." %} ```javascript { "status": false, "message": "Location name is required" } ``` {% endtab %} {% endtabs %} ## Retrieve a location `GET` `https://api.joinfoundhero.com/v1/locations/:id` Retrieves the details of a location that has previously been created. Supply the unique location ID that was returned from your previous request, and Found Hero will return the corresponding location information. #### Path Parameters | Name | Type | Description | | ---- | ------ | ---------------------- | | id | string | The unique location ID | {% tabs %} {% tab title="200 The location is retrieved successfully." %} ```javascript { "status": true, "data": { "contact": { "name": "David Backem", "email": "david.backem@gmail.com", "phone": "+1 (455) 4567-8974" }, "pickupTime": { "from": "10:00", "to": "14:00" }, "storageDuration": 45, "active": true, "_id": "5f29a6a2af7c9568fe1437f7", "user": "5f1c11c77431601b2fff7459", "name": "Four Seasons Hotel Chicago", "permalink": "four-seasons-hotel-chicago-TIqfTF", "identifier": "8LiwV5xppI3s", "website": "https://www.fourseasons.com/chicago/", "type": "hotel", "storagePlace": "House Keeping", "address1": "120 E. Delaware Place", "city": "Chicago", "state": "IL", "zipCode": "60611", "country": "US", "createdAt": "2020-08-04T18:19:14.471Z", "updatedAt": "2020-08-04T18:19:14.471Z" } } ``` {% endtab %} {% tab title="404 The location doesn't exist." %} ```javascript { "status": false, "message": "Location not found" } ``` {% endtab %} {% endtabs %} ## Update a location `PUT` `https://api.joinfoundhero.com/v1/locations/:id` Updates the specified location by setting the values of the parameters passed. #### Path Parameters | Name | Type | Description | | ---- | ------ | ---------------------- | | id | string | The unique location ID | #### Request Body | Name | Type | Description | | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | | name | string | The name of the location | | website | string | The website URL of the location | | logoUrl | string | The logo URL of the location | | description | string | A brief description of the location | | type | string | The type of location. e.g. hotel, airline, airport, etc. Refer to the above table to see all available location types. | | storageDuration | integer | The number of days the location stores a lost item | | storagePlace | string | The place where lost items are stored | | address1 | string | Address line 1 | | address2 | string | Address line 2 for additional information | | city | string | The name of the city | | state | string | The name of the state | | zipCode | string | Zipcode/postal code for this location | | country | string | A 2-letter country code .e.g. `US` | | contact | object | A JSON object containing the contact information | | contact.name | string | The name of the person in charge of lost and found | | contact.email | string | The primary email address of the person in charge of lost and found | | contact.email2 | string | The secondary email address for receiving shipping labels | | contact.phone | string | The phone number with country code for the contact person | | pickupTime | object | A JSON object containing from and to times during which the lost items can be picked up by the guests | | pickupTime.from | string | From pick-up time (HH:mm format) e.g. `10:00` | | pickupTime.to | string | To pick-up time .e.g. `14:00` | {% tabs %} {% tab title="200 The location is updated successfully." %} ```javascript { "status": true, "message": "Location is updated", "data": { "contact": { "name": "David Backem", "email": "david.backem@gmail.com", "email2": null, "phone": "+1 (455) 4567-8974" }, "pickupTime": { "from": "08:00", "to": "14:00" }, "storageDuration": 30, "active": true, "_id": "5f29a6a2af7c9568fe1437f7", "user": "5f1c11c77431601b2fff7459", "name": "Four Seasons Hotel Chicago", "permalink": "four-seasons-hotel-chicago-TIqfTF", "identifier": "8LiwV5xppI3s", "website": "https://www.fourseasons.com/chicago/", "type": "hotel", "storagePlace": "House Keeping", "address1": "120 E. Delaware Place", "city": "Chicago", "state": "IL", "zipCode": "60611", "country": "US", "createdAt": "2020-08-04T18:19:14.471Z", "updatedAt": "2020-08-04T18:42:13.114Z", "__v": 0, "address2": null, "description": "#1 hotel in Chicago", "latitude": null, "longitude": null } } ``` {% endtab %} {% tab title="404 The location doesn't exist." %} ```javascript { "status": false, "message": "Location not found" } ``` {% endtab %} {% endtabs %} ## Retrieve all locations `GET` `https://api.joinfoundhero.com/v1/locations?term=four&limit=10&page=1` Retrieve all locations created by the user. By default, this method returns a set of top 10 locations sorted by their names.\ \ You can also supply an optional query parameter called `term` to search locations by their names, descriptions, contact emails, and contact names.\ \ This method also supports pagination. You can use `limit` and `page`\ query parameters to control pagination. #### Query Parameters | Name | Type | Description | | ----- | ------- | --------------------------------------------------------------------------------------------------- | | term | string | Search term to filter-out locations | | limit | integer | The number of results per page. The value must be between `10` and `100`. The default value is `10` | | page | integer | The current page number. The default value is `1` | {% tabs %} {% tab title="200 The operation is completed successfully." %} ```javascript { "status": true, "data": { "locations": [ { "contact": { "name": "David Backem", "email": "david.backem@gmail.com", "email2": null, "phone": "+1 (455) 4567-8974" }, "pickupTime": { "from": "08:00", "to": "14:00" }, "storageDuration": 30, "active": true, "_id": "5f29a6a2af7c9568fe1437f7", "user": "5f1c11c77431601b2fff7459", "name": "Four Seasons Hotel Chicago", "permalink": "four-seasons-hotel-chicago-TIqfTF", "identifier": "8LiwV5xppI3s", "website": "https://www.fourseasons.com/chicago/", "type": "hotel", "storagePlace": "House Keeping", "address1": "120 E. Delaware Place", "city": "Chicago", "state": "IL", "zipCode": "60611", "country": "US", "createdAt": "2020-08-04T18:19:14.471Z", "updatedAt": "2020-08-04T18:42:13.114Z", "__v": 0, "address2": null, "description": "#1 hotel in Chicago", "latitude": null, "longitude": null } ], "page": 1, "limit": 10, "count": 1, "totalPages": 1, "hasMore": false } } ``` {% endtab %} {% endtabs %} ## Delete a location `DELETE` `https://api.joinfoundhero.com/v1/locations/:id` Permanently deletes a location. It cannot be undone. Also immediately delete all lost items associated with this location. #### Path Parameters | Name | Type | Description | | ---- | ------ | ---------------------- | | id | string | The unique location ID | {% tabs %} {% tab title="200 The location is deleted successfully." %} ```javascript { "status": true, "message": "Location deleted successfully" } ``` {% endtab %} {% tab title="404 The location doesn't exist." %} ```javascript { "status": false, "message": "Location not found" } ``` {% endtab %} {% endtabs %} {% hint style="danger" %} Be careful while deleting a location. It will also immediately delete all active and shipped lost items associated with this location. {% endhint %} ## Upload a logo `POST` `https://api.joinfoundhero.com/v1/locations/:id/upload-logo` This endpoint allows you to upload a logo for a location. For this particular request, you must set the request `Content-Type` header to `multipart/form-data`. #### Path Parameters | Name | Type | Description | | ---- | ------ | ---------------------- | | id | string | The unique location ID | #### Request Body | Name | Type | Description | | ---- | ------ | -------------------------------------------------- | | logo | string | The file to upload. File size must not exceed 2MB. | {% tabs %} {% tab title="200 The logo is upload successfully." %} ```javascript { "status": true, "message": "Logo is uploaded successfully", "data": "https://cdn.joinfoundhero.com/l/0d5c6820-4402-d1dc-4392-a6751fd8dcd1.png" } ``` {% endtab %} {% tab title="400 There was no file uploaded or the file size exceeds 2MB." %} ```javascript { "status": false, "message": "File size must not exceed 2MB" } ``` {% endtab %} {% endtabs %} # Lost Items You can use the Found Hero API to create, update, list, and remove lost items. ### Packaging Boxes Found Hero currently supports the following packaging boxes. You should pass the value of the selected box while creating the lost item. | Value | Description | Dimension (cm) | | -------- | ----------- | -------------- | | `letter` | Letter | 33 x 23 x 3 | | `flat` | Flat Box | 33 x 23 x 6 | | `shoe` | Shoe Box | 40 x 20 x 20 | | `moving` | Moving Box | 60 x 40 x 40 | | `long` | Long Box | 100 x 20 x 20 | {% hint style="info" %} We are working on adding support for custom packaging boxes. It will allow users to input the width, height, and depth of the package box. {% endhint %} ## Create an item `POST` `https://api.joinfoundhero.com/v1/locations/:lid/items` This endpoint allows you to create a new lost item. Found Hero will automatically notify the owner when the guest details are provided. #### Path Parameters | Name | Type | Description | | ---- | ------ | ----------------------------- | | lid | string | The unique ID of the location | #### Request Body | Name | Type | Description | | ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | | description | string | A brief description of the lost item. Example: `iPhone X` | | discoveryPlace | string | The place where the lost item was found. | | discoveryDate | string | The discovery date of the lost item in YYYY-MM-DD format | | brand | string | The name of the item's manufacturer | | model | string | The `brand`'s model of the lost item | | color | string | The color of the item | | storagePlace | string | The place where the lost item is stored. You can use this parameter to override the location's default storage place. | | notes | string | Internal notes for your team members | | imageUrl | string | An image URL for the lost item | | shipping | object | A JSON object containing information about the item's shipment | | shipping.weight | number | The weight of the lost item | | shipping.weightUnit | string | Weight unit. Acceptable values are `lb`, `kg`, `oz`, and `g`. The default value is `kg`. | | shipping.boxType | string | Type of the packaging box. Please refer to the above packaging boxes table for all available values. | | shipping.isDocument | boolean | A `true` or `false` value indicating whether the lost item consists of documents only | | owner | object | An optional JSON object containing information about the guest | | owner.firstName | string | The first name of the guest | | owner.lastName | string | The last name of the guest | | owner.email | string | The email address of the guest | | owner.phone | string | The phone number of the guest. It must include the country code. | {% tabs %} {% tab title="200 The lost item is created successfully." %} ```javascript { "status": true, "message": "Lost item created successfully", "data": { "owner": { "firstName": "Amina", "lastName": "Mankid", "email": "amina.mankid@hotmail.com", "phone": "+49 175 78452548" }, "shipping": { "weightUnit": "kg", "isDocument": false, "trackingNumbers": [], "totalPrice": 0, "taxes": 0, "fees": 0, "insurance": 0, "weight": 3.5, "boxType": "moving" }, "ownShipment": false, "labelGenerated": false, "archived": false, "language": "en", "_id": "5f29dbaf81e97ab3a73e2c69", "location": "5f29a6a2af7c9568fe1437f7", "identifier": "etxOKQlM5sAx", "description": "Macbook Pro", "discoveryPlace": "Room #452", "discoveryDate": "2020-07-22T00:00:00.000Z", "lastEmailSent": "2020-08-04T22:05:35.361Z", "notes": "The item seems to be damaged.", "brand": "Apple", "model": "X Series", "color": "Silver", "status": "PENDING", "activity": [ { "_id": "5f29dbaf81e97ab3a73e2c6a", "type": "EMAIL_SENT", "title": "An email was sent at amina.mankid@hotmail.com to inform the owner about their lost item.", "createdAt": "2020-08-04T22:05:35.808Z", "updatedAt": "2020-08-04T22:05:35.808Z" } ], "storagePlace": "Reception", "createdAt": "2020-08-04T22:05:35.381Z", "updatedAt": "2020-08-04T22:05:35.810Z" } } ``` {% endtab %} {% tab title="400 The request can not be completed due to data validation errors." %} ```javascript { "status": false, "message": "Item description is required" } ``` {% endtab %} {% tab title="404 The location doesn't exist." %} ```javascript { "status": false, "message": "Location not found" } ``` {% endtab %} {% endtabs %} ## Retrieve an item `GET` `https://api.joinfoundhero.com/v1/locations/:lid/items/:id` This endpoint allows you to retrieve the details of a lost item that has previously been created. Just pass the unique location and item IDs, and Found Hero will return the corresponding lost item information. #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------------------------ | | lid | string | The unique ID of the location | | id | string | The unique ID of the lost item | {% tabs %} {% tab title="200 The lost item is retrieved successfully." %} ```javascript { "status": true, "data": { "owner": { "firstName": "Amina", "lastName": "Mankid", "email": "amina.mankid@hotmail.com", "phone": "+49 175 78452548" }, "shipping": { "weightUnit": "kg", "isDocument": false, "trackingNumbers": [], "totalPrice": 0, "taxes": 0, "fees": 0, "insurance": 0, "weight": 3.5, "boxType": "moving" }, "ownShipment": false, "labelGenerated": false, "archived": false, "language": "en", "_id": "5f29dbaf81e97ab3a73e2c69", "location": { "contact": { "name": "David Backem", "email": "david.backem@gmail.com", "email2": null, "phone": "+1 (455) 4567-8974" }, "pickupTime": { "from": "08:00", "to": "14:00" }, "storageDuration": 30, "active": true, "_id": "5f29a6a2af7c9568fe1437f7", "user": "5f1c11c77431601b2fff7459", "name": "Four Seasons Hotel Chicago", "permalink": "four-seasons-hotel-chicago-TIqfTF", "identifier": "8LiwV5xppI3s", "website": "https://www.fourseasons.com/chicago/", "type": "hotel", "storagePlace": "House Keeping", "address1": "120 E. Delaware Place", "city": "Chicago", "state": "IL", "zipCode": "60611", "country": "US", "createdAt": "2020-08-04T18:19:14.471Z", "updatedAt": "2020-08-04T20:47:28.688Z", "__v": 0, "address2": null, "description": "#1 hotel in Chicago", "latitude": null, "longitude": null, "logoUrl": "https://cdn.joinfoundhero.com/l/38acd909-e623-48e2-8c89-b01f5759afbd.png" }, "identifier": "etxOKQlM5sAx", "description": "Macbook Pro", "discoveryPlace": "Room #452", "discoveryDate": "2020-07-22T00:00:00.000Z", "lastEmailSent": "2020-08-04T22:05:35.361Z", "notes": "The item seems to be damaged.", "brand": "Apple", "model": "X Series", "color": "Silver", "status": "PENDING", "activity": [ { "_id": "5f29dbaf81e97ab3a73e2c6a", "type": "EMAIL_SENT", "title": "An email was sent at amina.mankid@hotmail.com to inform the owner about their lost item.", "createdAt": "2020-08-04T22:05:35.808Z", "updatedAt": "2020-08-04T22:05:35.808Z" } ], "storagePlace": "Reception", "createdAt": "2020-08-04T22:05:35.381Z", "updatedAt": "2020-08-04T22:05:35.810Z" } } ``` {% endtab %} {% tab title="404 The lost item or the location doesn't exist." %} ```javascript { "status": false, "message": "Item not found" } ``` {% endtab %} {% endtabs %} ## Update an item `PUT` `https://api.joinfoundhero.com/v1/locations/:lid/items/:id` This endpoint allows you to update the lost item information. #### Path Parameters | Name | Type | Description | | ---- | ------ | ----------------------------- | | lid | string | The unique ID of the location | | id | string | The unique ID of the item | #### Request Body | Name | Type | Description | | ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | | description | string | A brief description of the lost item. Example: `iPhone X` | | discoveryPlace | string | The place where the lost item was found | | discoveryDate | string | The discovery date of the lost item in YYYY-MM-DD format | | brand | string | The name of the item's manufacturer | | model | string | The `brand`'s model of the lost item | | color | string | The color of the item | | storagePlace | string | The place where the lost item is stored. You can use this parameter to override the location's default storage place. | | notes | string | Internal notes for your team | | imageUrl | string | An optional image URL for the lost item | | shipping | object | A JSON object containing information about the item's shipment | | shipping.weight | number | The weight of the lost item | | shipping.weightUnit | string | Weight unit. Acceptable values are `lb`, `kg`, `oz`, and `g`. The default value is `kg`. | | shipping.boxType | string | Type of the packaging box. Please refer to the above packaging boxes table for all available values. | | shipping.isDocument | boolean | A `true` or `false` value indicating whether the lost item consists of documents only | | owner | object | An optional JSON object containing information about the guest | | owner.firstName | string | The first name of the guest | | owner.lastName | string | The last name of the guest | | owner.email | string | The email address of the guest | | owner.phone | string | The phone number of the guest. It must include the country code. | {% tabs %} {% tab title="200 The lost item is updated successfully." %} ```javascript { "status": true, "message": "Lost item is updated", "data": { "owner": { "firstName": "Amina", "lastName": "Mankid", "email": "amina.mankid@hotmail.com", "phone": "+49 175 78452548" }, "shipping": { "weightUnit": "kg", "isDocument": false, "trackingNumbers": [], "totalPrice": 0, "taxes": 0, "fees": 0, "insurance": 0, "weight": 3.5, "boxType": "flat" }, "ownShipment": false, "labelGenerated": false, "archived": false, "language": "en", "_id": "5f29dbaf81e97ab3a73e2c69", "location": { "contact": { "name": "David Backem", "email": "david.backem@gmail.com", "email2": null, "phone": "+1 (455) 4567-8974" }, "pickupTime": { "from": "08:00", "to": "14:00" }, "storageDuration": 30, "active": true, "_id": "5f29a6a2af7c9568fe1437f7", "user": "5f1c11c77431601b2fff7459", "name": "Four Seasons Hotel Chicago", "permalink": "four-seasons-hotel-chicago-TIqfTF", "identifier": "8LiwV5xppI3s", "website": "https://www.fourseasons.com/chicago/", "type": "hotel", "storagePlace": "House Keeping", "address1": "120 E. Delaware Place", "city": "Chicago", "state": "IL", "zipCode": "60611", "country": "US", "createdAt": "2020-08-04T18:19:14.471Z", "updatedAt": "2020-08-04T20:47:28.688Z", "__v": 0, "address2": null, "description": "#1 hotel in Chicago", "latitude": null, "longitude": null, "logoUrl": "https://cdn.joinfoundhero.com/l/38acd909-e623-48e2-8c89-b01f5759afbd.png" }, "identifier": "etxOKQlM5sAx", "description": "Macbook Pro 2020", "discoveryPlace": "Room #452", "discoveryDate": "2020-08-02T00:00:00.000Z", "lastEmailSent": "2020-08-04T22:05:35.361Z", "notes": "The item seems to be damaged.", "brand": "Apple", "model": "X Series", "color": "Silver", "status": "PENDING", "activity": [ { "_id": "5f29dbaf81e97ab3a73e2c6a", "type": "EMAIL_SENT", "title": "An email was sent at amina.mankid@hotmail.com to inform the owner about their lost item.", "createdAt": "2020-08-04T22:05:35.808Z", "updatedAt": "2020-08-04T22:05:35.808Z" } ], "storagePlace": "Reception", "createdAt": "2020-08-04T22:05:35.381Z", "updatedAt": "2020-08-04T23:23:29.390Z", "__v": 1 } } ``` {% endtab %} {% tab title="400 The request can not be completed due to data validation errors." %} ```javascript { "status": false, "message": "Item description is required" } ``` {% endtab %} {% tab title="404 The lost item or the location doesn't exist." %} ```javascript { "status": false, "message": "Item not found" } ``` {% endtab %} {% endtabs %} ## Retrieve all items by location `GET` `https://api.joinfoundhero.com/v1/locations/:lid/items` Retrieve all lost items associated with a specific location. By default, this method returns a set of 10 most recent lost items.\ \ You can also supply an optional query parameter called `term` to search lost items by their descriptions and guest information.\ \ This method also supports pagination. You can use `limit` and `page` query parameters to control pagination.
#### Path Parameters | Name | Type | Description | | ---- | ------ | ----------------------------- | | lid | string | The unique ID of the location | #### Query Parameters | Name | Type | Description | | ----- | ------- | ---------------------------------------------------------------------------------------------------- | | term | string | Search term to filter-out lost items | | limit | integer | The number of results per page. The value must be between `10` and `100`. The default value is `10`. | | page | integer | The current page number. The default value is `1`. | {% tabs %} {% tab title="200 The operation is completed successfully." %} ```javascript { "status": true, "data": { "items": [ { "owner": { "firstName": "Amina", "lastName": "Mankid", "email": "amina.mankid@hotmail.com", "phone": "+49 175 78452548" }, "shipping": { "weightUnit": "kg", "isDocument": false, "trackingNumbers": [], "totalPrice": 0, "taxes": 0, "fees": 0, "insurance": 0, "weight": 3.5, "boxType": "flat" }, "ownShipment": false, "labelGenerated": false, "archived": false, "language": "en", "_id": "5f29dbaf81e97ab3a73e2c69", "location": "5f29a6a2af7c9568fe1437f7", "identifier": "etxOKQlM5sAx", "description": "Macbook Pro 2020", "discoveryPlace": "Room #452", "discoveryDate": "2020-08-02T00:00:00.000Z", "lastEmailSent": "2020-08-04T22:05:35.361Z", "notes": "The item seems to be damaged.", "brand": "Apple", "model": "X Series", "color": "Silver", "status": "PENDING", "activity": [ { "_id": "5f29dbaf81e97ab3a73e2c6a", "type": "EMAIL_SENT", "title": "An email was sent at amina.mankid@hotmail.com to inform the owner about their lost item.", "createdAt": "2020-08-04T22:05:35.808Z", "updatedAt": "2020-08-04T22:05:35.808Z" } ], "storagePlace": "Reception", "createdAt": "2020-08-04T22:05:35.381Z", "updatedAt": "2020-08-04T23:23:29.390Z" } ], "page": 1, "limit": 10, "count": 1, "totalPages": 1, "hasMore": false } } ``` {% endtab %} {% tab title="404 The location doesn't exist." %} ```javascript { "status": false, "message": "Location not found" } ``` {% endtab %} {% endtabs %} ## Delete an item `DELETE` `https://api.joinfoundhero.com/v1/locations/:lid/items/:id` This endpoint allows you to permanently delete a lost item. It cannot be undone. #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------------------------ | | lid | string | The unique ID of the location | | id | string | The unique ID of the lost item | {% tabs %} {% tab title="200 The item is deleted successfully." %} ```javascript { "status": true, "message": "Item deleted successfully" } ``` {% endtab %} {% tab title="404 The lost item or the location doesn't exist." %} ```javascript { "status": false, "message": "Item not found" } ``` {% endtab %} {% endtabs %} ## Upload an image `POST` `https://api.joinfoundhero.com/v1/locations/:lid/items/:id/upload-image` This endpoint allows you to upload an image for the lost item. For this particular request, you must set the request `Content-Type` header to `multipart/form-data`. #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------------------------ | | lid | string | The unique lD of the location | | id | string | The unique ID of the lost item | #### Request Body | Name | Type | Description | | ----- | ------ | ------------------------------------------------------- | | image | string | The file to upload. The file size must not exceed 10MB. | {% tabs %} {% tab title="200 The image is uploaded successfully." %} ```javascript { "status": true, "message": "Image is uploaded successfully", "data": "https://cdn.joinfoundhero.com/i/b4ea1133-af0c-4559-300a-120fe08f421b.png" } ``` {% endtab %} {% tab title="400 There was no file uploaded or the file size exceeds 10MB." %} ```javascript { "status": false, "message": "File size must not exceed 10MB" } ``` {% endtab %} {% endtabs %} ## Update Item Status `PUT` `https://api.joinfoundhero.com/v1/locations/:lid/items/:id/update-status` This endpoint allows you to update item status. The different item status are : \ case 'PENDING' : return 'Waiting for response'\ case 'INFO COMPLETED : 'Recipient details filled'\ case 'FEE PAID' : return 'Shipping fee paid'\ case 'SHIPPED' : return 'In route'\ case 'DELIVERED' : return 'Safely Delivered'\ case 'DISCARD' : return 'Left behind'\ case 'PICKUP' : return 'Pick up by guest'\ case 'DONATE' : return 'Donate to chartiy' #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------------------------ | | id | string | The unique ID of the lost item | | lid | string | The unique ID of the location | #### Request Body | Name | Type | Description | | ------ | ------ | --------------------------------------------- | | status | string | The new status you want to affect to the item | {% tabs %} {% tab title="200 " %} ``` { "status": true, "message": "Lost item status is updated", "data": { "owner": { "firstName": "test", "lastName": "test", "email": "test@test.com", "phone": "3333333333" }, "shipping": { "weightUnit": "lb", "isDocument": false, "trackingNumbers": [], "totalPrice": 0, "taxes": 0, "fees": 0, "insurance": 0, "weight": 1, "boxType": "flat" }, "ownShipment": false, "labelGenerated": false, "archived": false, "language": "en", "_id": "60ed6e0ecb90adfe2658a431", "location": "5ff8a9d374334bcad6a44140", "request": "60e99edfcb90adfe2658a42d", "identifier": "sgH7zHmBwTPP", "description": "test", "discoveryPlace": "test", "discoveryDate": "2021-07-06T00:00:00.000Z", "status": "PENDING", "activity": [ { "_id": "60ed6e0ecb90adfe2658a432", "type": "EMAIL_SENT", "title": "An email was sent at test@test.com to inform the owner about their lost item.", "createdAt": "2021-07-13T10:42:22.293Z", "updatedAt": "2021-07-13T10:42:22.293Z" }, { "_id": "60f81fe6fffb56842a569a7c", "type": "STATUS_CHANGED", "title": "Item status was changed to PENDING.", "createdAt": "2021-07-21T13:23:50.663Z", "updatedAt": "2021-07-21T13:23:50.663Z" } ], "createdAt": "2021-07-13T10:42:22.273Z", "updatedAt": "2021-07-21T13:23:50.664Z", "__v": 2, "lastEmailSent": "2021-07-13T10:42:22.288Z" } } ``` {% endtab %} {% endtabs %} # 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 `GET` `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 `GET` `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. #### 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 `PUT` `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 `POST` `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 %}