Lost Items

You can use the Faundit API v2 to create, edit and get lost Items.

The Faundit Lost and Found API facilitates the management of guest belongings forgotten in establishments. Items reported as lost or misplaced are registered within the system, fostering their eventual return to their rightful owners. This API empowers partners to effectively handle lost and found scenarios by providing programmatic access to key functionalities.

Faundit Packaging

These are the maximum size for the dimensions of Faundit packaging:

Value	Dimension (cm)	Dimensions (in)
length	45	15
width	35	12
height	10	4

You can use other packaging with equal dimensions. Things that don't fit: pillow, suitcase, bags, large jackets, etc.

Return a list of all Items

GET https://{environment}.faundit.com/api/v2/items

Query Parameters

Name	Type	Description
limit	number	Specify the number of results per page. The default value is set to 10.
page	number	The default page number is 1.

200: OK Items returned successfully.

{
    "items": [
        {
            "ID": 438395,
            "item": "Sunglasses",
            "location": "213",
            "departuredDate": "2023-12-07 10:35:06.999",
            "itemNumber": 1181,
            "owner": {
                "firstName": null,
                "lastName": null,
                "contactEmail": "[e-mail]",
                "phoneNumber": null,
                "address": {
                    "address": null,
                    "address2": null,
                    "city": null,
                    "countryID": null,
                    "state": null,
                    "companyName": null
                }
            },
            "shipping": {
                "weight": {
                    "ID": 1,
                    "title": "Less than 2 kg."
                },
                "dimensions": {
                    "fitsInFaunditPackaging": true,
                    "width": null,
                    "lenght": null,
                    "height": null
                },
                "shippingLabel": null,
                "trackingUrl": null,
                "proformaUrl": null,
                "receiptUrl": null
            },
            "internalNotes": null,
            "itemStorage": "First drawer storage room.",
            "imageUrl": null,
            "ownShipment": false,
            "status": "waiting-response",
            "locationID": "23a10jw221197jc:abc12345",
            "ownerPickupComment": null,
            "createdAt": "2023-12-07 10:36:17.263",
            "updatedAt": null,
            "itemPaidAt": null,
            "ownerPickupDate": null,
            "pickupBookedAt": null,
            "customStorageDays": null,
            "colors": [
                "burgundy",
                "blue"
            ],
            "categories": [
                {
                    "ID": 12506,
                    "categoryID": "jewelry",
                    "manuallyClassified": true
                }
            ],
        }
    ],
    "hasMore": true,
    "limit": 1,
    "page": 1
}

400: Bad Request Query parameters not valid.

Return a single Item

GET https://{environment}.faundit.com/api/v2/items/:itemID

This endpoint allows you to return the details of a Lost Item that has previously been created. You can pass the item ID, and Faundit will return the corresponding lost item information.

Path Parameters

Name	Type	Description
itemID*	number	Unique lost item ID.

200: OK Item returned successfully.

{
    "ID": 438393,
    "item": "iPhone charger",
    "location": "Room 313",
    "departuredDate": "2023-12-07 08:44:03.594",
    "itemNumber": 1179,
    "owner": {
        "firstName": "Jose",
        "lastName": "Jonason",
        "contactEmail": "[e-mail]",
        "phoneNumber": "45 12345678",
        "address": {
            "address": "Carrer de la Llotja 2",
            "address2": "13A",
            "city": "València",
            "countryID": "ES",
            "state": null,
            "companyName": null
        }
    },
    "shipping": {
        "weight": {
            "ID": 1,
            "title": "Less than 2 kg."
        },
        "dimensions": {
            "fitsInFaunditPackaging": true,
            "width": null,
            "lenght": null,
            "height": null
        },
        "shippingLabel": null,
        "trackingUrl": null,
        "proformaUrl": null,
        "receiptUrl": null
    },
    "internalNotes": "Black color with a sticker on it",
    "itemStorage": "Storage room 1",
    "imageUrl": "https://company.s3.eu-central-1.amazonaws.com/image.jpg",
    "ownShipment": false,
    "status": "waiting-response",
    "locationID": "23a10jw221197jc:abc12345",
    "ownerPickupComment": null,
    "createdAt": "2023-12-07 09:46:06.925",
    "updatedAt": "2023-12-07 09:53:41.914",
    "itemPaidAt": null,
    "ownerPickupDate": null,
    "pickupBookedAt": null,
    "customStorageDays": 50,
    "language": {
        "ID": 230,
        "language": "English",
        "default": true,
        "createdAt": "2021-10-06 11:11:33.564"
    },
    "colors": [
        "burgundy"
    ],
    "categories": [
        {
            "ID": 12507,
            "categoryID": "electronic_main",
            "manuallyClassified": true
        }
    ],
}

