Social Post

Create a social post with templateInstance

POST/brands/:brand/social-posts

Example URI

{
  "facebook_page": "77a5cdf2-7b87-4806-b36b-c6710bdb06fe",
  "template_instance": "130a3dad-6d5e-4770-82b1-aa95232cfe79",
  "due_at": 1787791594.997,
  "caption": "test"
}

{
  "code": "OK",
  "data": {
    "id": "4fd0ab40-e5de-4f44-9633-417868c3a72f",
    "brand": "76a700de-d94c-4a95-b825-b2f5b72d9a30",
    "created_by": "3fc9443d-d2d2-426c-8aa9-c55f46361214",
    "caption": "test",
    "facebook_page": "77a5cdf2-7b87-4806-b36b-c6710bdb06fe",
    "template_instance": {
      "id": "130a3dad-6d5e-4770-82b1-aa95232cfe79",
      "created_at": 1787792194.038158,
      "html": "<div>fakeTemplateInstance</div>",
      "file": {
        "id": "9a8bbcbc-538b-4acc-b696-2e5545fd7edd",
        "created_at": 1787792194.959831,
        "updated_at": 1787792194.959831,
        "deleted_at": null,
        "created_by": "3fc9443d-d2d2-426c-8aa9-c55f46361214",
        "path": "templates/instances/26a1bae0-a1b2-11f1-811e-f93126d9eb55.png",
        "name": "image.png",
        "public": true,
        "type": "file",
        "url": "https://test.cloudfront.net/templates/instances/26a1bae0-a1b2-11f1-811e-f93126d9eb55.png",
        "preview_url": "https://test.cloudfront.net/templates/instances/26a1bae0-a1b2-11f1-811e-f93126d9eb55.png",
        "mime": "image/png"
      },
      "created_by": "3fc9443d-d2d2-426c-8aa9-c55f46361214",
      "branch": "http://mock-branch-url",
      "updated_at": 1787792194.038158,
      "deleted_at": null,
      "type": "template_instance"
    },
    "post_link": null,
    "failed_at": null,
    "failure": null,
    "media_container_id": null,
    "type": "social_post",
    "created_at": 1787792195.029561,
    "updated_at": 1787792195.029562,
    "deleted_at": null,
    "due_at": 1787791594.997,
    "executed_at": null,
    "owner": {
      "type": "user",
      "username": null,
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "+15585412967",
      "created_at": 1787792194.056663,
      "id": "3fc9443d-d2d2-426c-8aa9-c55f46361214",
      "address_id": null,
      "cover_image_url": null,
      "profile_image_url": null,
      "updated_at": 1787792194.056682,
      "user_status": "Active",
      "profile_image_thumbnail_url": null,
      "cover_image_thumbnail_url": null,
      "email_confirmed": false,
      "timezone": "America/Chicago",
      "user_type": "Agent",
      "deleted_at": null,
      "phone_confirmed": false,
      "is_shadow": null,
      "personal_room": "2de86cdd-9adb-49de-9df3-64c9c65d2282",
      "brand": null,
      "fake_email": null,
      "features": null,
      "last_seen_at": null,
      "email_signature": "This is my signature.",
      "daily_enabled": false,
      "email_quota": 30000,
      "website": null,
      "instagram": null,
      "twitter": null,
      "linkedin": null,
      "youtube": null,
      "facebook": null,
      "designation": null,
      "tiktok": null,
      "mfa_enabled": false,
      "xpressdocs_user_id": null,
      "bio": "This is my bio.",
      "current_time": "7:56 PM - Wednesday Aug 26, 2026",
      "push_allowed": true,
      "agents": null,
      "last_seen_type": null,
      "active_brand": "76a700de-d94c-4a95-b825-b2f5b72d9a30",
      "display_name": "John Doe",
      "abbreviated_display_name": "John",
      "online_state": "Offline",
      "has_password": true
    }
  }
}

Create a social post with asset

POST/brands/:brand/social-posts

Example URI

{
  "facebook_page": "77a5cdf2-7b87-4806-b36b-c6710bdb06fe",
  "asset": "ff9b4669-bdbd-45a4-b4bd-96e01b5d838a",
  "due_at": 1787791595.091,
  "caption": "testAsset"
}

{
  "code": "OK",
  "data": {
    "id": "91d8492a-2146-4455-a6e3-ccc381f110d8",
    "brand": "76a700de-d94c-4a95-b825-b2f5b72d9a30",
    "created_by": "3fc9443d-d2d2-426c-8aa9-c55f46361214",
    "caption": "testAsset",
    "facebook_page": "77a5cdf2-7b87-4806-b36b-c6710bdb06fe",
    "post_link": null,
    "failed_at": null,
    "failure": null,
    "media_container_id": null,
    "type": "social_post",
    "created_at": 1787792195.11873,
    "updated_at": 1787792195.11873,
    "deleted_at": null,
    "due_at": 1787791595.091,
    "executed_at": null
  }
}

Generate an AI caption recommendation

POST/brands/:brand/social-posts/:id/caption

Generates an AI recommendation for an Instagram caption for the social post. This only returns a recommendation; it does not modify the post.

When the post is tied to a listing (resolved from its template instance, or via the optional listing body param) the listing details and a sample of its photos are sent to the model so it can write a caption grounded in the actual property. For posts that are not tied to a listing (e.g. holiday/celebration templates or static assets) the post’s rendered creative image and template metadata are sent instead, so a caption is still generated.

brand (uuid) ID of the brand

id (uuid) ID of the social post

listing (uuid, optional) listing id to use as an override/fallback when the post is not linked to a listing

Example URI