Developers › API reference › User-defined fields

PUT `/api/v1/udf/{table}/{slot}`

Define a field (Admins; versioned).

Scope udf:admin
operationId referenceSaveUdf

The token needs the scope udf:admin, and the person or service account behind it needs the matching privileges and account permissions, exactly as on the screens. See Scopes.

Request

PUT /api/v1/udf/{table}/{slot}

Path parameters

Name	Description	Example
`table`	The reference table: securities, issuers, accounts, account_groups, brokers, models, benchmarks, desks or list_entries.	`securities`
`slot`	The slot, 1 to 10.	`1`

Headers

Header	Required	Value
`Authorization`	yes	`Bearer <token>`: an OAuth access token (`vat_…`) or a personal access token (`vpt_…`). Get a token
`Content-Type`	yes	`application/json`

Body: `UdfDefIn`

Field	Type	Required	Description
`name`	string	yes	The field's name (unique within the table).
`type`	string	yes	text, integer, decimal, date, boolean or list.

Other fields of the resource are accepted too; unknown fields are reported by a validation problem, never ignored silently.

Decimals (money, prices, quantities, percentages) are sent as strings, ids as strings, times as ISO 8601 UTC.

Examples

Keep the token in an environment variable (VESTORIS_TOKEN), never in the script.

curl

curl -X PUT "https://vestoris.com/api/v1/udf/securities/1" \
  -H "Authorization: Bearer $VESTORIS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Internal rating","type":"list","options":"AAA\nAA\nA\nBBB\nBB\nB\nCCC\nD","flags":{"forms":true,"blotter":true,"compliance":true}}'

Python (requests)

import os, requests

r = requests.put(
    "https://vestoris.com/api/v1/udf/securities/1",
    headers={
        "Authorization": f"Bearer {os.environ['VESTORIS_TOKEN']}",
    },
    json={
        "name": "Internal rating",
        "type": "list",
        "options": "AAA\nAA\nA\nBBB\nBB\nB\nCCC\nD",
        "flags": {
            "forms": True,
            "blotter": True,
            "compliance": True
        }
    },
    timeout=30,
)
r.raise_for_status()  # errors are application/problem+json with a stable "code"
print(r.json())

JavaScript (fetch)

const res = await fetch("https://vestoris.com/api/v1/udf/securities/1", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.VESTORIS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "name": "Internal rating",
      "type": "list",
      "options": "AAA\nAA\nA\nBBB\nBB\nB\nCCC\nD",
      "flags": {
          "forms": true,
          "blotter": true,
          "compliance": true
      }
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.detail}`); // problem+json
console.log(data);

Response

200 OK, application/json: UdfDef. Rate-limit headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.

Response fields

Field	Type	Description
`slot`	any	The slot number, 1 to 10.
`column`	string	The database column behind the slot (udf_1 … udf_10).
`active`	any	Whether it is in use.
`name`	any	The name.
`description`	any	A description in plain words.
`type`	any	The type.
`max_length`	any	Maximum length for text.
`precision`	any	Total digits for decimals.
`scale`	any	Digits after the decimal point.
`required`	any	Whether a value is required.
`default`	any	The value used when none is given.
`min`	any	Minimum allowed value.
`max`	any	Maximum allowed value.
`pattern`	any	A pattern text values must match.
`options`	any	The list's options, in order.
`flags`	object	Where the field appears: forms, searchable, blotter, compliance, workflow.
`version`	any	Version number.
`updated_at`	date-time or null	When it last changed.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "slot": 1,
    "column": "udf_1",
    "active": true,
    "name": null,
    "description": "",
    "type": null,
    "max_length": null,
    "precision": null,
    "scale": null,
    "required": false,
    "default": null,
    "min": null,
    "max": null,
    "pattern": null,
    "options": null,
    "flags": {
        "forms": true,
        "searchable": true,
        "blotter": true
    },
    "version": 1,
    "updated_at": "2026-10-27T14:30:00Z"
}

Example values. Your values depend on your firm's data; prices, orders and fills are simulated.

Status codes and errors

Errors are application/problem+json (RFC 9457) with a stable code to program against; the detail says what to fix. See Errors.

Status	When	Problem codes
200	Success
400	The request is malformed	`invalid_request` `invalid_json`
401	No token, or it is invalid or expired	`invalid_token`
403	The token lacks the scope, or the person or service account behind it lacks the privilege or account permission	`insufficient_scope` `forbidden` `ip_not_allowed`
404	Not found, or not visible to you (the API never confirms what you may not see)	`not_found`
409	Not possible in the current state	`invalid_transition` `conflict`
422	Validation failed (the detail says which field), or blocked	`validation_failed`
429	Rate limited: wait for Retry-After seconds	`rate_limited`

{
    "type": "https://vestoris.com/developers/errors#validation_failed",
    "title": "Validation failed",
    "status": 422,
    "detail": "Quantity must be greater than zero.",
    "code": "validation_failed",
    "instance": "/api/v1/udf/securities/1"
}

On the screens

The same thing in the app is explained in:

User-defined fields

PUT /api/v1/udf/{table}/{slot}