Set an asset book ID · Fieldmotion API

When to use this endpoint

Use Asset_setBookId for an inline edit when the caller already knows the asset ID.

Use Asset_getByBookID to resolve a record from this value after it has been assigned.

Authentication and permissions

The handler requires an authenticated tenant context, established by signed API-key fields or a CRM session. It checks the tenant table prefix but does not separately require a logged-in user ID.

No page, role, or asset permission is checked.

Parameters

Parameter	Type	Required	Description
`id`	Integer string	Yes	Positive server-side asset ID. The handler does not verify that the asset exists.
`val`	String	Yes	New book ID after trimming. Blank is accepted. The endpoint does not enforce the schema’s 32-character limit before writing.

Example request

$result = FM_api('Asset_setBookId', [
	'id' => '4821',
	'val' => 'BOOK-2048',
]);

Example response

{
  "ok": 1
}

Errors and unusual responses

Response	Condition
`{"error":"not logged in"}`	No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
`{"error":"missing or invalid parameter: id"}`	`id` is absent or does not convert to a positive integer.
`{"error":"missing or invalid parameter: val"}`	`val` is omitted. A present blank value is accepted.
`{"error":"An asset with that Book ID already exists"}`	The tenant setting `asset-unique-book_id` is enabled and another non-deleted asset has the same trimmed value.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

Success does not prove the row exists or the write succeeded. There is no target existence check, and a database rejection such as an overlong value is not converted into an error. The endpoint still writes its audit entry and returns {"ok":1}.

The uniqueness check excludes the addressed ID and all soft-deleted rows, but includes archived rows.
There is no no-change shortcut; submitting the current value still performs the update and audit path.
The update itself has no active, archived, or deleted filter, so an existing soft-deleted row can be changed.
This is a single-record mutation; it provides no list filtering or pagination.

Side effects

The update attempts to set book_id and last_edited, sets edited_uuid to Asset_setBookId, invalidates the asset cache, and writes an asset audit entry.

See it in Fieldmotion

CRM1

Open Assets, edit the Book ID cell, and filter Network requests for Asset_setBookId. CRM1 restores the old display value if the endpoint returns an error.

CRM2

No direct production CRM2 call to Asset_setBookId was found; CRM2 uses its broader update contract.

Related endpoints

Asset_getByBookID looks up the complete row by this value.
Asset_get can verify the stored value by ID.
Asset_new accepts a book ID during creation and uses the same uniqueness setting.