POST - Committing an Action

---

At a Glance

• POST commits an action or saves state.
• POST sends file data through multipart/form-data.
• POST includes all field values.
• POST does not return a response body.
• The outcome appears in status codes and headers.
• X-* headers direct the client to close a view, refresh content, or navigate.

The POST method commits user actions or saves state on the Air Doctor server.

Typical use cases:

• Appointment request
• Form submit
• Document upload

Unlike PUT and PATCH, which describe or update the current screen, a POST call marks the completion of a transaction.

Trigger Overview

Trigger	Client Action
User submits a form	Call POST with all field values
User attaches files	Call POST with multipart parts
Screen definition requests	Call POST through the endpoint in the action block

POST Lifecycle Overview

[POST Request]
      ↓
[201 or 204 Status]
      ↓
[Process X-* Headers]
      ↓
[Close │ Refresh │ Navigate │ Show Banner]

Request

Send a POST request to the endpoint specified by the action in your screen definition. The request must include the following elements:

All current field values

Similar to a PATCH call, provide the values of each input field on the screen. This action sends a complete snapshot of the user state at the moment of submission. Exclude parameters that do not appear on the screen and do not appear in the URL.

File attachments

For fields that accept files, supply the actual file data in the POST call. Use the multipart/form-data content type and include each file under its corresponding field name. For fields that accept multiple files, include multiple parts with the same name.

Note: A preceding PATCH call may indicate file presence with boolean or integer counts. The POST call transfers the files themselves.

Open API use

when you call the endpoint outside the screen definition, include only the fields defined in the Open API.

Send tokens and context headers (such as X‑Camera, X‑Microphone, X‑Location, X‑Coordinates, and similar headers) in the same format used for PATCH calls. For authentication guidance, see Access Token Handling.

Method Comparison

Method	Purpose	Response Content
PUT	Load a screen	Full screen definition
PATCH	Update the current screen	Incremental updates
POST	Commit an action	Status code and headers only

Response

The response body of a POST call remains empty. The outcome appears in HTTP status codes and headers.

• 201 Created – The request creates a new entity. The server returns a Location header that contains the identifier of the new resource.

• 204 No Content – The request succeeds but does not create a new entity with a public identifier. The response body remains empty.

In addition to the status code, the server uses custom headers to instruct the client on the next action.

Response Headers

The table defines each header, its type, and its description.

Header	Type	Description
X-Close	string	A values of Yes directs the client close the current popup or page. For a full page, the client navigates back in page history.
X-Refresh	string	Controls refresh behavior. Accepted values: None – no refresh; Update – perform an immediate PATCH call; Page – call the original PUT endpoint to reload the page; App – restart the application, typically required when a user changes language or logs in or out.
X-Banner	string	Message to present as a transient notification such as a snackbar.
X-Forward	string	PUT endpoint for navigation to a different page. This value directs the client to a follow-up screen after an operation completes.

For login and logout operations, the server may set or clear the session-token cookie in the response. Unless you handle user access externally, ensure your client respects these cookie updates to keep authentication state in sync.

Summary

Use the POST endpoint to finalize user actions and submit data, including file uploads, to the server. Supply a complete set of field values, attach files as multipart parts, and read the response status and headers to determine the next step. A 201 response indicates a new resource exists and its identifier appears in the Location header. A 204 response indicates success without a new entity. The custom X‑* headers instruct the client to close the current view, reload content, display a message, or navigate to another location.