Create entities
This page describes how to create individual entities and multiple entities at the same time using the Management API.
For more information about the Entity Detection feature, see Entity Detection.
Entity Detection - Management API
This section provides basic examples of how to create an entity and how to create multiple entities at one time using the Management API.
Authentication
These requests require an access token, as described in Authenticate.
Create an entity
To create a custom entity, use the POST <https://api.symbl.ai/v1/manage/entities
> operation.
import fetch from 'node-fetch';
const accessToken = '<ACCESS_TOKEN>';
const entityParams = {
'type': '<TYPE>',
'subType': '<SUBTYPE>',
'category': 'Custom',
'values': [
'<ENTITY_VOCAB>',
'<ENTITY_VOCAB>',
...
]
}
const fetchResponse = await fetch('https://api.symbl.ai/v1/manage/entities', {
method: 'post',
body: JSON.stringify(entityParams),
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
}
});
const responseBody = await fetchResponse.json();
console.log(responseBody);
Where:
<ACCESS_TOKEN>
is a valid API access token.<TYPE>
describes the type of entity. For example,Vehicle
. You can have multiple entities of the same type.<SUBTYPE>
describes a subset of the entity. For example,TeslaModel
. Subtypes must be unique for each type of entity. For example, there may be only oneTeslaModel
subtype for theVehicle
type.<ENTITY_VOCAB>
is a string to match in a conversation. The vocabulary you provide only returns entities if the string exactly matches a word or phrase in a conversation. For example,["Model X", "Model S", "Model 3", "Model Y"]
.
For additional details about the request body parameters for this request, see Request body parameters.
Create multiple entities
To create multiple custom entities at the same time, use the POST htt://api.symbl.ai/v1/manage/entities/bulk
operation.
import fetch from 'node-fetch';
const accessToken = '<ACCESS_TOKEN>';
const entities = [
{
'type': '<TYPE>',
'subType': '<SUBTYPE>',
'category': 'Custom',
'values': [
'<ENTITY_VOCAB>',
'<ENTITY_VOCAB>',
...
]
},
{
'type': '<TYPE>',
'subType': '<SUBTYPE>',
'category': 'Custom',
'values': [
'<ENTITY_VOCAB>',
'<ENTITY_VOCAB>',
...
]
},
...
]
const fetchResponse = await fetch('https://api.symbl.ai/v1/manage/entities/bulk', {
method: 'post',
body: JSON.stringify(entities),
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
}
});
const responseBody = await fetchResponse.json();
console.log(responseBody);
Where:
<ACCESS_TOKEN>
is a valid API access token.<TYPE>
describes the type of entity. For example,Vehicle
. You can have multiple entities of the same type.<SUBTYPE>
describes a subset of the entity. For example,TeslaModel
. Subtypes must be unique for each type of entity. For example, there may be only oneTeslaModel
subtype for theVehicle
type.<ENTITY_VOCAB>
is a string to match in a conversation. The vocabulary you provide only returns entities if the string exactly matches a word or phrase in a conversation. For example,["Model X", "Model S", "Model 3", "Model Y"]
.
For additional details about the request body parameters for this request, see Request body parameters.
Request body parameters
The following table describes the body parameters that can be used with this request.
Parameter | Required | Description |
---|---|---|
type | Yes | The type of custom entity. Multiple entities can have the same type. |
subType | Yes | The subtype of the custom entity. Subtypes for a type must be unique. |
category | Yes | The value must be Custom . |
values | Yes | A list of vocabulary for the custom entity. Custom entities are identified only if they exactly match the vocabulary in values . |
Response
The following table describes the response body that is returned by this request.
Field | Description |
---|---|
id | The unique identifier of the custom entity. You can use the ID to get, update, and delete the custom entity. |
type | The type of the custom entity. |
subType | The subtype of the custom entity. |
category | The value is Custom . |
values | The list of vocabulary for the custom entity. |
Example response for an entity
{
"id": "4476908732794496",
"type": "Vehicle",
"subType": "TeslaModel",
"category": "Custom",
"values": [
"Model X",
"Model S",
"Model 3",
"Model Y"
]
}
Example response for multiple entities
{
"entities": [
{
"id": "4476908732794496",
"type": "Vehicle",
"subType": "TeslaModel",
"category": "Custom",
"values": [
"Model X",
"Model S",
"Model 3",
"Model Y"
]
},
{
"id": "3242908732344496",
"type": "Vehicle",
"subType": "TeslaTruck",
"category": "Custom",
"values": [
"Cyber truck",
"Semi truck"
]
}
]
}
Updated 4 months ago