> 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/create-new-service-order-intake-form.md).

# Create new service order intake form

Create a new service order intake form for a service type. Set storeUid to create the form for a single store; leave it out or send an empty string to create a tenant-wide form, which requires SERVICE\_CONFIG. Supply serviceFormUid to make the call idempotent: a repeat with the same serviceFormUid returns the form already created and writes nothing, when that form is one the tenant created at the scope the request names — a tenant-wide form, or a form of the same store. The seeded default form's uid, and a serviceFormUid held by any other form, are refused with a 400, and a malformed uid stays refused. A repeat is answered once the scope the request names is resolved, with the permission that scope needs, and before any other check the create makes, so it never meets the refusal its own record would cause: a retry naming a store the tenant does not hold is refused with a 400, and a tenant-wide retry without SERVICE\_CONFIG with a 403. A store form wins over the tenant form for the same service type, and the tenant form wins over the seeded default form. One active form per level: a service type carries at most one unarchived form per store, and at most one unarchived tenant-wide form. A create at a level another active form already holds is refused with a 409 saying which level is taken — the store already has a form for this service type, or the tenant does. The resolution picks a single form at each level, so a second one would make the answer arbitrary. The seeded default does not occupy the tenant level. A tenant that has only the default still has its tenant level free, and the default goes on existing beside the tenant-wide form that is created — it is the floor the resolution falls back to, not a form standing in the way. Archived forms occupy no level either: they are history, kept for the service orders created from them, so a form created already archived is not checked against a level at all. A level that was free when the client last read it may have been taken since, so a 409 is answered by re-reading and trying again rather than by retrying the same call. Place fields on the form with the placements list; archived fields cannot be placed. A placement can be made conditional with visibleWhen, so that it is shown at intake only while the field it names holds the value it names. That field must be of type BOOLEAN, SELECT or MULTI\_SELECT, not marked sensitive, and placed on the same form at a lower position — and it may itself be conditional, so conditions can be chained down a branch. A form whose condition breaks any of those rules, names an equals the field cannot hold, or closes a cycle is rejected.

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":{"ServiceFormResponse":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceFormResponseSchema"}}}}},"schemas":{"ServiceFormResponseSchema":{"title":"ServiceFormResponseSchema","description":"An intake form: the ordered set of fields that is filled in when a service order of a given service type is created.\nA form belongs either to a single store or to the whole tenant. A store form always wins over the tenant form for the same service type, and the tenant form wins over the seeded default form.\nA tenant-wide form is edited only with SERVICE_CONFIG; a store that needs a different form clones it and edits the copy, which then wins for that store.\nForms are never deleted — archive a form to take it out of use.\nstoreUid is an empty string on a tenant-wide form.","type":"object","required":["serviceFormUid","tenantUid","storeUid","serviceTypeUid","name","archived","placements","createdAt","createdBy","lastModifiedAt","lastModifiedBy"],"properties":{"serviceFormUid":{"$ref":"#/components/schemas/UID"},"tenantUid":{"$ref":"#/components/schemas/UID"},"storeUid":{"$ref":"#/components/schemas/OptionalUID"},"serviceTypeUid":{"$ref":"#/components/schemas/UID"},"name":{"type":"string","description":"The name of the form."},"archived":{"type":"boolean","description":"An archived form is kept for the service orders created from it, but is never resolved for new service orders."},"placements":{"type":"array","description":"The fields on the form, with their position, whether they are required, and the condition that decides whether they are shown.","items":{"$ref":"#/components/schemas/ServiceFormPlacementResponseSchema"}},"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-_]+"},"OptionalUID":{"title":"OptionalUID","type":"string","pattern":"^[A-Za-z0-9-_]*"},"ServiceFormPlacementResponseSchema":{"title":"ServiceFormPlacementResponseSchema","description":"A field placed on an intake form, with the field's render information embedded so the form can be rendered without looking the field up.","type":"object","required":["serviceFormFieldUid","position","required","visibleWhen","fieldKey","label","fieldType","systemKind","sensitive","selectOptions","validation","note"],"properties":{"serviceFormFieldUid":{"$ref":"#/components/schemas/UID"},"position":{"type":"integer","description":"The position of the field on the form. Fields are shown in ascending position order."},"required":{"type":"boolean","description":"Whether the field must have a value before the service order can be created."},"visibleWhen":{"nullable":true,"description":"The condition that decides whether the field is shown at intake, or null when the field is always shown.\nrequired only applies while the placement is visible: a hidden field is never demanded, and a value sent for one is discarded rather than stored.","allOf":[{"$ref":"#/components/schemas/ServiceFormPlacementConditionSchema"}]},"fieldKey":{"type":"string","description":"The stable slug of the field. It never changes."},"label":{"type":"string","description":"The label to show for the field."},"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, whose label is the platform's own, localized to the reader's language; null marks one of the tenant's own custom fields.","allOf":[{"$ref":"#/components/schemas/ServiceFormFieldSystemKindENUM"}]},"sensitive":{"type":"boolean","description":"Whether the captured value is sensitive. Sensitive values are left out of search results, webhooks and exports, and are deleted when the service order reaches a terminal state. A placement of a SECRET field is not filled in with a form value — create a service order secret carrying this serviceFormFieldUid instead."},"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 the captured value is matched against on top of the field type check: one of the named rules phone and email, or an anchored regular expression matched against the whole value. It applies to TEXT, TEXTAREA and NUMBER custom fields and never to an empty value. 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 to show under the input at intake, written by the tenant. It is plain text, in which clients render URLs as links. An empty string when the field has no note — a platform field never has one."}}},"ServiceFormPlacementConditionSchema":{"title":"ServiceFormPlacementConditionSchema","description":"The condition that decides whether a placement is shown at intake. The placement is shown only while the field named here holds the captured value given in equals, and is hidden the rest of the time.\nThe comparison is against the captured value as text: a BOOLEAN answer compares as the strings true and false, a SELECT answer compares against the option that was chosen, and a MULTI_SELECT answer matches when equals is one of the options that were chosen.\nThe field named here must be of type BOOLEAN, SELECT or MULTI_SELECT, must not be marked sensitive, and must be placed on the same form at a lower position than the placement it governs. It may itself be a conditional placement, so conditions can be chained down a branch. A form whose condition names a field of another type, a sensitive field, a field that is not on the form, or a field at the same or a higher position, or whose conditions close a cycle, is rejected when the form is written — as is a condition whose equals is not a value the named field can hold.\nThe schema is nullable: null is what an unconditional placement carries in visibleWhen.","type":"object","nullable":true,"required":["serviceFormFieldUid","equals"],"properties":{"serviceFormFieldUid":{"description":"The field on the same form whose captured value the condition looks at.","type":"string","pattern":"^[A-Za-z0-9-_]+"},"equals":{"type":"string","description":"The captured value the named field must hold for the placement to be shown. It must be a value the field can hold — true or false for a BOOLEAN field, one of its selectOptions for a SELECT or MULTI_SELECT field — and anything else is rejected when the form is written."}}},"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"},"ServiceFormCreateRequestSchema":{"allOf":[{"$ref":"#/components/schemas/ServiceFormUpdateRequestSchema"},{"required":["serviceTypeUid"],"properties":{"serviceFormUid":{"$ref":"#/components/schemas/UID"},"serviceTypeUid":{"$ref":"#/components/schemas/UID"},"storeUid":{"$ref":"#/components/schemas/OptionalUID"}}}],"title":"ServiceFormCreateRequestSchema","description":"A new intake form. Supply serviceFormUid to make the call idempotent: a repeat with the same serviceFormUid returns the form already created and writes nothing, when that form is one the tenant created at the scope the request names — a tenant-wide form, or a form of the same store. The seeded default form's uid, and a serviceFormUid held by any other form, are refused with a 400, and a malformed uid stays refused. A repeat is answered once the scope the request names is resolved, with the permission that scope needs, and before any other check the create makes, so it never meets the refusal its own record would cause: a retry naming a store the tenant does not hold is refused with a 400, and a tenant-wide retry without SERVICE_CONFIG with a 403.\nSet storeUid to create the form for a single store; leave it out or send an empty string to create a tenant-wide form, which requires SERVICE_CONFIG.\nThe service type and the store are set here once and cannot be updated afterwards.","type":"object"},"ServiceFormUpdateRequestSchema":{"title":"ServiceFormUpdateRequestSchema","description":"An update of an intake form. The placements list replaces the fields on the form — a field left out of the list is removed from the form.\nThe store and the service type of a form are set when it is created and cannot be updated.\nA tenant-wide form is edited only with SERVICE_CONFIG; a store that needs a different form clones it and edits the copy instead.\nArchived fields cannot be placed on a form.\nA placement made conditional with visibleWhen must name a field of type BOOLEAN, SELECT or MULTI_SELECT that is not marked sensitive, placed on the same form at a lower position, and its equals must be a value that field can hold. Conditions may be chained down a branch, but a form whose condition breaks any of those rules, or whose conditions close a cycle, is rejected.","type":"object","required":["name","placements"],"properties":{"name":{"type":"string","description":"The name of the form."},"archived":{"type":"boolean","description":"Set to true to take the form out of use. An archived form is never resolved for new service orders."},"placements":{"type":"array","description":"The fields on the form. The list replaces the current placements.","items":{"$ref":"#/components/schemas/ServiceFormPlacementSchema"}}}},"ServiceFormPlacementSchema":{"title":"ServiceFormPlacementSchema","description":"A field placed on an intake form: which field, where it appears, whether it must be filled in, and the condition that decides whether it is shown at all.","type":"object","required":["serviceFormFieldUid","position"],"properties":{"serviceFormFieldUid":{"$ref":"#/components/schemas/UID"},"position":{"type":"integer","description":"The position of the field on the form. Fields are shown in ascending position order."},"required":{"type":"boolean","description":"Whether the field must have a value before the service order can be created. Defaults to false. The server enforces the required set when a service order is created, for orders created through the API as well; on an update it asks only for the required fields the update clears, or turns from hidden to shown with an answer it sends (formValues on the update). A placement of the platform field PRIORITY marked required is refused with a 400: the service order's priority always holds a value."},"visibleWhen":{"nullable":true,"description":"The condition that decides whether the field is shown at intake. Leave it out or send null to have the field shown always.\nA conditional placement's required only applies while the placement is visible: a hidden field is never demanded, and a value sent for one is discarded rather than stored.","allOf":[{"$ref":"#/components/schemas/ServiceFormPlacementConditionSchema"}]}}}},"requestBodies":{"ServiceFormCreateRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceFormCreateRequestSchema"}}}}}},"paths":{"/tenants/{tenantUid}/serviceorders/forms":{"post":{"summary":"Create new service order intake form","operationId":"post-serviceorders-forms","description":"Create a new service order intake form for a service type. Set storeUid to create the form for a single store; leave it out or send an empty string to create a tenant-wide form, which requires SERVICE_CONFIG. Supply serviceFormUid to make the call idempotent: a repeat with the same serviceFormUid returns the form already created and writes nothing, when that form is one the tenant created at the scope the request names — a tenant-wide form, or a form of the same store. The seeded default form's uid, and a serviceFormUid held by any other form, are refused with a 400, and a malformed uid stays refused. A repeat is answered once the scope the request names is resolved, with the permission that scope needs, and before any other check the create makes, so it never meets the refusal its own record would cause: a retry naming a store the tenant does not hold is refused with a 400, and a tenant-wide retry without SERVICE_CONFIG with a 403.\nA store form wins over the tenant form for the same service type, and the tenant form wins over the seeded default form.\nOne active form per level: a service type carries at most one unarchived form per store, and at most one unarchived tenant-wide form. A create at a level another active form already holds is refused with a 409 saying which level is taken — the store already has a form for this service type, or the tenant does. The resolution picks a single form at each level, so a second one would make the answer arbitrary.\nThe seeded default does not occupy the tenant level. A tenant that has only the default still has its tenant level free, and the default goes on existing beside the tenant-wide form that is created — it is the floor the resolution falls back to, not a form standing in the way. Archived forms occupy no level either: they are history, kept for the service orders created from them, so a form created already archived is not checked against a level at all.\nA level that was free when the client last read it may have been taken since, so a 409 is answered by re-reading and trying again rather than by retrying the same call.\nPlace fields on the form with the placements list; archived fields cannot be placed.\nA placement can be made conditional with visibleWhen, so that it is shown at intake only while the field it names holds the value it names. That field must be of type BOOLEAN, SELECT or MULTI_SELECT, not marked sensitive, and placed on the same form at a lower position — and it may itself be conditional, so conditions can be chained down a branch. A form whose condition breaks any of those rules, names an equals the field cannot hold, or closes a cycle is rejected.\n\nRequired permissions: SERVICE_STORE_CONFIG, SERVICE_CONFIG","responses":{"201":{"$ref":"#/components/responses/ServiceFormResponse"}},"tags":["Service"],"requestBody":{"$ref":"#/components/requestBodies/ServiceFormCreateRequest"}}}}}
```


---

# 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/create-new-service-order-intake-form.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.
