Prerequisites
Data format
The API uses HTTP and JSON to retrieve and deliver data.
State Management
The Neocom API has state management already built into it. Therefore, only the answer(s) to the current question needs to be sent to the API together with a session-token. The session-token identifies an advisor session and can be used only once.
For every request to the API, the session-token needs to be sent as well, except for the first request. If the session-token does not exist, a new session is created and the new session-token is returned to the payload.
The session-token needs to be sent as a separate HTTP header: Neocom-Session-Token.
Authentication
In order to use the API, an API key is required. This API key needs to be sent with every request as a separate HTTP header: Neocom-API-Key
Advisor
The API supports multiple advisors per client. Therefore, for each request, the ID of the advisor needs to be sent in the HTTP headers: Neocom-Advisor-ID.
The Advisor-ID can be obtained in the Neocom Admin Portal.
Data Entities
Question
Represents a question with answers as defined in the Neocom Admin Portal. A question is identified in the API via the question-id, which is also used when sending the payload to the API with the answer to the current question.
Three question types exist:
- SINGLE: Only one answer can be selected
- MULTIPLE: Multiple answers can be selected
- RANGE: A numeric range of allowed values
Single & Multiple question-type Questions
{
"question_id": "some-question-id",
"title": "some question title",
"description": "some question description" || null,
"image": "link to a question image" || null,
"question_type": "SINGLE" || "MULTIPLE",
"skip_text": "Skip question" || null,
"answers": [<Answer Object>]
}
Range question-type Question
"question_id": "some-question-id",
"title": "some question title",
"description": "some question description" || null,
"image": "link to a question image" || null,
"question_type": "RANGE",
"skip_text": "Skip question" || null,
"range_from": 500,
"range_to": 5000,
"range_step": 500,
"range_label": "€",
"range_groupings": [
{
"title": "Bis zu 1.500€",
"position": 0,
"range_from": 500,
"range_to": 1500
}
],
"answers": [
{
"answer_id": "500.0-1500.0",
"range_from": 500,
"range_to": 1500
}
]
}
Answer
Represents an answer to a question. An answer is identified in the API via the answer-id, which is also used when sending the payload to the API with the answer to the current question.
The background_color is used for colour answers.
{
"answer_id": "some-answer-id",
"title": "some answer title",
"description": "some answer description" || null,
"image": "link to an answer image" || null,
"background_color": "#ff0044" || null
}
Result Item
A result item represents a product recommended by Neocom.
{
"sku": "some-sku",
"image": "link to product image",
"link": "link to the product",
"title": "some product title",
"description": "some product description" || null,
"price": "99.99"
}
Get the first question
To get the first question and at the same time to create a new session, send a POST request including the required HTTP headers to the next endpoint.
Request
curl -X POST https://public.api.neocomapp.com/api/v7/next/
-H 'Content-Type: application/json' \
-H 'Neocom-API-Key: some-api-key' \
-H 'Neocom-Advisor-ID: some-advisor-id'
Response
{
"session_token": "some-session-token",
"question": <Question Object>,
"results": null
}
Get the second (and more) question
All subsequent request in order to get the next question follow the same pattern and endpoint as the first request. In order to link the request to a session, the session-token needs to be sent in the HTTP headers.
If the question key is null, the end of the advisor has been reached and there is no more question to come.
Once the results key is not null and contains an array of result objects, results can be shown already. These results might not be matching to all preferences of the customer yet until all questions have been asked (meaning the question key is null). Results are sent once all Filtering questions have been asked, which is usually at ~25% of the conversation (this can be controlled in the Neocom Admin Portal). It is up to the client to decide whether to show the results only at the end of the conversation or already earlier as a sneak-peek.
Skipping a question is achieved by sending an empty list of answers.
Request
curl -X POST https://public.api.neocomapp.com/api/v7/next/
-H 'Content-Type: application/json' \
-H 'Neocom-API-Key: some-api-key' \
-H 'Neocom-Advisor-ID: some-advisor-id' \
-H 'Neocom-Session-Token: some-session-token' \
-d '{ "question_id": "some-question-id", "answers": ["some-answer-id"]}'
Response
{
"session_token": "some-session-token",
"question": <Question Object> || null,
"results": [<Result Object>] || null
}