400: Bad Request Item ID not valid.

404: Not Found Item not found.

Register an Item

POST https://{environment}.faundit.com/api/v2/items

This endpoint allows you to register an Item.

Request Body

Name	Type	Description
item*	string	Contains a description of an Item. Example: "iPhone charger"
location*	string	The physical last known location of the Item. This will typically be the room number of a hotel, the license plate/contract number of a rental car, etc. Example: "Room 311" Example: "311" Example: "Reception"
departuredDate*	string	Check-out date of the owner. Example: "2021-11-29 00:00:00" Example: "2021-11-29T12:57:25.021Z" Example: "2021-11-29T12:57:25" Only above formats will be accepted. OBS: Time will be ignored.
owner	object	A JSON object containing data about the Item's owner.
owner.firstName	string	First name of the owner. Example: "Jose"
owner.lastName	string	Last name of the owner. Example: "Jonason"
owner.address.address	string	Address of the owner. Example: "36 Graham St."
owner.address.address2	string	Second address line of the owner. Example: "2nd floor"
owner.address.city	string	City of the owner. Example: "London"
owner.address.countryID	string	Alpha-2 country code of the owner. Example: "GB" *You’ll find the values in the section “Country Reference”. Use the abbreviation (value) of the key, e.g. “GB” for the United Kingdom.
owner.address.state	string	State of the property (Australia, Canada & USA only). Example: "NY" Use abbreviations accordingly to our State Reference page.
owner.address.zipCode	string	Zip code of the owner. Example: "N1 8GJ"
owner.address.companyName	string	Company of the address. Only for business addresses. Example: "Faundit ApS"
shipping*	object	A JSON object containing data about the Item's shipment.
shipping.weight	object	A JSON object containing data about the Item's weight.
shipping.weight.ID	number	WeightID referencing the weight of the found Item (roughly). 1: Less than 2kg. 2: Less than 5kg. 3: Between 5 and 10kg. 4: Between 10 and 15kg. 5: Between 15 and 20kg. 6: More than 20kg. Example: 1
shipping.dimensions	object	A JSON object containing data about the Item's dimensions.
shipping.dimensions.fitsInFaunditPackaging	boolean	A true or false value indicating whether the Item fits in the Faundit packaging. *You can find the measures in the section Item dimensions & weight.
shipping.dimensions.width	number	The width of your packaging. Required if the value fitsInFaunditPackaging is false.
shipping.dimensions.length	number	The length of your packaging. Required if the value fitsInFaunditPackaging is false.
shipping.dimensions.height	number	The height of your packaging. Required if the value fitsInFaunditPackaging is false.
itemStorage	string	Where the lost Item is physically stored at your location. Example: "Storage room 1" Value not visible to the lost Item. owner.
internalNotes	string	Internal notes for your organization regarding the found Item. Example: "Black color with a sticker on it" Value not visible to the lost Item owner.
imageUrl	string	Image of the found Item. It has to be a valid URL. Example: "https://company.s3.eu-central-1.amazonaws.com/image.jpg" Accepted image formats: JPG, JPEG, PNG, GIF
customStorageDays	number	Override default storage days to store it for a longer or shorter period.
owner.contactEmail	string	Email address of the owner. Example: "[e-mail]"
owner.phoneNumber	string	Phone number of the owner. Example: "[phone]" Example: "[phone]" Example: "[phone]" *Remember the country-specific code, e.g. "+45" for Denmark.
owner.address	object	A JSON object containing data about the owner's address.
owner.reservationNumber	string	The reservation number associated with the location where the lost item was found. Leave null if not applicable.
owner.activityNumber	string	The activity number associated with the location where the lost item was found. Leave null if not applicable.
owner.agreementNumber	string	The agreement number associated with the location where the lost item was found. Leave null if not applicable.
locationID*	string	The ID of the Location to which the Lost Item will be registered.
brand	string	Brand of the found item.
colors	array of strings	Color IDs referencing the colors of the found Item.
categories	array of strings	Category IDs referencing the categories of the found Item.
languageID	number	Language ID referencing the Language you want to use when communicating with the owner. languageID overrules languageCode. If it's not provided, it will fallback to the default language of the Location. See Locations for querying available Languages for your Location.
languageCode	string	ISO 639 Language Code references the language you want to use when communicating with the owner. If languageID is provided, it will overule languageCode. If it is not provided, it will fall back to the Location’s default language. Currently supported Language Codes: en, da, de, se, fr, nl, cs, no, ar, es, fo

