Create a person event definition

Request#

POST /api/v1/person-events

Requires person-events:create and an active token creator who remains an administrator of the token’s organization. Person event setup and permissions.

Send Authorization: Bearer YOUR_API_TOKEN and Accept: application/json.

Query parameters#

This endpoint does not use query parameters.

Request body#

Send JSON with Content-Type: application/json.

name string Required

Display name, 3–255 characters.

group string Optional

Always person. Optional; any other value returns 422. Cannot change after creation.

icon string Optional

Available icon name, up to 100 lowercase letters, numbers, or hyphens. Use setup options; defaults to user when creating.

color string Optional

Color from setup options; defaults to gray when creating.

visible boolean Optional

Whether this definition is offered when logging person events; defaults to true when creating.

sets_status string or null Optional

active or inactive to set the person’s status whenever this event is logged, or null (the default) to leave status alone.

limit_to_categories integer array Optional

Accepted only as an empty list. Category restrictions apply to asset events only.

cost_category_id null Optional

Accepted only as null. Cost categories apply to asset lifecycle events only.

fields object array Optional

Complete replacement field list. See field definitions below. Omit to use the defaults: date, time, and notes.

Field definitions#

A supplied fields array replaces the complete list, with at most 100 entries. Each entry accepts only the following properties. Preserve every existing field you want to keep and strip read-only response properties before sending it.

id integer or null Required

Existing field ID from this definition, or null for a new field. Existing IDs must be distinct.

slug string or null Required

Existing immutable slug, a built-in slug (date, time, and notes), or null for a new custom field. Built-in slugs must be unique within the list.

name string Required

Display label, 2–255 characters.

datatype string Required

text, number, date, boolean, yesno, phone, or editor. Built-ins use their server-defined datatype. Fields with saved values cannot change datatype.

size string Required

Display width: full or half.

is_required boolean Required

Whether a value is required when the event is logged. Always normalized to false for boolean fields.

visible boolean Required

Whether the field is shown and accepted. Set false to hide a field while retaining its history.

The built-in date and time fields map to the logged event’s event_date, and notes maps to its description; marking them required makes those inputs required when logging an event. Custom fields take values through field_values. is_system, has_values, and position are read-only; omit them from field payloads. The array order determines field position. Adding required fields does not backfill historical values.

Retry protection#

Requires Idempotency-Key: 8–128 letters, numbers, dots, underscores, colons, or hyphens. Reuse the same method, path, body, and key for retries. Successful responses are remembered for 24 hours per token. Conflicting key reuse returns 409. Idempotency and retries.

Example#

Set ASSETCENTER_API_TOKEN as described in the quick start.

curl --request POST "https://my.assetcenter.app/api/v1/person-events" \
  --header "Authorization: Bearer $ASSETCENTER_API_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{"name":"Badge issued","fields":[{"id":null,"slug":"date","name":"Date","datatype":"date","size":"half","is_required":false,"visible":true},{"id":null,"slug":null,"name":"Badge number","datatype":"text","size":"full","is_required":true,"visible":true}]}'

For retries, reuse the original key instead of generating another UUID.

Response#

201 Created. Illustrative values; IDs and positions will differ.

{
  "data": {
    "id": 42,
    "group": "person",
    "name": "Badge issued",
    "icon": "user",
    "color": "gray",
    "visible": true,
    "is_system": false,
    "is_global": false,
    "parent_id": null,
    "position": 0,
    "limit_to_categories": [],
    "cost_category_id": null,
    "sets_status": null,
    "can_delete": true,
    "fields": [
      {
        "id": 101,
        "slug": "date",
        "name": "Date",
        "datatype": "date",
        "size": "half",
        "position": 0,
        "is_system": true,
        "is_required": false,
        "visible": true,
        "has_values": false
      },
      {
        "id": 102,
        "slug": null,
        "name": "Badge number",
        "datatype": "text",
        "size": "full",
        "position": 1,
        "is_system": false,
        "is_required": true,
        "visible": true,
        "has_values": false
      }
    ]
  }
}

Behavior and constraints#

Only name is required. The definition is created in the token’s organization as a custom event and appended to the end of the list. Omitted fields use the defaults (date, time, and notes); send an empty list for no fields. The returned definition includes fields and can_delete, as described in get a definition. Protected IDs, system flags, timestamps, position, and unknown input return 422.

Errors#

401 means the customer token is missing, invalid, expired, or revoked, or its creator is inactive. 403 means the required permission or administrator membership is missing. 404 means the definition is unavailable in the token’s organization. 422 means invalid or unsupported input. 429 means the rate limit was reached. Errors and limits. 409 means conflicting idempotency-key reuse or a protected deletion.