Create an asset · Fieldmotion API

When to use this endpoint

Use Asset_new when creating one asset from CRM1 or an integration. Resolve the asset type and any owner/location IDs before calling it.

For bulk CSV workflows, the CRM asset importer calls this endpoint internally and then applies additional edit logic.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler requires a nonzero logged-in user ID but performs no additional page or role-permission check.

The insert and relationship lookups use the authenticated tenant.

Parameters

Parameter	Type	Required	Description
`name`	String	Yes	Asset name after trimming. Blank and the PHP-false string `"0"` are rejected. When `asset-unique-name` is enabled, it must differ from every non-deleted asset name after trimming.
`type_id`	Integer string	Yes	Positive existing asset-type ID. Zero, negative, and nonexistent IDs are rejected.
`code`	String	No	Serial number after trimming; defaults to blank. When `asset-unique-code` is enabled, it must be unique among non-deleted assets.
`book_id`	String	No	External book ID after trimming; defaults to blank. When `asset-unique-book_id` is enabled, it must be unique among non-deleted assets. The endpoint does not enforce the schema’s 32-character limit before inserting.
`make`	String	No	Make after trimming; defaults to blank. The endpoint does not enforce the schema’s 45-character limit.
`model`	String	No	Model after trimming; defaults to blank. The endpoint does not enforce the schema’s 45-character limit.
`value`	Numeric string	No	Converted with `floatval`; defaults to `0`. Values above `99999999.99` are rejected. Nonnumeric text becomes zero; negative values are not explicitly rejected.
`location_type`	Integer string	No	Immediate whereabouts type; defaults to `0`. Normal values are `0` location, `1` customer, and `2` asset, but this create handler does not validate the range or target.
`location_id`	Integer string	No	Immediate location target ID; defaults to `0`. Existence and compatibility with `location_type` are not validated.
`owner_id`	Integer string	No	Customer ID stored as owner; defaults to `0`. The customer is not validated.
`meta`	Array	No	Initial metadata map. Only a PHP/request array is accepted; other wire values are replaced with an empty map. It is stored as JSON after custom and home-location processing.
`custom_values`	JSON object string or array	No	Initial asset custom values. A string is JSON-decoded; a non-array becomes an empty custom map. Field display names are converted to canonical layout IDs when the asset type has an unambiguous matching custom layout field. These values replace `meta.custom`.
`home_location_type`	Integer or name string	No	Home-location type stored in metadata. Accepts `-1` through `2`, or `location`/`area`/`site`, `customer`/`client`, or `asset`. Legacy alias: `loc_type`.
`home_location_id`	Integer or exact name string	No	Home-location ID or an exact case-insensitive name that resolves to exactly one row of the selected type. Blank and `-1` store `-1`. If only an ID/name is supplied, the type defaults to customer. Legacy alias: `loc_id`.
`warranty`	Date or spreadsheet serial string	No	A `YYYY-MM-DD` string, or an integer spreadsheet date serial converted relative to 1899-12-30. Other supplied formats are logged and silently omitted rather than returning an error.

Example request

$created = FM_api('Asset_new', [
	'name' => 'Compressor 4',
	'type_id' => '47',
	'code' => 'CMP-004',
	'book_id' => 'BOOK-2048',
	'make' => 'ExampleCo',
	'model' => 'CX4',
	'value' => '1250.00',
	'owner_id' => '1088',
	'location_type' => '1',
	'location_id' => '1088',
	'warranty' => '2027-09-24',
	'custom_values' => json_encode(['Inspection class' => 'A']),
]);

Example response

{
  "ok": 1,
  "id": 4821
}

The new server ID is returned as a JSON number. The response does not echo or expand the created row.

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":"Name and Type are required"}`	The trimmed name is false-like or `type_id` converts to zero.
`{"error":"value too large. cannot be higher than 99999999.99"}`	The converted value exceeds the positive schema maximum.
`{"error":"That type_id does not match an existing Type"}`	No asset type has the supplied nonzero ID.
`{"error":"An asset of that name already exists"}`	Name uniqueness is enabled and a non-deleted match exists.
`{"error":"An asset with that Book ID already exists"}`	Book-ID uniqueness is enabled and a non-deleted match exists.
`{"error":"An asset with that Serial Number already exists"}`	Serial-number uniqueness is enabled and a non-deleted match exists.
`{"error":"Invalid Home Location Type"}`	A supplied home-location type is outside the accepted range or names.
`{"error":"Could not resolve Home Location"}`	A named home location matches zero or multiple eligible rows.

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

Behaviour and edge cases

Current whereabouts references are trusted. The endpoint does not validate location_type, location_id, or owner_id, and it does not run the circular-whereabouts guard used by the newer update contract. Validate these relationships before creation.

The uniqueness settings are asset-unique-name, asset-unique-book_id, and asset-unique-code. Each check excludes soft-deleted assets but includes archived assets.
All custom values are stored below meta.custom. Empty metadata is encoded with JSON object semantics, so a normal new row contains an object rather than a list.
Named asset home locations resolve only against non-archived assets, but that lookup does not filter soft-deleted asset rows. Named customer home locations exclude soft-deleted customers.
The warranty’s YYYY-MM-DD check verifies shape, not calendar validity. Database rejection of an invalid date or overlong field is not converted into a specific application error.
This creates one record and offers no filtering or pagination.

Side effects

Inserts the asset with cdate and last_edited set to the current server date-time.
Creates an initial active asset_movements row at the same date-time, including the starting location and an explicit owner value. This insert is not wrapped in a transaction with the asset insert.
Invalidates the assets cache and also customer_assets when a nonzero owner or a nonzero typed location is supplied.
Writes an asset audit-log entry.

See it in Fieldmotion

CRM1

Open Assets or a customer’s Assets tab, choose the create action, complete the asset popup, and filter Network requests for Asset_new. The popup supplies type, owner, current location, identity fields, make, model, and value.

CRM2

No direct production CRM2 call to Asset_new was found. CRM2’s Assets module uses its newer create-data contract.

Related endpoints

Asset_get retrieves the newly created stored fields.
Asset_setOwner changes ownership and adds movement history.
Asset_delete soft-deletes an asset.