200: OK Item successfully updated.

{
    "ID": 438271,
    "item": "iPhone charger",
    "location": "Room 131",
    "departuredDate": "2021-11-29 00:00:00.000",
    "itemNumber": 1070,
    "owner": {
        "firstName": "Jose",
        "lastName": "Jonason",
        "contactEmail": "[e-mail]",
        "phoneNumber": "[phone]",
        "address": {
            "address": "36 Graham St",
            "address2": "2nd floor",
            "city": "London",
            "zipCode": "N1 8GJ"
            "countryID": "GB",
            "state": null,
            "companyName": "Faundit ApS"
        },
        "reservationNumber": "ABCD13",
        "activityNumber": "1234",
        "agreementNumber": "4321",
    },
    "shipping": {
        "weight": {
            "ID": 1,
            "title": "Less than 2 kg."
        },
        "dimensions": {
            "fitsInFaunditPackaging": true,
            "width": null,
            "lenght": null,
            "height": null
        },
        "shippingLabel": null,
        "trackingUrl": null,
        "proformaUrl": null,
        "receiptUrl": null
    },
    "internalNotes": "Black color with a sticker on it",
    "itemStorage": "Storage room 1",
    "imageUrl": null,
    "ownShipment": false,
    "status": "waiting-response",
    "locationID": "23a10jw221197jc:abc12345",
    "ownerPickupComment": null,
    "brand": "Apple",
    "colors": [
        "burgundy", "blue"
    ],
    "createdAt": "2023-06-27 10:06:02.938",
    "updatedAt": "2023-12-07 13:57:48.099",
    "itemPaidAt": null,
    "ownerPickupDate": null,
    "pickupBookedAt": null,
    "customStorageDays": null,
    "colors": [
        "burgundy"
    ],
    "categories": [
        {
            "ID": 12507,
            "categoryID": "electronic_main",
            "manuallyClassified": true
        }
    ],
}

400: Bad Request Invalid fields.

Update an Item

PUT https://{environment}.faundit.com/api/v2/items/:itemID

This endpoint allows you to update the details of an Item.

Path Parameters

Name	Type	Description
itemID*	number	Item unique identifier.

Request Body

