Deletes the media held by named elements of a single record: clears each element's stored value on the record and queues the underlying Amazon S3 object for deletion. Use this when one photo, signature, drawing, sound clip or multi-photo set must be removed without deleting the record. The generic record PUT cannot do this: it never touches the blob and cannot clear a multi_photo field at all.
Request body
Send a JSON array of element names, ["photo_1", "signature_1"]. Also accepted: an array of { "element_name": ... } objects, a single { "element_name": ... } object, and either of those wrapped as { "fields": [...] }. Names are trimmed and de-duplicated. A request may name at most 200 elements; 201 or more returns 413 and nothing is changed.
Every named element must exist on the page and be an image, signature, sound, drawing or multi_photo element. Any other element (attachment, third-party file upload, a non-media field, a name not on the page) fails the whole request with 400 naming the element, and no data changes.
What is deleted
The URLs are never supplied by the caller; they are read from what the record holds. Only objects in Amazon S3 are deleted (public https://...amazonaws.com/... URLs and privates3:// URLs) and only when the object key sits under this page's media prefix ({profile_id}/{data_table_name}). Media held in the customer's own storage (Box, Dropbox, Google Drive, OneDrive, SharePoint), on Rackspace Cloud Files, or under another page's prefix is refused per element and the stored value is left exactly as it was. A multi_photo element is all-or-nothing: if any one of its URLs is refused, the whole element is refused.
The stored values are written first, in one statement for the whole record, and only then is the blob deletion queued, so a failed write never leaves a queued deletion behind. The record's modified_by, modified_date and server_modified_date are updated and the page's record version moves so devices pick up the change.
Response
A plain JSON array with one entry per distinct element, in request order. Each entry has element_name and status; urls is added on DELETE_QUEUED and VALUE_CLEARED, and reason plus the single offending url on DELETE_FAILED.
status |
reason |
Meaning |
|---|---|---|
DELETE_QUEUED |
- | Value cleared; every URL in urls was handed to the deletion queue. |
VALUE_CLEARED |
-, QUEUE_FAILED |
Value cleared but the blob was not deleted: the deletion queue is disabled on this server (no reason), or it refused the request (QUEUE_FAILED). Keep urls if you need to clean up or restore. |
NO_MEDIA |
- | The element already held no media. A no-op success, so replaying a request is idempotent. |
DELETE_FAILED |
MEDIA_NOT_HOSTED_ON_S3, URL_OUT_OF_SCOPE |
Refused; nothing changed for this element. url names the first URL that was not an S3 object, or that is not keyed under this page. |
HTTP status
202no element failed and at least one deletion was queued200no element failed and nothing was queued (NO_MEDIAonly, or the queue is disabled)207some elements failed and some did not, or the values were cleared but the queue refused the request400every element failed, or the body/element names were invalid (nothing changed)413more than 200 element names in one request401no valid bearer token403no record-delete permission on the page, or another profile'sprofile_id404invalidpage_id, the page does not belong to the profile, or the record does not exist
Authorization
Standard bearer token. The caller must be allowed to delete records on the page: the same rule as DELETE .../records/{record_id}, including access inherited through a parent form and the standalone Delete Records role. Unlike POST .../media_restore, BASIC users are not denied outright; a BASIC user who may delete records on the page may delete their media.
Recovering deleted media
Deletion of the S3 object is reversible for as long as the bucket's version retention keeps it: pass the urls from this response to POST .../pages/{page_id}/media_restore. Restoring the object does not re-attach it to the record; the element's stored value stays empty. Keep the urls from this response if you may need to restore.
Responses
-
Accepted - every named element was handled and at least one blob deletion was queued (
DELETE_QUEUED). The stored values are already cleared; the S3 objects are removed asynchronously. -
OK - every named element was handled and nothing was queued, either because every element was already empty (
NO_MEDIA) or because the media deletion queue is disabled on this server (VALUE_CLEARED, the value is gone but the blob is not). -
Multi-Status - some elements failed and some did not, or the values were cleared but the deletion queue refused the request (
VALUE_CLEAREDwithreasonQUEUE_FAILED). Same body shape as202; inspect each item'sstatus. -
Bad Request - the body was empty or not a list of element names, an element name is not on the page, an element is not one of the five supported media types (standard error object body naming the element; nothing is changed), or every named element failed (same outcome array as
202). -
Unauthorized - missing or invalid bearer token.
-
Forbidden - the user cannot delete records on this page, or
profile_idis not the caller's own profile. -
Not Found -
page_idis not a valid page id, the page does not belong toprofile_id, orrecord_iddoes not exist on the page. -
Payload Too Large - more than 200 element names were submitted. Split the batch and retry.
curl \
--request DELETE 'https://api.iformbuilder.com/exzact/api/v80/[servername]/profiles/self/pages/{page_id}/records/{record_id}/media' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer {access_token}" \
--data '[
"photo_1",
"signature_1"
]'
[
"photo_1",
"signature_1"
]
[
{
"element_name": "photo_1"
},
{
"element_name": "signature_1"
}
]
{
"element_name": "photo_1"
}
[
{
"element_name": "photo_1",
"status": "DELETE_QUEUED",
"urls": [
"https://zerion-iform-media-example.s3.amazonaws.com/app/67890/_data67890_inspection_form/field_1234.png"
]
},
{
"element_name": "signature_1",
"status": "NO_MEDIA"
}
]
[
{
"element_name": "photo_1",
"status": "NO_MEDIA"
}
]
[
{
"element_name": "photo_1",
"status": "DELETE_QUEUED",
"urls": [
"https://zerion-iform-media-example.s3.amazonaws.com/app/67890/_data67890_inspection_form/field_1234.png"
]
},
{
"element_name": "drawing_1",
"status": "DELETE_FAILED",
"reason": "MEDIA_NOT_HOSTED_ON_S3",
"url": "https://www.dropbox.com/s/abc123/drawing.png"
}
]
{
"error_message": "Element 'attachment_1' does not hold media this endpoint can delete."
}
{
"error_message": "Request body must contain a list of element names whose media should be deleted."
}
[
{
"element_name": "drawing_1",
"status": "DELETE_FAILED",
"reason": "MEDIA_NOT_HOSTED_ON_S3",
"url": "https://www.dropbox.com/s/abc123/drawing.png"
}
]
{
"error_message": "Invalid access token"
}
{
"error_message": "User does not have the required permission"
}
{
"error_message": "The requested resource is not found"
}
{
"error_message": "Batch ceiling exceeded (max 200). Send fewer element names per request."
}