Entity API
Create Entity
Create a new entity for a team.
POST
/
v2
/
entities
Create Entity
curl --request POST \
--url https://public.api.serval.com/v2/entities \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"teamId": "<string>",
"entityTypeId": "<string>",
"key": "<string>",
"name": "<string>",
"fieldValues": [
{
"fieldId": "<string>",
"fieldKey": "<string>",
"value": 123,
"pinned": true
}
]
}
'import requests
url = "https://public.api.serval.com/v2/entities"
payload = {
"teamId": "<string>",
"entityTypeId": "<string>",
"key": "<string>",
"name": "<string>",
"fieldValues": [
{
"fieldId": "<string>",
"fieldKey": "<string>",
"value": 123,
"pinned": True
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
teamId: '<string>',
entityTypeId: '<string>',
key: '<string>',
name: '<string>',
fieldValues: [{fieldId: '<string>', fieldKey: '<string>', value: 123, pinned: true}]
})
};
fetch('https://public.api.serval.com/v2/entities', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://public.api.serval.com/v2/entities",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'teamId' => '<string>',
'entityTypeId' => '<string>',
'key' => '<string>',
'name' => '<string>',
'fieldValues' => [
[
'fieldId' => '<string>',
'fieldKey' => '<string>',
'value' => 123,
'pinned' => true
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://public.api.serval.com/v2/entities"
payload := strings.NewReader("{\n \"teamId\": \"<string>\",\n \"entityTypeId\": \"<string>\",\n \"key\": \"<string>\",\n \"name\": \"<string>\",\n \"fieldValues\": [\n {\n \"fieldId\": \"<string>\",\n \"fieldKey\": \"<string>\",\n \"value\": 123,\n \"pinned\": true\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://public.api.serval.com/v2/entities")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"teamId\": \"<string>\",\n \"entityTypeId\": \"<string>\",\n \"key\": \"<string>\",\n \"name\": \"<string>\",\n \"fieldValues\": [\n {\n \"fieldId\": \"<string>\",\n \"fieldKey\": \"<string>\",\n \"value\": 123,\n \"pinned\": true\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://public.api.serval.com/v2/entities")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"teamId\": \"<string>\",\n \"entityTypeId\": \"<string>\",\n \"key\": \"<string>\",\n \"name\": \"<string>\",\n \"fieldValues\": [\n {\n \"fieldId\": \"<string>\",\n \"fieldKey\": \"<string>\",\n \"value\": 123,\n \"pinned\": true\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "<string>",
"key": "<string>",
"name": "<string>",
"teamId": "<string>",
"entityTypeId": "<string>",
"entityTypeKey": "<string>",
"createdByUserId": "<string>",
"updatedByUserId": "<string>",
"createdAt": "2025-01-15T01:30:15.000Z",
"updatedAt": "2025-01-15T01:30:15.000Z",
"deletedAt": "2025-01-15T01:30:15.000Z",
"archivedAt": "2025-01-15T01:30:15.000Z",
"fieldValues": [
{
"id": "<string>",
"entityId": "<string>",
"fieldId": "<string>",
"fieldKey": "<string>",
"fieldName": "<string>",
"dataType": "DATA_TYPE_UNSPECIFIED",
"value": 123,
"setByUserId": "<string>",
"setByAppInstanceId": "<string>",
"createdAt": "2025-01-15T01:30:15.000Z",
"deletedAt": "2025-01-15T01:30:15.000Z",
"pinned": true,
"redacted": true,
"sensitive": true,
"setByFormula": true
}
],
"sourceAppInstanceIds": [
"<string>"
],
"sharedMetadata": {
"sourceTeamId": "<string>",
"sourceTeamName": "<string>"
},
"sourceApps": [
{
"appInstanceId": "<string>",
"displayName": "<string>",
"serviceName": "<string>",
"serviceDisplayName": "<string>",
"logoUrl": "<string>",
"domain": "<string>",
"useIntegratedServiceRegistry": true,
"isCustom": true
}
]
},
"pendingChange": {
"id": "<string>",
"entityId": "<string>",
"entityTypeId": "<string>",
"operation": "ENTITY_CHANGE_OPERATION_UNSPECIFIED",
"state": "ENTITY_PENDING_CHANGE_STATE_UNSPECIFIED",
"entityWorkflowRuleIds": [
"<string>"
],
"submittedByUserId": "<string>",
"createdAt": "2025-01-15T01:30:15.000Z",
"fieldChanges": [
{
"fieldId": "<string>",
"beforeJson": "<string>",
"afterJson": "<string>",
"redacted": true,
"pinned": true
}
],
"runs": [
{
"entityWorkflowRuleId": "<string>",
"workflowId": "<string>",
"workflowRunId": "<string>",
"state": "ENTITY_PENDING_CHANGE_RUN_STATE_UNSPECIFIED"
}
],
"reason": "<string>"
}
}Authentication and permissions
Token requirements: User-based token (OAuth) or Organization-scoped API key or Team-scoped API key. Send a bearer access token for one of these identities. The permissions and resource restrictions below also apply.
| Credential | Access requirements |
|---|---|
| Organization-scoped API key | entities:write |
| Team-scoped API key | entities:write |
| User-based token (OAuth) | Supported, subject to permissions |
- Create in a team’s database: team_id is the team the caller acts as: the entity type’s owning team, or a team the type’s database is shared with at “Can write”. The entity is created in the owning team. An entity type the acting team cannot reach reads as not found. Schema and row-access rules still apply.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
The ID of the team the caller acts as: the entity type's owning team, or a team the type's database is shared with at "Can write". A key or worker bound to a team acts as that team and may name only it or the owning team. The entity is created in the owning team.
The ID of the entity type. A type the acting team cannot reach reads as not found.
The entity key. Sets the value of the entity type's key field (is_key_field). Ignored if field_values already contains a value for the key field.
The entity name. Sets the value of the entity type's name field (is_name_field). Ignored if field_values already contains a value for the name field.
The field values for the entity. Must include the key field and name field values (unless using the key/name convenience fields above).
Show child attributes
Show child attributes
Was this page helpful?
⌘I
Create Entity
curl --request POST \
--url https://public.api.serval.com/v2/entities \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"teamId": "<string>",
"entityTypeId": "<string>",
"key": "<string>",
"name": "<string>",
"fieldValues": [
{
"fieldId": "<string>",
"fieldKey": "<string>",
"value": 123,
"pinned": true
}
]
}
'import requests
url = "https://public.api.serval.com/v2/entities"
payload = {
"teamId": "<string>",
"entityTypeId": "<string>",
"key": "<string>",
"name": "<string>",
"fieldValues": [
{
"fieldId": "<string>",
"fieldKey": "<string>",
"value": 123,
"pinned": True
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
teamId: '<string>',
entityTypeId: '<string>',
key: '<string>',
name: '<string>',
fieldValues: [{fieldId: '<string>', fieldKey: '<string>', value: 123, pinned: true}]
})
};
fetch('https://public.api.serval.com/v2/entities', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://public.api.serval.com/v2/entities",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'teamId' => '<string>',
'entityTypeId' => '<string>',
'key' => '<string>',
'name' => '<string>',
'fieldValues' => [
[
'fieldId' => '<string>',
'fieldKey' => '<string>',
'value' => 123,
'pinned' => true
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://public.api.serval.com/v2/entities"
payload := strings.NewReader("{\n \"teamId\": \"<string>\",\n \"entityTypeId\": \"<string>\",\n \"key\": \"<string>\",\n \"name\": \"<string>\",\n \"fieldValues\": [\n {\n \"fieldId\": \"<string>\",\n \"fieldKey\": \"<string>\",\n \"value\": 123,\n \"pinned\": true\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://public.api.serval.com/v2/entities")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"teamId\": \"<string>\",\n \"entityTypeId\": \"<string>\",\n \"key\": \"<string>\",\n \"name\": \"<string>\",\n \"fieldValues\": [\n {\n \"fieldId\": \"<string>\",\n \"fieldKey\": \"<string>\",\n \"value\": 123,\n \"pinned\": true\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://public.api.serval.com/v2/entities")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"teamId\": \"<string>\",\n \"entityTypeId\": \"<string>\",\n \"key\": \"<string>\",\n \"name\": \"<string>\",\n \"fieldValues\": [\n {\n \"fieldId\": \"<string>\",\n \"fieldKey\": \"<string>\",\n \"value\": 123,\n \"pinned\": true\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "<string>",
"key": "<string>",
"name": "<string>",
"teamId": "<string>",
"entityTypeId": "<string>",
"entityTypeKey": "<string>",
"createdByUserId": "<string>",
"updatedByUserId": "<string>",
"createdAt": "2025-01-15T01:30:15.000Z",
"updatedAt": "2025-01-15T01:30:15.000Z",
"deletedAt": "2025-01-15T01:30:15.000Z",
"archivedAt": "2025-01-15T01:30:15.000Z",
"fieldValues": [
{
"id": "<string>",
"entityId": "<string>",
"fieldId": "<string>",
"fieldKey": "<string>",
"fieldName": "<string>",
"dataType": "DATA_TYPE_UNSPECIFIED",
"value": 123,
"setByUserId": "<string>",
"setByAppInstanceId": "<string>",
"createdAt": "2025-01-15T01:30:15.000Z",
"deletedAt": "2025-01-15T01:30:15.000Z",
"pinned": true,
"redacted": true,
"sensitive": true,
"setByFormula": true
}
],
"sourceAppInstanceIds": [
"<string>"
],
"sharedMetadata": {
"sourceTeamId": "<string>",
"sourceTeamName": "<string>"
},
"sourceApps": [
{
"appInstanceId": "<string>",
"displayName": "<string>",
"serviceName": "<string>",
"serviceDisplayName": "<string>",
"logoUrl": "<string>",
"domain": "<string>",
"useIntegratedServiceRegistry": true,
"isCustom": true
}
]
},
"pendingChange": {
"id": "<string>",
"entityId": "<string>",
"entityTypeId": "<string>",
"operation": "ENTITY_CHANGE_OPERATION_UNSPECIFIED",
"state": "ENTITY_PENDING_CHANGE_STATE_UNSPECIFIED",
"entityWorkflowRuleIds": [
"<string>"
],
"submittedByUserId": "<string>",
"createdAt": "2025-01-15T01:30:15.000Z",
"fieldChanges": [
{
"fieldId": "<string>",
"beforeJson": "<string>",
"afterJson": "<string>",
"redacted": true,
"pinned": true
}
],
"runs": [
{
"entityWorkflowRuleId": "<string>",
"workflowId": "<string>",
"workflowRunId": "<string>",
"state": "ENTITY_PENDING_CHANGE_RUN_STATE_UNSPECIFIED"
}
],
"reason": "<string>"
}
}