Name	Type	Description
item	string	Contains description of an Item. Example: "iPhone charger"
location	string	Place where the Item was found. Example: "Room 311" Example: "311" Example: "Reception"
departuredDate	string	Check-out date of the owner. Example: "2021-11-29 00:00:00" Example: "2021-11-29T12:57:25.021Z" Example: "2021-11-29T12:57:25" Only above formats will be accepted. OBS: Time will be ignored.
owner	object	A JSON object containing data about the Item's owner.
owner.firstName	string	First name of the owner. Example: "Jose"
owner.lastName	string	Last name of the owner. Example: "Jonason"
owner.address.address	string	Address of the owner. Example: "36 Graham St."
owner.address.address2	string	Second address line of the owner. Example: "2nd floor"
owner.address.city	string	City of the owner. Example: "London"
owner.address.countryID	string	Alpha-2 country code of the owner. Example: "GB" *You’ll find the values in the section “Country Reference”. Use the abbreviation (value) of the key, e.g. “GB” for the United Kingdom.
owner.address.state	string	State of the property (Australia, Canada & USA only). Example: "NY" Use abbreviations accordingly to our State Reference page.
owner.address.zipCode	string	Zip code of the owner. Example: "N1 8GJ"
owner.address.companyName	string	Company of the address. Only for business addresses. Example: "Faundit ApS"
shipping	object	A JSON object containing data about the Item's shipment.
shipping.weight	object	A JSON object containing data about the Item's weight.
shipping.weight.ID	number	WeightID referencing the weight of the found Item (roughly). 1: Less than 2kg. 2: Less than 5kg. 3: Between 5 and 10kg. 4: Between 10 and 15kg. 5: Between 15 and 20kg. 6: More than 20kg. Example: 1
shipping.dimensions*	object	A JSON object containing data about the Item's dimensions.
shipping.dimensions.fitsInFaunditPackaging*	boolean	A true or false value indicating whether the Item fits in the Faundit packaging. *You can find the measures in the section Item dimensions & weight.
shipping.dimensions.width	number	The width of your packaging. Required if the value fitsInFaunditPackaging is false.
shipping.dimensions.length	number	The length of your packaging. Required if the value fitsInFaunditPackaging is false.
shipping.dimensions.height	number	The height of your packaging. Required if the value fitsInFaunditPackaging is false.
itemStorage	string	Where the lost Item is physically stored at your location. Example: "Storage room 1" Value not visible to the lost Item owner.
internalNotes	string	Internal notes for your organization regarding the found item. Example: "Black color with a sticker on it" Value not visible to the lost Item owner.
imageUrl	string	Image of the found Item. Has to be a valid URL. Example: "https://company.s3.eu-central-1.amazonaws.com/image.jpg" Accepted image formats: JPG, JPEG, PNG, GIF
customStorageDays	number	Override default storage days to store it for a longer or shorter period.
owner.contactEmail	string	Email address of the owner. Example: "[e-mail]"
owner.phoneNumber	string	Phone number of the owner. Example: "[phone]" Example: "[phone]" Example: "[phone]" *Remember the country-specific code, e.g. "+45" for Denmark.
owner.address	object	A JSON object containing data about the owner's address.
owner.reservationNumber	string	The reservation number associated with the location where the lost item was found. Leave null if not applicable.
owner.activityNumber	string	The activity number associated with the location where the lost item was found. Leave null if not applicable.
owner.agreementNumber	string	The agreement number associated with the location where the lost item was found. Leave null if not applicable.
brand	string	Brand of the found item.
colors	array of strings	Color IDs referencing the colors of the found Item.
categories	array of strings	Category IDs referencing the categories of the found Item.

200: OK Item successfully updated.

