Create an inbox item
File an enquiry, feedback or message into the clinic's inbox, with attachments.
POST /v1/inbox/createPuts a message in front of the clinic's staff — a contact-form enquiry, a feedback score, a document a patient sent you. It is the route behind the enquiry widget, and it is equally useful from a server when your own website collects the enquiry.
It takes multipart/form-data: a JSON payload part, plus any number of
file parts.
Parts
| Part | Type | Required | Description |
|---|---|---|---|
payload | JSON | Yes | The message. Sent either as a plain form field or as a JSON blob part — both are accepted. |
| anything else | file | No | Attachments. The part name does not matter; every non-payload part is treated as one. |
The payload object
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | ENQUIRY, FEEDBACK, EMAIL, SUPPORT, CONTACT, APPOINTMENT_REQUEST, PRESCRIPTION_REQUEST, LAB_RESULT_NOTIFICATION. |
subject | string | No | The line staff see first. |
description | string | No | The body. |
previewText | string | No | A short summary for the list view. |
senderName | string | No | Who it is from. |
senderEmail | string | No | |
senderPhone | string | No | |
addressId | number | No | Which location it belongs to. Defaults to the workspace's primary address when omitted. |
priority | string | No | LOW (default), MEDIUM, HIGH. |
status | string | No | Defaults to UNREAD. |
isStarred | boolean | No | Defaults to false. |
feedbackRating | number | No | For a FEEDBACK item. |
referenceId | number | No | Link it to an appointment or patient record. |
sourceId | string | No | Your own id for the message, for reconciliation. |
metadata | object | No | Arbitrary JSON kept with the item. |
workspaceId is injected from your key — do not send one.
Try it
/v1/inbox/createBody
POST /v1/inbox/create{
"countryCode": "+91"
}https://api.medos.oneUse a dedicated test key, and put your browser's address on its allowlist
A Developer API key authenticates on its own, so it only works from the addresses registered against it — and this page calls from your browser, not your servers. Unless your own public address is on the list you get a 403 naming it, which is the allowlist doing its job. Your browser may also reach us over IPv6 even when your server does not, so the address in the error is often not the one you expected. The key here is kept in memory only and never written to storage, but create a test key for it and deactivate that key when you are done.
Request
curl -sX POST "https://api.medos.one/v1/inbox/create" \
-H "x-api-key: $MEDOS_API_KEY" \
-F 'payload={"type":"ENQUIRY","subject":"Physio availability","description":"Do you have evening slots this week?","senderName":"Asha Nair","senderEmail":"asha@example.com","senderPhone":"+919876543210","priority":"MEDIUM"};type=application/json' \
-F "attachments=@referral-letter.pdf"Response
The created item, with its id, uuid, resolved workspaceId and addressId,
and an entry per stored attachment.
Common failures
| Status | Cause |
|---|---|
400 | payload is required — no payload part was sent. |
400 | payload must be valid JSON — it arrived as a string that does not parse. Check your form encoding, not the object. |
400 | type outside the list above. |
Attachments ride along, they do not upload separately
There is no separate upload step and no object key to manage — send the files in the same request and Medos stores them against the item.
This is a write-only route here
You can file items; reading, replying to and closing them happens in the Medos inbox. If you need to sync inbox state back into your own system, tell us what you need rather than polling for a route that is not exposed.