Social Post

Create a social post with templateInstance

POST/brands/:brand/social-posts

Example URI

{
  "facebook_page": "625e74af-6c54-4bf5-8db4-ddbedd9c1f59",
  "template_instance": "e6a4395a-104a-48f0-aa5f-abfa083e85bd",
  "due_at": 1783014374.523,
  "caption": "test"
}

{
  "code": "OK",
  "data": {
    "id": "b5681bf2-f01c-4a35-8d89-1746498e1545",
    "brand": "34143167-e1c1-4d15-9027-a15f97110a8d",
    "created_by": "ddf86b9b-0c5f-4ecc-a991-30031f3918c6",
    "caption": "test",
    "facebook_page": "625e74af-6c54-4bf5-8db4-ddbedd9c1f59",
    "template_instance": {
      "id": "e6a4395a-104a-48f0-aa5f-abfa083e85bd",
      "created_at": 1783014973.625282,
      "html": "<div>fakeTemplateInstance</div>",
      "file": {
        "id": "dffeea26-d61a-4722-8511-70708d1add74",
        "created_at": 1783014974.485298,
        "updated_at": 1783014974.485298,
        "deleted_at": null,
        "created_by": "ddf86b9b-0c5f-4ecc-a991-30031f3918c6",
        "path": "templates/instances/51566630-763f-11f1-94b5-7519f45a456b.png",
        "name": "image.png",
        "public": true,
        "type": "file",
        "url": "https://test.cloudfront.net/templates/instances/51566630-763f-11f1-94b5-7519f45a456b.png",
        "preview_url": "https://test.cloudfront.net/templates/instances/51566630-763f-11f1-94b5-7519f45a456b.png",
        "mime": "image/png"
      },
      "created_by": "ddf86b9b-0c5f-4ecc-a991-30031f3918c6",
      "branch": "http://mock-branch-url",
      "updated_at": 1783014973.625282,
      "deleted_at": null,
      "type": "template_instance"
    },
    "post_link": null,
    "failed_at": null,
    "failure": null,
    "media_container_id": null,
    "type": "social_post",
    "created_at": 1783014974.546728,
    "updated_at": 1783014974.546729,
    "deleted_at": null,
    "due_at": 1783014374.523,
    "executed_at": null,
    "owner": {
      "type": "user",
      "username": null,
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "+18598254118",
      "created_at": 1783014973.644084,
      "id": "ddf86b9b-0c5f-4ecc-a991-30031f3918c6",
      "address_id": null,
      "cover_image_url": null,
      "profile_image_url": null,
      "updated_at": 1783014973.644106,
      "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": "219b5144-c21d-4d98-be0c-9737cb6dc48a",
      "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": "12:56 PM - Thursday Jul 02, 2026",
      "push_allowed": true,
      "agents": null,
      "last_seen_type": null,
      "active_brand": "34143167-e1c1-4d15-9027-a15f97110a8d",
      "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": "625e74af-6c54-4bf5-8db4-ddbedd9c1f59",
  "asset": "c7356f09-bb6c-4fd8-8e79-c55ff3814524",
  "due_at": 1783014374.607,
  "caption": "testAsset"
}

{
  "code": "OK",
  "data": {
    "id": "b51ea092-b3d9-4fac-983c-c5d54a90a20d",
    "brand": "34143167-e1c1-4d15-9027-a15f97110a8d",
    "created_by": "ddf86b9b-0c5f-4ecc-a991-30031f3918c6",
    "caption": "testAsset",
    "facebook_page": "625e74af-6c54-4bf5-8db4-ddbedd9c1f59",
    "post_link": null,
    "failed_at": null,
    "failure": null,
    "media_container_id": null,
    "type": "social_post",
    "created_at": 1783014974.633868,
    "updated_at": 1783014974.633868,
    "deleted_at": null,
    "due_at": 1783014374.607,
    "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