POST /v1/partner/files accepts JPEG, PNG and PDF files of up to 10 MB, recognised from their content, and returns an upload_id. You then answer the upload step with that upload_id within 24 hours, before the upload expires.
Last reviewed: 2026-11-04
The upload step itself is described in Questionnaires and schema, and the answer goes into the request described in Submit a consultation.
Upload a file
POST /v1/partner/files with multipart/form-data. Scope: consultations:write.
201 Created:
content_type is the type Hi Doctor detected, not the one you declared.
Which files are accepted?
Files are checked by their content, never by their extension or declared MIME type.- Maximum size: 10 MB per file. Larger files fail with
422 file_too_large. - Images wider or taller than 10,000 pixels, or larger than 25 million pixels in total, fail with
422 image_too_large. - The file name and the declared MIME type are ignored. A renamed file or a wrong MIME type is accepted when its bytes are a JPEG, PNG or PDF, and the response reports the detected
content_type. - A file whose bytes are not recognised as one of these formats fails with
422 unsupported_media. The check reads the PDF signature or opens the image; it is not a full validation of the file, so send files straight from the camera or your PDF generator.
reason_code: photo_quality.
Expiry and use
- An upload is
pendinguntil a consultation uses it, thenattached. Each upload can be attached once. - Pending uploads expire after 24 hours (
expires_at). After that they can no longer be attached to a consultation. Upload close to submission. - An expired, unknown or already attached
upload_idmakes the submission fail with422 upload_unusable. - Pending uploads count towards a storage quota of 2 GB per partner. When it is full, uploads fail with
422 storage_quota_exceeded. Only upload files you are about to submit, and contact Hi Doctor if you reach the quota. - An expired upload stops counting towards the quota at
expires_at, and a periodic cleanup deletes it together with its file. Attached uploads are kept with the consultation.
Use the upload in an answer
Answer the upload step with the scalar shape:Frequently asked questions
Can I upload HEIC or WebP photos from a phone?
No. Only JPEG, PNG and PDF are accepted, recognised from the file’s bytes. Convert other formats to JPEG or PNG before uploading.Does the file extension or MIME type matter?
No. Hi Doctor ignores the file name and the declared type and reports the detected content type in the response.How long do I have to use an upload?
A pending upload expires 24 hours after it is created, at the time given in expires_at. Upload close to submission so the file is still pending when you submit.Can I reuse one upload for two consultations?
No. Each upload can be attached once. Upload the file again for another consultation.What makes a good photo for the doctor?
A well-lit, in-focus image at the camera’s normal resolution. Poor photos are a common reason for an information request with the photo_quality reason code.Are uploads in test mode stored?
Yes, with the test consultation they were sent with, but never in a medical record. The file is checked exactly as in live mode.Next steps
Submit a consultation
Answer the upload step and send the consultation.
Information requests
Answer a doctor’s request for a better photo or a document.
Partner API errors
Upload error codes and how to handle them.