createMultiImagePost
Creates a multi-image album or gallery for post types with data_type=4. Imports external image URLs into site storage and verifies each photo lands successfully.
Instructions
Create an album group - Create a new portfoliogroup record. Writes live data.
Use when: creating a photo album, gallery, product listing with multiple photos, or any post type with data_type=4. Confirm the target post type's data_type via listPostTypes first - data_type=4 belongs here; 9/20 belongs in createSingleImagePost. For external image URLs, always use the bulk post_image CSV + auto_image_import=1 here - this is the only path that imports externals into site storage. createMultiImagePostPhoto does NOT import and is only suitable for already-hosted-on-site URLs.
Required: user_id, data_id, data_type.
Pre-check before create: BD does NOT enforce uniqueness on group_name, and the public URL slug is derived from it — duplicate names produce a URL collision (unpredictable which resolves). Do a server-side filter-find: listMultiImagePosts property=group_name property_value=<proposed> property_operator==. Zero rows = name free; >=1 = taken. If taken: compare records, not strings - the same real-world record -> do NOT create (reuse via updateMultiImagePost); a different record sharing the name -> retitle to distinguish and re-check. Never create a duplicate under a new name.
Parameter interactions:
data_id+data_type- specify the post type this album belongs to (fromlistPostTypes;data_typemust be4)group_status:0=Hidden,1=Publishedpost_image- comma-separated image URLs imported as child photos at create timeauto_image_import=1- fetches thepost_imageURLs into site storage (required for external sources to survive)
Post-create verification (critical): HTTP 200 does NOT mean every photo imported. After create, call listMultiImagePostPhotos property=group_id&property_value=<new_group_id>&property_operator==; row count must equal CSV count and every row needs non-empty file + image_imported=2 (success; 0 = silent-failure row). Fix failed row: deleteMultiImagePostPhoto, then updateMultiImagePost group_id=<same>&post_image=<replacement>&auto_image_import=1 (appends). Do NOT delete and recreate the album.
See also: updateMultiImagePost (modify existing), createMultiImagePostPhoto (already-hosted URLs only).
Returns: { status: "success", message: {...createdRecord} } - includes the server-assigned group_id.
Which endpoint to use - data_type family decides:
Every post type in data_categories has a data_type field that classifies its family. Call listPostTypes or getPostType to see the data_type of your target post type, then choose:
| Family | Use endpoint |
| Multi-image (albums, galleries, photo-heavy listings - e.g. Classified, Photo Album, Property, Product) |
|
| Single-image video |
|
| Single-image article / event / blog / job / coupon |
|
| Internal admin types (Member Listings, Reviews, Sub Accounts, Specialties, Favorites) - NOT posts | Use the resource-specific endpoint (e.g. |
If you call the wrong create endpoint for a given post type, BD may accept the row but it won't render on the public site correctly.
Category for multi-image posts: multi-image posts do NOT expose post_category like single-image posts do. Album-level categorization is configured differently in BD admin and is not cleanly writable via the create payload. If categorization is needed, add it via a follow-up updateMultiImagePost or BD admin.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data_id | Yes | ||
| user_id | Yes | ||
| data_type | Yes | Classification family - for this endpoint, must be `4` (multi-image). Read from the target post type's `data_type` column via `listPostTypes` / `getPostType`. If the post type's `data_type` is `9` or `20`, use `createSingleImagePost` instead. Do NOT call `listDataTypes` - `data_type` is a classification, not a per-site FK. | |
| post_tags | No | Comma-separated keywords for the album. Free-form strings - not related to the `Tags` resource. | |
| group_desc | No | Album description HTML. Froala body field — see **Rule: Post-body formatting** (structure, `fr-dib fr-fil`/`fr-fir` float + inline `width: 350px`, landscape Pexels images). | |
| group_name | No | ||
| post_image | No | Comma-separated list of image URLs to import as the album's photos (created at upload time as child `MultiImagePostPhoto` records). **LANDSCAPE only — verify each candidate's orientation via `getImageDimensions` per **Rule: Image dimensions** before commit; bare URLs, no `?query`, each must end in `.jpg`/`.jpeg`/`.png` (WebP/GIF/AVIF skipped pre-tool per the same rule) — see **Rule: Image URLs**.** Query strings (`?w=1600`, `?auto=compress`) get baked into imported filenames and 404. Pair with `auto_image_import=1` to fetch externals into site storage. After create, verify every URL landed via `listMultiImagePostPhotos`. `createMultiImagePostPhoto` does NOT import externals and cannot patch a failed row. | |
| auto_geocode | No | Set to `1` to geocode the album's location. Requires the "Pretty URLs with Google Maps" site feature. | |
| group_status | No | 0=Not Published, 1=Published, 3=Pending Approval (rare — set when site admin requires manual moderation before albums go live). | |
| auto_image_import | No | **Auto-import images to site storage.** Set `1` when any external image URL field on this multi-image post holds a URL - BD fetches and saves each image locally. Without the flag, BD stores URLs as-is; images break if source hosts go down. **Recommended default when supplying external image URLs**; omit or set `0` only if user explicitly wants external URL references. Supports JPG/PNG/GIF/WebP/SVG. Processing delay: several minutes per image. |