API reference inquiries - WEBSALE Dokumentation

The inquiries/ endpoint enables querying inquiry data, as well as deleting and updating its status.

Supported methods

List of all supported methods.

Command/info	Endpoints	GET	POST	PUT	DELETE
Inquiries	inquiries/

Data fields

Name	Type	Meaning
id	String	Unique ID of the inquiry
subshopId	String	Specifies the subshop in which the inquiry was received (e.g. “deutsch”)
processingStatus	INT	Processing status of the inquiry: - `0` = New (newly received) - `1` = Read - `2` = Answered - `3` = Closed
data	Object	Contains form fields and additional metadata of the inquiry as a JSON object
data.fields	Array	Contains the technical name of the field, its label (designation), and the value provided
data.inquiryConfigId	String	ID of the configuration used to create the inquiry form
data.inquiryId	String	Unique ID of the inquiry
data.shopId	String	Technical name of the shop
data.submitter	Object	Contains the email address, the IP address, and the session ID of the submitter
data.subshopId	String	Specifies the subshop in which the inquiry was received (e.g. “deutsch”)
createdAt	String	Date and time of inquiry creation (in ISO 8601 format, UTC)
updatedAt	String	Date and time of the last modification of the inquiry (in ISO 8601 format, UTC)

Example

{
    "createdAt": "2024-10-11T12:03:48Z",
    "data": {
        "fields": [
            {
                "label": "Vorname",
                "name": "firstName",
                "value": "Foo"
            },
            {
                "label": "Nachname",
                "name": "lastName",
                "value": "Bar"
            },
            {
                "label": "Betreff",
                "name": "subject",
                "value": "mySubject"
            },
            {
                "label": "Kundennummer",
                "name": "customerNumber",
                "value": "11"
            },
            {
                "label": "Text",
                "name": "text",
                "value": "myMessage"
            }
        ],
        "inquiryConfigId": "contact",
        "inquiryId": "4dea07ff679aa8b4",
        "shopId": "myshop",
        "submitter": {
            "emailAddress": "email@email.com",
            "ipAddress": "172.18.0.XXX",
            "sessionId": "cf41e72fadae3eaeb0aeca63d..."
        },
        "subshopId": "deutsch"
    },
    "id": "4dea07ff679aa8b4",
    "processingStatus": 0,
    "subshopId": "deutsch",
    "updatedAt": "2024-10-11T12:03:48Z"
}

Using the methods

GET inquiries

Retrieves a list of all existing inquiries — with filter and sort options.

Example

https://www.<your-shop>.de/admin/api/v1/inquiries

Response

{
    "endReached": true,
    "items": [
        {
            "createdAt": "2024-10-11T12:03:48Z",
            "data": {
                "fields": [
                    {
                        "label": "Vorname",
                        "name": "firstName",
                        "value": "Foo"
                    },
                    ...
                ],
                "inquiryConfigId": "contact",
                "inquiryId": "4dea07ff679aa8b4",
                "shopId": "myshop",
                "submitter": {
                    "emailAddress": "email@email.com",
                    "ipAddress": "172.18.0.XXX",
                    "sessionId": "cf41e72fadae3eaeb0aeca63d..."
                },
                "subshopId": "deutsch"
            },
            "id": "4dea07ff679aa8b4",
            "processingStatus": 0,
            "subshopId": "deutsch",
            "updatedAt": "2024-10-11T12:03:48Z"
        },
        ...
    ],
    "nextPageToken": "NQ",
    "totalCount": 6
}

Filter fields

createdAt, updatedAt, id, subshopId, processingStatus, inquiryConfigId

Sort fields

createdAt, updatedAt, id, subshopId, processingStatus

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or do not have the required permissions to read inquiries.
400 Bad Request	”invalidValue”	`size` ∉ [1;300]	`pageToken` is not a number or is less than 0.
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:“.
503 Service Unavailable	”internalError”	Not all inquiries could be decrypted.

GET inquiries/{inquiryId}

Retrieves the details of a single inquiry by its ID.

Example

https://www.<your-shop>.de/admin/api/v1/inquiries/4dea07ff679aa8b4

Response

