> For the complete documentation index, see [llms.txt](https://apidocs.zerionsoftware.com/doc/iformbuilder-v81/llms.txt)

# Delete Record Media

> DELETE /profiles/{profile_id}/pages/{page_id}/records/{record_id}/media
> 
> 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
> 
> - `202` no element failed and at least one deletion was queued
> - `200` no element failed and nothing was queued (`NO_MEDIA` only, or the queue is disabled)
> - `207` some elements failed and some did not, or the values were cleared but the queue refused the request
> - `400` every element failed, or the body/element names were invalid (nothing changed)
> - `413` more than 200 element names in one request
> - `401` no valid bearer token
> - `403` no record-delete permission on the page, or another profile's `profile_id`
> - `404` invalid `page_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.



## Servers
- https://api.iformbuilder.com/exzact/api/v81/[servername]: https://api.iformbuilder.com/exzact/api/v81/[servername]


## Authentication methods
- Oauth2


## Parameters
### Headers

- **Authorization** (string)
  e.g. Bearer {access_token}


### Path parameters

- **profile_id** (string)
  id of the profile

- **page_id** (number)
  id of the page

- **record_id** (number)
  id of the record



### Body: application/json (array[string])

array[string]

## Responses
### 202
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.

#### Body: application/json (array[object])
- **element_name** (string)
  the element's name as stored on the page

- **status** (string)
  per-element outcome

- **reason** (string)
  present on `DELETE_FAILED` (`MEDIA_NOT_HOSTED_ON_S3`, `URL_OUT_OF_SCOPE`) and on `VALUE_CLEARED` when the deletion queue refused the request (`QUEUE_FAILED`)

- **urls** (array[string])
  present on `DELETE_QUEUED` and `VALUE_CLEARED`; every media url the element held before it was cleared (one for a single-value element, one per file for `multi_photo`)

- **url** (string)
  present only on `DELETE_FAILED`; the first url that caused the refusal


### 200
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).

#### Body: application/json (array[object])
- **element_name** (string)
  the element's name as stored on the page

- **status** (string)
  per-element outcome

- **reason** (string)
  present on `DELETE_FAILED` (`MEDIA_NOT_HOSTED_ON_S3`, `URL_OUT_OF_SCOPE`) and on `VALUE_CLEARED` when the deletion queue refused the request (`QUEUE_FAILED`)

- **urls** (array[string])
  present on `DELETE_QUEUED` and `VALUE_CLEARED`; every media url the element held before it was cleared (one for a single-value element, one per file for `multi_photo`)

- **url** (string)
  present only on `DELETE_FAILED`; the first url that caused the refusal


### 207
Multi-Status - some elements failed and some did not, or the values were cleared but the deletion queue refused the request (`VALUE_CLEARED` with `reason` `QUEUE_FAILED`). Same body shape as `202`; inspect each item's `status`.

#### Body: application/json (array[object])
- **element_name** (string)
  the element's name as stored on the page

- **status** (string)
  per-element outcome

- **reason** (string)
  present on `DELETE_FAILED` (`MEDIA_NOT_HOSTED_ON_S3`, `URL_OUT_OF_SCOPE`) and on `VALUE_CLEARED` when the deletion queue refused the request (`QUEUE_FAILED`)

- **urls** (array[string])
  present on `DELETE_QUEUED` and `VALUE_CLEARED`; every media url the element held before it was cleared (one for a single-value element, one per file for `multi_photo`)

- **url** (string)
  present only on `DELETE_FAILED`; the first url that caused the refusal


### 400
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`).

#### Body: application/json (object)
- **error_message** (string)
  human-readable reason for the failure


### 401
Unauthorized - missing or invalid bearer token.

#### Body: application/json (object)
- **error_message** (string)
  human-readable reason for the failure


### 403
Forbidden - the user cannot delete records on this page, or `profile_id` is not the caller's own profile.

#### Body: application/json (object)
- **error_message** (string)
  human-readable reason for the failure


### 404
Not Found - `page_id` is not a valid page id, the page does not belong to `profile_id`, or `record_id` does not exist on the page.

#### Body: application/json (object)
- **error_message** (string)
  human-readable reason for the failure


### 413
Payload Too Large - more than 200 element names were submitted. Split the batch and retry.

#### Body: application/json (object)
- **error_message** (string)
  human-readable reason for the failure



[Powered by Bump.sh](https://bump.sh)
