> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/docs/developers/api-documentation/service/update-service-order-form-field.md).

# Update service order form field

Update a service order form field. Only the tenant's own custom fields are updated here: a field carrying a system kind is a platform field, and an update or an archiving of one is refused — it belongs to the platform. The field type is immutable and cannot be updated. Editing the label leaves the field key alone, and leaves the label already snapshotted on existing service orders alone. Fields are never deleted — set archived to take a field out of use. An archived field is kept for the service orders that already captured it, but cannot be placed on a form any more. Only SERVICE\_CONFIG may archive a field or set sensitive, and sensitive only flips one way, from false to true. A field of type SECRET is always sensitive and cannot be made non-sensitive.

Required permissions: SERVICE\_STORE\_CONFIG, SERVICE\_CONFIG

```json
{"openapi":"3.0.2","info":{"title":"Flow Retail API version 2","version":"2.0.0"},"tags":[{"name":"Service","description":"Service"}],"servers":[{"description":"Flow Retail Production","url":"https://api.flowretail.com/v2"},{"description":"Flow Retail Stage","url":"https://api.stage.flowretail.com/v2"}],"security":[{"accessToken":[]},{"authToken":[]},{"integrationToken":[]}],"components":{"securitySchemes":{"accessToken":{"description":"Access token recevied after user login with a deviceToken","scheme":"bearer","type":"http"},"authToken":{"description":"Token received from the auth service","scheme":"bearer","type":"http"},"integrationToken":{"scheme":"bearer","type":"http"}},"responses":{"ServiceFormFieldResponse":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceFormFieldResponseSchema"}}}}},"schemas":{"ServiceFormFieldResponseSchema":{"title":"ServiceFormFieldResponseSchema","description":"A field in the tenant's service order form field library. A field is defined once for the tenant and can be placed on any number of intake forms.\nThe library holds two populations. A field carrying a systemKind is a platform field: it is already there for every tenant, the platform labels and controls it, and the tenant cannot change it — no relabelling, no archiving, no change of validation or sensitivity. A field whose systemKind is null is the tenant's own custom field, created and edited by the tenant.\nfieldType is immutable after creation — create a new field instead of changing it.\nsensitive only flips one way, from false to true, and only with SERVICE_CONFIG, and only on a custom field. The field type SECRET always implies sensitive, which is why the platform field PASSCODE is always sensitive.\nValues captured for a sensitive field are left out of search results, webhooks and exports, and are deleted when the service order reaches a terminal state. A field of type SECRET is not captured as a form value at all: what is captured for it is stored as a service order secret, listed by its label alone and read through the secrets reveal endpoint.\nFields are never deleted — archive a custom field to take it out of use. Only SERVICE_CONFIG may archive a field or flip sensitive, and neither is ever done to a platform field.","type":"object","required":["serviceFormFieldUid","tenantUid","fieldKey","label","fieldType","systemKind","sensitive","selectOptions","validation","note","archived","createdAt","createdBy","lastModifiedAt","lastModifiedBy"],"properties":{"serviceFormFieldUid":{"$ref":"#/components/schemas/UID"},"tenantUid":{"$ref":"#/components/schemas/UID"},"fieldKey":{"type":"string","description":"A stable slug to recognise the field by in exports and integrations — it never changes. On a custom field it is generated by the server from the label at creation and survives every label edit; a platform field carries a fixed platform key, the same for every tenant and every language."},"label":{"type":"string","description":"The label shown for the field at intake. On a platform field it is the platform's own label, localized to the reader's language; on a custom field it is the label the tenant gave it."},"fieldType":{"$ref":"#/components/schemas/ServiceFormFieldTypeENUM"},"systemKind":{"nullable":true,"description":"The well-known Flow concept this field represents. A system kind marks the field as a platform field, labelled and controlled by the platform and unchangeable by the tenant; null marks the tenant's own custom field.","allOf":[{"$ref":"#/components/schemas/ServiceFormFieldSystemKindENUM"}]},"sensitive":{"type":"boolean","description":"Sensitive values are left out of search results, webhooks and exports, and are deleted when the service order reaches a terminal state. On a custom field it flips one way only, from false to true, and only with SERVICE_CONFIG; on a platform field it is fixed — PASSCODE is sensitive, the rest are not, and it never changes. Always true when the field type is SECRET, whose values are stored as service order secrets rather than as form values."},"selectOptions":{"type":"array","description":"The values a user can pick from when the field type is SELECT or MULTI_SELECT. Empty for every other field type.","items":{"type":"string"}},"validation":{"type":"string","description":"The rule captured values are matched against, on top of the check the field type already implies. It is either one of the named rules phone and email, or a regular expression, anchored with ^ and $ — one that does not compile is rejected when the field is written.\nA rule is the tenant's to set on its own custom fields of type TEXT, TEXTAREA and NUMBER, and is ignored for every other field type. It is matched against the whole captured value when a form value is written, as the rule reads at that moment; an empty value is never matched, so clearing stays possible — demanding a value is what a placement's required is for. It never applies to a SECRET field, whose captures are stored as service order secrets rather than as form values. An empty string when the field has no rule — and always empty on a platform field: what the platform checks natively, such as the IMEI checksum on the IMEI field, is not expressed here."},"note":{"type":"string","description":"Guidance written by the tenant and shown under the input at intake. It is plain text, in which clients render URLs as links. An empty string when the field has no note, and always empty on a platform field."},"archived":{"type":"boolean","description":"An archived field is kept for the service orders that already captured it, but it cannot be placed on a form any more. Only SERVICE_CONFIG may archive a field, and a platform field is never archived."},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"},"lastModifiedAt":{"type":"string","format":"date-time"},"lastModifiedBy":{"type":"string"}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"ServiceFormFieldTypeENUM":{"title":"ServiceFormFieldTypeENUM","description":"The data type of a service order form field. It decides how the field is rendered at intake and how the captured value is validated.\nTEXT: single-line text. TEXTAREA: multi-line text. NUMBER: a number. BOOLEAN: true or false. DATE: an ISO 8601 date. SELECT: one of the values listed in the field's selectOptions. MULTI_SELECT: several of the values listed in the field's selectOptions. SECRET: a short sensitive text such as a device passcode.\nSECRET always implies sensitive, and what is captured for a SECRET field is never kept as a form value: it is stored as a service order secret, which holds the value encrypted, is listed by its label alone under the service order's secrets, and can only be read through the secrets reveal endpoint. Secrets are deleted when the service order reaches a terminal state.\nWhat is captured for a MULTI_SELECT field is a list rather than a single answer, and is sent and returned in the form value's values rather than in its value.\nThe field type is immutable after the field has been created — create a new field instead of changing it.","enum":["TEXT","TEXTAREA","NUMBER","BOOLEAN","DATE","SELECT","MULTI_SELECT","SECRET"],"type":"string"},"ServiceFormFieldSystemKindENUM":{"title":"ServiceFormFieldSystemKindENUM","description":"Marks a service order form field as a platform field: a well-known Flow concept, so clients and integrations can recognise the field without matching on its label.\nSERIAL_NUMBER: the serial number of the device. IMEI: the IMEI of a mobile device. PASSCODE: the passcode or unlock code of the device — it is of the field type SECRET and is therefore always sensitive. ACCESSORIES: the accessories handed in with the device, written as free text. LOCATION_LABEL: where the device is physically stored while it is in the workshop. ISSUE_REPRODUCED: whether the reported issue could be reproduced. INTERNAL_NOTE: a note that is never shown to the customer. PRODUCT: the product the unit in for service is. PRIORITY: how urgent the work is, one of the four values of PriorityENUM.\nA platform field is already in every tenant's field library, ready to be used. It belongs to the platform: the platform labels it — the label comes back localized to the reader's language, the way the platform localizes everywhere else — and the tenant can neither create, relabel nor archive one, nor change its validation or its sensitivity. Its whole definition — type, sensitivity and what it is checked against — is fixed by the platform and does not change, so a condition, a filter or an integration built against a platform field keeps working. No platform field carries selectOptions: what a tenant would put in such a list is the tenant's own, so a platform field is free text, a number, a boolean, a secret or, for PRIORITY, one of the four PriorityENUM values its kind names, and selectOptions is always empty on one. In every other respect a platform field is an ordinary field: it stands in the field list with a uid of its own, and it is placed on a form exactly like any other field, except that PRIORITY is never marked required.\nPRODUCT is a backed field: what is captured for it is written to the service order's own productUid rather than into the form value store, because that is what the case is identified by. It is of field type TEXT and is never sensitive. A PRODUCT capture is the uid of one of the tenant's products, and a uid naming none is refused with a 404, the same answer the service order's own productUid gives — the two are one road, so they refuse alike. A client renders it by its system kind — a product search — rather than as a text box.\nPRIORITY is backed in the same way: what is captured for it is written to the service order's own priority rather than into the form value store, because that is the priority the case carries wherever it is shown and filtered. It is of field type TEXT and is never sensitive. A PRIORITY capture is one of the names of PriorityENUM — HIGHEST, HIGH, LOW or NONE — and any other value is refused with a 400; clearing it stores NONE. A client renders it by its system kind — a picker of the four values — rather than as a text box, and its selectOptions stays empty. It is never a required field: the service order's priority always holds a value, so required would mean nothing, and a form placement that marks it required is refused with a 400. As with every backed field, a PRIORITY capture wins over priority sent in the same request, and a PRIORITY placement the write hides — hidden on the create, or closed by an update's own answers — clears it to NONE in the same write.\nThe estimated price and the max price are not platform fields: they are fields of the service order itself, estimatedPrice and maxPrice, entered at intake beside the coverage.\nA field without a system kind is a field the tenant created itself, and everything about it is the tenant's to set. The schema is nullable: null is the value systemKind carries on such a custom field.\nExtensible — new system kinds may be added, so clients must not fail on a value they do not know. A kind is seeded into every tenant's field library, so a client that lists the library meets every kind the platform has, including ones added after it was built.","enum":["SERIAL_NUMBER","IMEI","PASSCODE","ACCESSORIES","LOCATION_LABEL","ISSUE_REPRODUCED","INTERNAL_NOTE","PRODUCT","PRIORITY",null],"nullable":true,"type":"string"},"ServiceFormFieldUpdateRequestSchema":{"title":"ServiceFormFieldUpdateRequestSchema","description":"An update of a field in the service order form field library. Only the tenant's own custom fields are updated here: a field carrying a system kind is a platform field, and an update or an archiving of one is refused — it belongs to the platform.\nfieldType is immutable and cannot be updated. Editing the label does not change the fieldKey, and does not change the label already snapshotted on existing service orders.\nOnly SERVICE_CONFIG may set sensitive or archived; sensitive can only be set from false to true and can never be turned off again.","type":"object","required":["label"],"properties":{"label":{"type":"string","description":"The label shown for the field at intake."},"sensitive":{"type":"boolean","description":"Flips one way only, from false to true, and only with SERVICE_CONFIG. Always true when the field type is SECRET, and cannot be turned off for such a field. It cannot be turned on for a field that a condition on any form names, because conditions never read sensitive fields."},"selectOptions":{"type":"array","description":"The values a user can pick from when the field type is SELECT or MULTI_SELECT. Ignored for every other field type. An option that a condition on any form points at with its equals cannot be removed while that condition exists.","items":{"type":"string"}},"validation":{"type":"string","description":"The rule captured values are matched against, on top of the check the field type already implies. Send one of the named rules phone and email, or a regular expression, which must be anchored with ^ and $ and must compile — a rule that does not is rejected here.\nThe rule applies to TEXT, TEXTAREA and NUMBER fields and is ignored for every other field type. It is matched against the whole captured value when a form value is written, as the rule reads at that moment; an empty value is never matched, so clearing stays possible — demanding a value is what a placement's required is for. It never applies to a SECRET field, whose captures are stored as service order secrets rather than as form values. Send an empty string to clear the rule."},"note":{"type":"string","description":"Guidance to show under the input at intake, written by the tenant. It is plain text, in which clients render URLs as links. Send an empty string to clear it."},"archived":{"type":"boolean","description":"Set to true to take the field out of use. Only SERVICE_CONFIG may archive a field."}}}},"requestBodies":{"ServiceFormFieldUpdateRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceFormFieldUpdateRequestSchema"}}}}}},"paths":{"/tenants/{tenantUid}/serviceorders/formfields/{serviceFormFieldUid}":{"put":{"summary":"Update service order form field","operationId":"put-serviceorders-formfields","description":"Update a service order form field. Only the tenant's own custom fields are updated here: a field carrying a system kind is a platform field, and an update or an archiving of one is refused — it belongs to the platform.\nThe field type is immutable and cannot be updated. Editing the label leaves the field key alone, and leaves the label already snapshotted on existing service orders alone.\nFields are never deleted — set archived to take a field out of use. An archived field is kept for the service orders that already captured it, but cannot be placed on a form any more.\nOnly SERVICE_CONFIG may archive a field or set sensitive, and sensitive only flips one way, from false to true. A field of type SECRET is always sensitive and cannot be made non-sensitive.\n\nRequired permissions: SERVICE_STORE_CONFIG, SERVICE_CONFIG","responses":{"200":{"$ref":"#/components/responses/ServiceFormFieldResponse"}},"tags":["Service"],"requestBody":{"$ref":"#/components/requestBodies/ServiceFormFieldUpdateRequest"}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flowretail.com/docs/developers/api-documentation/service/update-service-order-form-field.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
