Customer Requests

You can use the Faundit API v2 to create and get customer Requests.

Customer Requests are made by guests/owners of lost Items. The inquiries are collected in a structured manner and used to match with already registered Items to return them to the respective owners.

Return a list of all customer Requests

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

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 Requests returned successfully.

{
    "requests": [
        {
            "ID": 33719,
            "departuredDate": "2023-12-01 00:00:00.000",
            "location": "Room 311",
            "request": "iPhone charger",
            "requestNumber": 33,
            "owner": {
                "name": "Jose Jonason",
                "email": "[e-mail]",
                "phoneNumber": "[phone]"
            },
            "matchedItemID": null,
            "locationID": "23a10jw221197jc:abc12345",
            "imageUrl": null,
            "resolved": false,
            "status": "waiting-guest-response",
            "askForDetails": {
                "question": "What color is it?",
                "answer": "It's a white charger."
            },
            "createdAt": "2023-11-30 10:44:39.188",
            "updatedAt": "2023-12-06 10:54:11.217",
            "colors": [
                "burgundy"
            ],
            "categories": [
                {
                    "ID": 12508,
                    "categoryID": "electronic_secondary",
                    "manuallyClassified": true
                }
            ],
        }
    ],
    "hasMore": true,
    "limit": 1,
    "page": 1
}

400: Bad Request Query parameters not valid.

Return a single customer Request

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

This endpoint allows you to return the details of a customer Request that has previously been created. You can pass the Request ID, and Faundit will return the corresponding Request details.

Path Parameters

Name	Type	Description
requestID*	number	Customer Request unique identifier. Example: 1317

200: OK Request returned successfully.

{
    "ID": 33719,
    "departuredDate": "2023-12-01 00:00:00.000",
    "location": "Room 311",
    "request": "iPhone charger",
    "requestNumber": 33,
    "owner": {
        "name": "Jose Jonason",
        "email": "[e-mail]",
        "phoneNumber": "[phone]"
    },
        "matchedItemID": null,
        "locationID": "23a10jw221197jc:abc12345",
        "imageUrl": null,
        "resolved": false,
        "status": "waiting-guest-response",
        "askForDetails": {
            "question": "What color is it?",
            "answer": "It's a white charger."
        },
        "colors": [
            "burgundy"
        ],
        "categories": [
            {
                "ID": 12507,
                "categoryID": "electronic_secondary",
                "manuallyClassified": true
            }
        ],
        "createdAt": "2023-11-30 10:44:39.188",
        "updatedAt": "2023-12-06 10:54:11.217"
}

400: Bad Request Request ID not valid.

404: Not Found Request not found.

Register a customer Request

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

This endpoint allows you to register a customer Request.

Request Body

Name	Type	Description
request*	string	Customer Request description.
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 owner.
owner.name	string	Name of the owner. Example: "Jose Jonason"
owner.email	string	Email address of the owner. The body must contain either an email address, a phone number or both. Example: "[e-mail]"
owner.phoneNumber	string	Phone number of the owner. The body must contain either an email address, a phone number or both. Example: "[phone]" Example: "[phone]" Example: "[phone]" *Remember the country-specific code, e.g. "+45" for Denmark.
owner.reservationNumber	string	The reservation number associated with the location where the lost item was found. Leave null if not applicable.
imageUrl	string	Image of the customer Request. 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
locationID*	string	The ID of the Location to which the Customer Request will be registered.
brand	string	Brand of the item.
colors	array of strings	Color IDs referencing the colors of the item.
categories	array of strings	Category IDs referencing the categories of the 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 Request created successfully

{
    "ID": 33719,
    "departuredDate": "2023-12-01 00:00:00.000",
    "location": "Room 311",
    "request": "iPhone charger",
    "requestNumber": 33,
    "owner": {
        "name": "Jose Jonason",
        "email": "[e-mail]",
        "phoneNumber": "[phone]",
        "reservationNumber": "ABCD13",
    },
    "matchedItemID": null,
    "locationID": "23a10jw221197jc:abc12345",
    "imageUrl": null,
    "resolved": false,
    "status": "waiting-guest-response",
    "askForDetails": {
        "question": "What color is it?",
        "answer": "It's a white charger."
    },
    "brand": "Apple",
    "colors": [
        "burgundy", "blue"
    ],
    "categories": [
        {
            "ID": 12507,
            "categoryID": "electronic_secondary",
            "manuallyClassified": true
        }
    ],
    "createdAt": "2023-11-30 10:44:39.188",
    "updatedAt": "2023-12-06 10:54:11.217"
}

400: Bad Request Invalid fields.

Update the status of a customer Request

PUT https://{environment}.faundit.com/api/v2/requests/:requestID/status

This endpoint allows you to update the status of a Request to not-found or awaiting-guest-response.

Path Parameters

Name	Type	Description
requestID*	number	Customer Request unique identifier. Example: 1317

Request Body

Name	Type	Description
status*	string	The new status you want to update the Request to. Example: "awaiting-guest-response" You can find this under the section Request status.

200: OK Request status updated successfully.

{
    "ID": 33719,
    "departuredDate": "2023-12-01 00:00:00.000",
    "location": "Room 311",
    "request": "iPhone charger",
    "requestNumber": 33,
    "owner": {
        "name": "Jose Jonason",
        "email": "[e-mail]",
        "phoneNumber": "[phone]"
    },
        "matchedItemID": null,
        "locationID": "23a10jw221197jc:abc12345",
        "imageUrl": null,
        "resolved": false,
        "status": "awaiting-guest-response",
        "askForDetails": {
            "question": "What color is it?",
            "answer": "It's a white charger."
        },
        "createdAt": "2023-11-30 10:44:39.188",
        "updatedAt": "2023-12-06 10:54:11.217"
}

404: Not Found Request not found.

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

400: Bad Request Invalid or missing values.

Upload a customer Request image

POST https://{environment}.faundit.com/api/v2/requests/:requestID/upload-image

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

Path Parameters

Name	Type	Description
requestID*	number	Customer Request unique identifier. Example: 1317

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.