Delete Record Media

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://apidocs.zerionsoftware.com/doc/iformbuilder-v80/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "iFormBuilder V80 MCP server": {
    "url": "https://apidocs.zerionsoftware.com/doc/iformbuilder-v80/mcp"
  }
}

Close
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.

Headers

  • Authorization string

    e.g. Bearer {access_token}

Path parameters

  • profile_id string Required

    id of the profile

  • page_id number Required

    id of the page

  • record_id number Required

    id of the record

application/json
Body array[string] | array[object] | object Required
One of:

name of an image, signature, sound, drawing or multi_photo element on the page

Not more than 200 elements.

Not more than 200 elements.

Hide attribute Show attribute object
  • element_name string Required

Responses

  • 202 application/json

    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.

    Hide response attributes Show response attributes object
    • element_name string Required

      the element's name as stored on the page

    • status string Required

      per-element outcome

      Values are DELETE_QUEUED, VALUE_CLEARED, NO_MEDIA, or DELETE_FAILED.

    • 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 application/json

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

    Hide response attributes Show response attributes object
    • element_name string Required

      the element's name as stored on the page

    • status string Required

      per-element outcome

      Values are DELETE_QUEUED, VALUE_CLEARED, NO_MEDIA, or DELETE_FAILED.

    • 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 application/json

    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.

    Hide response attributes Show response attributes object
    • element_name string Required

      the element's name as stored on the page

    • status string Required

      per-element outcome

      Values are DELETE_QUEUED, VALUE_CLEARED, NO_MEDIA, or DELETE_FAILED.

    • 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 application/json

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

    One of:

    per-element outcome of a record media DELETE request

    Hide attributes Show attributes object

    per-element outcome of a record media DELETE request

    • element_name string Required

      the element's name as stored on the page

    • status string Required

      per-element outcome

      Values are DELETE_QUEUED, VALUE_CLEARED, NO_MEDIA, or DELETE_FAILED.

    • 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

  • 401 application/json

    Unauthorized - missing or invalid bearer token.

    Hide response attribute Show response attribute object
    • error_message string Required

      human-readable reason for the failure

  • 403 application/json

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

    Hide response attribute Show response attribute object
    • error_message string Required

      human-readable reason for the failure

  • 404 application/json

    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.

    Hide response attribute Show response attribute object
    • error_message string Required

      human-readable reason for the failure

  • 413 application/json

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

    Hide response attribute Show response attribute object
    • error_message string Required

      human-readable reason for the failure

DELETE /profiles/{profile_id}/pages/{page_id}/records/{record_id}/media
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"
]'
Request examples
[
  "photo_1",
  "signature_1"
]
[
  {
    "element_name": "photo_1"
  },
  {
    "element_name": "signature_1"
  }
]
{
  "element_name": "photo_1"
}
Response examples (202)
[
  {
    "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"
  }
]
Response examples (200)
[
  {
    "element_name": "photo_1",
    "status": "NO_MEDIA"
  }
]
Response examples (207)
[
  {
    "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"
  }
]
Response examples (400)
{
  "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"
  }
]
Response examples (401)
{
  "error_message": "Invalid access token"
}
Response examples (403)
{
  "error_message": "User does not have the required permission"
}
Response examples (404)
{
  "error_message": "The requested resource is not found"
}
Response examples (413)
{
  "error_message": "Batch ceiling exceeded (max 200). Send fewer element names per request."
}