{
    "ID": 438271,
    "item": "iPhone charger",
    "location": "Room 131",
    "departuredDate": "2021-11-29 00:00:00.000",
    "itemNumber": 1070,
    "owner": {
        "firstName": "Jose",
        "lastName": "Jonason",
        "contactEmail": "[e-mail]",
        "phoneNumber": "[phone]",
        "address": {
            "address": "36 Graham St",
            "address2": "2nd floor",
            "city": "London",
            "zipCode": "N1 8GJ"
            "countryID": "GB",
            "state": null,
            "companyName": "Faundit ApS"
        },
        "reservationNumber": "ABCD13",
        "activityNumber": "1234",
        "agreementNumber": "4321",
    },
    "shipping": {
        "weight": {
            "ID": 1,
            "title": "Less than 2 kg."
        },
        "dimensions": {
            "fitsInFaunditPackaging": true,
            "width": null,
            "lenght": null,
            "height": null
        },
        "shippingLabel": null,
        "trackingUrl": null,
        "proformaUrl": null,
        "receiptUrl": null
    },
    "internalNotes": "Black color with a sticker on it",
    "itemStorage": "Storage room 1",
    "imageUrl": null,
    "ownShipment": false,
    "status": "waiting-response",
    "locationID": "23a10jw221197jc:abc12345",
    "ownerPickupComment": null,
    "brand": "Apple",
    "colors": [
        "burgundy", "blue"
    ],
    "createdAt": "2023-06-27 10:06:02.938",
    "updatedAt": "2023-12-07 13:57:48.099",
    "itemPaidAt": null,
    "ownerPickupDate": null,
    "pickupBookedAt": null,
    "customStorageDays": null,
    "colors": [
        "burgundy"
    ],
    "categories": [
        {
            "ID": 12507,
            "categoryID": "electronic_main",
            "manuallyClassified": true
        }
    ],
}

404: Not Found Item not found.

403: Forbidden Item couldn't be updated.

Update the status of an Item

PUT https://{environment}.faundit.com/api/v2/items/:itemID/status

This endpoint allows you to update the status of an Item to left-behind or finished.

Path Parameters

Name	Type	Description
itemID*	number	Item unique identifier.

Request Body

Name	Type	Description
status*	string	The new status you want to update the Item to. Example: "left-behind" Use status accordingly to our Item status page.

200: OK Item status updated successfully.

{
    "ID": 438392,
    "item": "Smartband",
    "location": "Lobby",
    "departuredDate": "2021-11-28 23:00:00.000",
    "itemNumber": 1178,
    "owner": {
        "firstName": "Jose",
        "lastName": "Jonason",
        "contactEmail": "[e-mail]",
        "phoneNumber": "[phone]",
        "address": {
            "address": "Norre Alle",
            "address2": "50",
            "city": "Aarhus",
            "countryID": "DK",
            "state": null,
            "companyName": "Faundit ApS"
        }
    },
    "shipping": {
        "weight": {
            "ID": 1,
            "title": "Less than 2 kg."
        },
        "dimensions": {
            "fitsInFaunditPackaging": true,
            "width": null,
            "lenght": null,
            "height": null
        },
        "shippingLabel": null,
        "trackingUrl": null,
        "proformaUrl": null,
        "receiptUrl": null
    },
    "internalNotes": "It has a little scratch on the screen.",
    "itemStorage": "Storage room 1.",
    "imageUrl": null,
    "ownShipment": false,
    "status": "finished",
    "locationID": "23a10jw221197jc:abc12345",
    "ownerPickupComment": null,
    "createdAt": "2023-12-01 13:24:26.987",
    "updatedAt": "2023-12-07 12:44:08.071",
    "itemPaidAt": null,
    "ownerPickupDate": null,
    "pickupBookedAt": null,
    "customStorageDays": null,
    "language": {
        "ID": 230,
        "language": "English",
        "default": true,
        "createdAt": "2021-10-06 11:11:33.564"
    }
}

404: Not Found Item not found.

403: Forbidden Item cannot be updated to the selected status.

400: Bad Request Invalid or missing values.

Upload an Item image

POST https://{environment}.faundit.com/api/v2/items/:itemID/upload-image

This endpoint enables you to submit an image for the lost Item. Ensure that, for this specific request, you set the Content-Type header to multipart/form-data.

Path Parameters

Name	Type	Description
itemID*	number	Item unique identifier.

Headers

Name	Type	Description
Content-Type*	multipart/form-data

Request Body

Name	Type	Description
image*		The file to upload.

200: OK Image uploaded. It returns the image URL that you can use while registering or updating an item.

"https://company.s3.eu-central-1.amazonaws.com/image.jpg"

400: Bad Request Image not uploaded.