> For the complete documentation index, see [llms.txt](https://docs.osmosworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.osmosworks.com/business-modules/requests-and-applications.md). # Requests and applications This module covers how customers submit requests and how staff manage the resulting applications. ## Request lifecycle A service request has status values: * `DRAFT` — the customer is filling it in. * `PENDING` — submitted and awaiting staff review. * `ACCEPTED` — converted into an application. * `REJECTED` — staff decided not to proceed. ```mermaid stateDiagram-v2 [*] --> DRAFT: Create request DRAFT --> PENDING: Submit PENDING --> ACCEPTED: Staff accept PENDING --> REJECTED: Staff reject ACCEPTED --> [*]: Application created REJECTED --> [*] ``` ### Creating a request A customer calls `POST /api/v1/customer/requests/{serviceId}`. The backend: 1. Verifies the service is published and not archived. 2. Verifies the customer does not already have an open request for this service. 3. Resolves or creates a self party for the customer. 4. Creates a `ServiceRequest` with a generated reference such as `REQ-XXXXXX` and status `DRAFT`. ### Editing a draft request Customers and staff can update answers and documents on a draft request: * `PUT /api/v1/customer/requests/{requestId}/answers/{questionId}` * `PUT /api/v1/customer/requests/{requestId}/documents/{requirementId}` Answers are validated by answer type. Documents must reference a `FileObject` with status `UPLOADED`. ### Submitting a request `POST /api/v1/customer/requests/{requestId}/submit` validates: * All visible required questions have answers. * All visible required requirements have uploaded documents. If validation passes, the request status becomes `PENDING`. ### Staff review Staff can view a pending request and accept or reject it: * `GET /api/v1/staff/requests/{requestId}` * `POST /api/v1/staff/requests/{requestId}/accept` * `POST /api/v1/staff/requests/{requestId}/reject` (requires a rejection reason) Accepting a request creates an application and copies the service snapshot, stages, questions, requirements, and draft answers into application-scoped tables. ## Application lifecycle An application has status values: * `IN_PROGRESS` — active work. * `COMPLETED` — all stages finished. * `CLOSED` — terminated without completion. Application stages have states: * `LOCKED` — not yet reachable. * `CURRENT` — the active stage. * `COMPLETED` — finished. ```mermaid stateDiagram-v2 [*] --> IN_PROGRESS: Request accepted IN_PROGRESS --> COMPLETED: Last stage completed IN_PROGRESS --> CLOSED: Staff close ``` ### Stage lifecycle ```mermaid stateDiagram-v2 [*] --> LOCKED: Application created (snapshots stages) LOCKED --> CURRENT: Previous stage completed & showRule passes (or initial visible stage) state CURRENT { [*] --> CollectingInput: Collect answers & documents CollectingInput --> InvoiceGenerated: If Payment Stage (Invoice created OPEN) InvoiceGenerated --> PaymentSettled: Paystack checkout succeeds (Invoice PAID) } CURRENT --> COMPLETED: Staff completes stage (validates required answers & docs) COMPLETED --> [*]: Unlocks next stage ``` ### Application creation When staff accept a request: 1. An `Application` is created with a snapshot of the service. 2. `ApplicationStage` records are created from the service stages, all initially `LOCKED`. 3. `ApplicationQuestion` and `ApplicationRequirement` records are created from the service questions and requirements. 4. Draft request answers are copied into `ApplicationAnswer` records. 5. The first visible stage is set to `CURRENT`. If it is a payment stage, an invoice is created. ### Editing an application Customers and staff can edit answers, documents, and party details on an editable application: * `PUT /api/v1/customer/applications/{applicationId}/answers/{questionId}` * `PUT /api/v1/staff/applications/{applicationId}/answers/{questionId}` * `PUT /api/v1/customer/applications/{applicationId}/documents/{requirementId}` * `PUT /api/v1/staff/applications/{applicationId}/documents/{requirementId}` * `PUT /api/v1/customer/applications/{applicationId}/party` * `PUT /api/v1/staff/applications/{applicationId}/party` An application is editable unless its status is `COMPLETED` or `CLOSED`. A stage is editable unless it is `COMPLETED` or paid. Party count cannot be changed after a payment has been made (`APPLICATION_PARTY_COUNT_LOCKED`). ### Completing a stage Staff call `POST /api/v1/staff/applications/{applicationId}/stages/{stageId}/complete`. The backend: 1. Verifies the stage is the current stage. 2. Validates required answers and documents for the stage. 3. For payment stages, verifies the linked invoice is `PAID`. 4. Marks the stage `COMPLETED`. 5. Finds the next visible stage and sets it to `CURRENT`. 6. If the next stage is a payment stage, creates its invoice. 7. If there is no next visible stage, marks the application `COMPLETED`. ### Closing an application Staff can close an application that is not locked: `POST /api/v1/staff/applications/{applicationId}/close` ### Audit history Staff can retrieve edit history for an application: `GET /api/v1/staff/applications/{applicationId}/history` ## Visibility and rules Questions, requirements, stages, and charges use rules to decide visibility. The rule evaluator reads answers from a flat map keyed by `request.` and `party.`. A missing or null answer makes every condition false, including negative operators, so stale answers cannot cause something to appear unexpectedly. ## Incomplete requirements and rejected documents * A stage cannot be completed while required questions are unanswered or required documents are missing. * A requirement marked `reviewRequired` must be uploaded; the backend does not yet enforce staff approval before stage completion. **Needs clarification.** ## Payments and add-ons Payment stages block progression until the linked invoice is paid. Charges can be conditional on answers (for example, an express-processing add-on). The price preview endpoint lets staff see the price for a payment stage before completing it. ## Permissions * `request:create`, `request:read` — customer request actions. * `request:review` — staff accept/reject requests. * `application:read`, `application:manage` — staff and customer application actions. --- # 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.osmosworks.com/business-modules/requests-and-applications.md?ask=&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.