{
    "createdAt": "2024-10-11T12:03:48Z",
    "data": {
        "fields": [
            {
                "label": "Vorname",
                "name": "firstName",
                "value": "Foo"
            },
            {
                "label": "Nachname",
                "name": "lastName",
                "value": "Bar"
            },
            {
                "label": "Betreff",
                "name": "subject",
                "value": "mySubject"
            },
            {
                "label": "Kundennummer",
                "name": "customerNumber",
                "value": "11"
            },
            {
                "label": "Text",
                "name": "text",
                "value": "myMessage"
            }
        ],
        "inquiryConfigId": "contact",
        "inquiryId": "4dea07ff679aa8b4",
        "shopId": "myshop",
        "submitter": {
            "emailAddress": "email@email.com",
            "ipAddress": "172.18.0.XXX",
            "sessionId": "cf41e72fadae3eaeb0aeca63d..."
        },
        "subshopId": "deutsch"
    },
    "id": "4dea07ff679aa8b4",
    "processingStatus": 0,
    "subshopId": "deutsch",
    "updatedAt": "2024-10-11T12:03:48Z"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or do not have the required permissions to read inquiries.
404 Not Found		The inquiry was not found.
503 Service Unavailable	”internalError”	The inquiry could not be decrypted.

GET inquiries/open

This endpoint returns an overview of the number of open inquiries grouped by inquiry configuration. The response contains a list of objects, where each object specifies the number of open inquiries (count) and the associated inquiry configuration (inquiryConfigId).

Example

https://www.<your-shop>.de/admin/api/v1/inquiries/open

Response

{
    "items": [
        {
            "count": 3,
            "inquiryConfigId": "catalogue"
        },
        {
            "count": 15,
            "inquiryConfigId": "contact"
        },
        {
            "count": 1,
            "inquiryConfigId": "productQuestion"
        },
        {
            "count": 1,
            "inquiryConfigId": "returnInquiry"
        }
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or do not have the required permissions to read inquiries.
503 Service Unavailable	”internalError”	Inquiries could not be loaded.

PUT inquiries/{inquiryId}

Updates the processing status of a specific inquiry. Possible values for processingStatus:

0 = New
1 = Read
2 = Answered
3 = Closed

Example

https://www.<your-shop>.de/admin/api/v1/inquiries/bda4c9c28ebc6920

Request body

{
    "processingStatus": 1
}

Response

{
    "createdAt": "2024-10-11T12:03:48Z",
    "data": {
        "fields": [
            {
                "label": "Vorname",
                "name": "firstName",
                "value": "Foo"
            }
        ],
        "inquiryConfigId": "contact",
        "inquiryId": "bda4c9c28ebc6920",
        "shopId": "myshop",
        "submitter": {
            "emailAddress": "email@email.com",
            "ipAddress": "172.18.0.XXX",
            "sessionId": "cf41e72fadae3eaeb0aeca63d..."
        },
        "subshopId": "deutsch"
    },
    "id": "bda4c9c28ebc6920",
    "processingStatus": 1,
    "subshopId": "deutsch",
    "updatedAt": "2024-10-11T12:05:00Z"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or do not have the required permissions to write inquiries.
400 Bad Request		Request body could not be loaded as JSON. Updating failed.
400 Bad Request	”missing”	`processingStatus` was not provided.
400 Bad Request	”unknownDataField”	An attempt was made to provide an unknown field. Only `processingStatus` is allowed.
400 Bad Request	”invalidFormat”	`processingStatus` is not a number.
400 Bad Request	”invalidValue”	`processingStatus` is outside the valid range (0–3).
404 Not Found		The inquiry was not found.
503 Service Unavailable	”internalError”	The inquiry could not be decrypted.

DELETE inquiries/{inquiryId}

Permanently deletes a specific inquiry.

Example

https://www.<your-shop>.de/admin/api/v1/inquiries/bda4c9c28ebc6920

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or do not have the required permissions to delete inquiries.
404 Not Found		The inquiry was not found.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

​Supported methods

​Data fields

​Example

​Using the methods

​GET inquiries

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET inquiries/{inquiryId}

​Example

​Response

​Error codes

​GET inquiries/open

​Example

​Response

​Error codes

​PUT inquiries/{inquiryId}

​Example

​Request body

​Response

​Error codes

​DELETE inquiries/{inquiryId}

​Example

​Response

​Error codes

​Support

Supported methods

Data fields

Example

Using the methods

GET inquiries

Example

Response

Filter fields

Sort fields

Error codes

GET inquiries/{inquiryId}

Example

Response

Error codes

GET inquiries/open

Example

Response

Error codes

PUT inquiries/{inquiryId}

Example

Request body

Response

Error codes

DELETE inquiries/{inquiryId}

Example

Response

Error codes

Support