Entity API

Update Entities

Set the same field values on up to 100 selected database records in one table, for example changing their name field. Only supplied fields change. Each record is authorized and validated independently: data contains saved records, pending_changes contains changes held for before-save workflows, and failures contains records that were not updated. A successful response can include failures; inspect all three lists before reporting success or retrying. Retry only failed records, not saved or pending records.

PUT

entities

Update Entities

curl --request PUT \
  --url https://public.api.serval.com/v2/entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityIds": [
    "<string>"
  ],
  "fieldValues": [
    {
      "fieldId": "<string>",
      "fieldKey": "<string>",
      "value": 123,
      "pinned": true
    }
  ]
}
'

import requests

url = "https://public.api.serval.com/v2/entities"

payload = {
    "entityIds": ["<string>"],
    "fieldValues": [
        {
            "fieldId": "<string>",
            "fieldKey": "<string>",
            "value": 123,
            "pinned": True
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entityIds: ['<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 => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'entityIds' => [
        '<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  \"entityIds\": [\n    \"<string>\"\n  ],\n  \"fieldValues\": [\n    {\n      \"fieldId\": \"<string>\",\n      \"fieldKey\": \"<string>\",\n      \"value\": 123,\n      \"pinned\": true\n    }\n  ]\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://public.api.serval.com/v2/entities")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entityIds\": [\n    \"<string>\"\n  ],\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::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entityIds\": [\n    \"<string>\"\n  ],\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
        }
      ]
    }
  ],
  "pendingChanges": [
    {
      "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>"
    }
  ],
  "failures": [
    {
      "entityId": "<string>",
      "message": "<string>"
    }
  ]
}

Authentication and permissions

Token requirements: User-based token (OAuth) or Organization-scoped API key or Workspace-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`
Workspace-scoped API key	`entities:write`
User-based token (OAuth)	Supported, subject to permissions

Permissions joined by + are all required; or separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Workspace keys must allow every workspace checked by the request. OAuth access depends on the user’s roles and resource access.

Change a record in a workspace’s database, or in a database shared with one of your workspaces: The permission is checked on the record’s owning workspace, or on a workspace the record’s database is shared with; Read alone admits no changes. A record in a database not shared with one of your workspaces is refused. Update requires Update access; archive and unarchive require Delete access. Database, table, field and record conditions still apply.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

entityIds

string[]

required

Up to 100 record IDs from one table. Duplicate IDs are updated once.

fieldValues

EntityFieldValueInput · object[]

required

Set these values on every selected record; omitted fields are unchanged.

Show child attributes

Response

200 - application/json

Success

data

Entity · object[]

Show child attributes

pendingChanges

EntityPendingChange · object[]

Show child attributes

failures

UpdateEntitiesFailure · object[]

Show child attributes

Update Entities

curl --request PUT \
  --url https://public.api.serval.com/v2/entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityIds": [
    "<string>"
  ],
  "fieldValues": [
    {
      "fieldId": "<string>",
      "fieldKey": "<string>",
      "value": 123,
      "pinned": true
    }
  ]
}
'

import requests

url = "https://public.api.serval.com/v2/entities"

payload = {
    "entityIds": ["<string>"],
    "fieldValues": [
        {
            "fieldId": "<string>",
            "fieldKey": "<string>",
            "value": 123,
            "pinned": True
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entityIds: ['<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 => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'entityIds' => [
        '<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  \"entityIds\": [\n    \"<string>\"\n  ],\n  \"fieldValues\": [\n    {\n      \"fieldId\": \"<string>\",\n      \"fieldKey\": \"<string>\",\n      \"value\": 123,\n      \"pinned\": true\n    }\n  ]\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://public.api.serval.com/v2/entities")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entityIds\": [\n    \"<string>\"\n  ],\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::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entityIds\": [\n    \"<string>\"\n  ],\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
        }
      ]
    }
  ],
  "pendingChanges": [
    {
      "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>"
    }
  ],
  "failures": [
    {
      "entityId": "<string>",
      "message": "<string>"
    }
  ]
}

Get started

Authentication

Endpoints

Development

Update Entities

Authentication and permissions

Authorizations

Body

Response

​Authentication and permissions

Authorizations

Body

Response

Authentication and permissions