> 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/list-service-order-intake-forms.md).

# List service order intake forms

List the tenant's service order intake forms, both the tenant-wide forms and the forms belonging to a single store. Filter by service type, or by store — send an empty storeUid to get only the tenant-wide forms. Archived forms are left out unless includeArchived is set. The list carries configured forms only — the forms somebody in the tenant has made. The seeded default is never among them, whatever the filters and includeArchived are set to: it carries no placements, cannot be edited or archived, and occupies no level, so there is nothing about it for a form list to offer. A tenant that has configured no forms of its own therefore lists none. To find the form that actually applies to a store and a service type, use the resolved intake form endpoint instead, which is an intake read and asks for SERVICE\_ORDER. That endpoint does resolve to the seeded default, reporting its level as DEFAULT. Reading them asks for any service permission — SERVICE\_ORDER or SERVICE\_STORE\_CONFIG at the tenant, at an organization or at any one store, or SERVICE\_CONFIG, which is held at the tenant only — because whoever configures the intake forms reads them. A tenant-wide ADMIN grant counts as every permission. A caller holding none of them, a user with no role assignments included, is refused with a 403.

Required permissions: SERVICE\_ORDER, 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":{"ServiceFormListResponse":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServiceFormResponseSchema"}},"paging":{"$ref":"#/components/schemas/Paging"}},"required":["items","paging"]}}}}},"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"},"Paging":{"description":"totalCount The total number of items in the result set.\n\npageSize The number of items per page.\n\npageNumber The current page in the result set.","properties":{"pageNumber":{"type":"integer"},"pageSize":{"type":"integer"},"totalCount":{"type":"integer"}},"required":["totalCount","pageSize","pageNumber"],"title":"Paging","type":"object"},"SortDirectionENUM":{"description":"|ENUM      | Description |\n| ---------------- | ------------ |\n| ASC | Sort in ascending order|\n| DESC | Sort in descending order|\n","enum":["ASC","DESC"],"title":"SortDirectionENUM","type":"string"}},"parameters":{"serviceFormServiceTypeUidQuery":{"name":"serviceTypeUid","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UID"},"description":"Filter by service type"},"serviceFormStoreUidQuery":{"name":"storeUid","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OptionalUID"},"description":"Filter by store. Send an empty string to get only the tenant-wide forms."},"includeArchivedQuery":{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include archived items in the response. Defaults to false."},"pageNumberQuery":{"description":"Reference to a specific page in a result set.","in":"query","name":"pageNumber","required":false,"schema":{"type":"integer"}},"pageSizeQuery":{"description":"The number of items per page in a result set.","in":"query","name":"pageSize","required":false,"schema":{"type":"integer"}},"sortByQuery":{"description":"Defines which field the resource list is sorted by.","in":"query","name":"sortBy","required":false,"schema":{"type":"string"}},"sortDirectionQuery":{"description":"Reference to a sort direction","explode":false,"in":"query","name":"sortDirection","schema":{"$ref":"#/components/schemas/SortDirectionENUM"},"style":"form"}}},"paths":{"/tenants/{tenantUid}/serviceorders/forms":{"get":{"summary":"List service order intake forms","tags":["Service"],"responses":{"200":{"$ref":"#/components/responses/ServiceFormListResponse"}},"operationId":"get-serviceorders-forms","description":"List the tenant's service order intake forms, both the tenant-wide forms and the forms belonging to a single store. Filter by service type, or by store — send an empty storeUid to get only the tenant-wide forms. Archived forms are left out unless includeArchived is set.\nThe list carries configured forms only — the forms somebody in the tenant has made. The seeded default is never among them, whatever the filters and includeArchived are set to: it carries no placements, cannot be edited or archived, and occupies no level, so there is nothing about it for a form list to offer. A tenant that has configured no forms of its own therefore lists none.\nTo find the form that actually applies to a store and a service type, use the resolved intake form endpoint instead, which is an intake read and asks for SERVICE_ORDER. That endpoint does resolve to the seeded default, reporting its level as DEFAULT.\nReading them asks for any service permission — SERVICE_ORDER or SERVICE_STORE_CONFIG at the tenant, at an organization or at any one store, or SERVICE_CONFIG, which is held at the tenant only — because whoever configures the intake forms reads them. A tenant-wide ADMIN grant counts as every permission. A caller holding none of them, a user with no role assignments included, is refused with a 403.\n\nRequired permissions: SERVICE_ORDER, SERVICE_STORE_CONFIG, SERVICE_CONFIG","parameters":[{"$ref":"#/components/parameters/serviceFormServiceTypeUidQuery"},{"$ref":"#/components/parameters/serviceFormStoreUidQuery"},{"$ref":"#/components/parameters/includeArchivedQuery"},{"$ref":"#/components/parameters/pageNumberQuery"},{"$ref":"#/components/parameters/pageSizeQuery"},{"$ref":"#/components/parameters/sortByQuery"},{"$ref":"#/components/parameters/sortDirectionQuery"}]}}}}
```


---

# 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/list-service-order-intake-forms.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.
