Skip to main content
Posts allow businesses to share announcements, offers, events, and updates directly on connected platforms. Once published, your content appears on Google, Facebook, Instagram, and your Store Locator, helping you engage with customers and improve your online presence.For Google: When a business is connected to a Google location (action performed in Partoo app on Partner Connection page), existing Google Posts are automatically imported and kept in sync as Partoo Posts. If the business is later disconnected, the Google Posts published on Google will be deleted from Partoo database.

​
Prerequisites

Before using the Posts API, ensure you have:
  • Active subscription to Posts plan
  • API key with appropriate role (Business Manager, Group Manager, Organization Manager, or Organization Admin)
  • Platform Integrations: Businesses must be connected to target platforms
    • Google My Business
    • Facebook
    • Instagram
    • Store Locator
    • Businesses have a google_location_id connected
    • DIFFUSION feature enabled
If you need help with any of these prerequisites, please contact your Account Manager who can guide you through the process.

​
Understanding Post Types

Different post types serve different purposes and have specific requirements:
  • News Posts
  • Event Posts
  • Offer Posts
News posts are announcements and updates about your business.Required fields:
  • summary: Main content (max 1500 chars for Google, 10000 for Facebook, 2200 for Instagram)
Supported platforms:
  • ✅ Google
  • ✅ Facebook
  • ✅ Instagram (requires at least 1 image)
  • ✅ Store Locator
In API requests, use "post_type": "news" to create news posts.

​
Creating Posts

All roles can create posts for the businesses they have access to. Each business gets its own individual post.
Who can create posts for multiple businesses:
  • Organization Admin & Organization Manager: All businesses in the organization
  • Group Manager: All businesses in their assigned groups
  • Business Manager: Their assigned businesses (can be one or multiple)
About bulk_id: When you create posts for more than 1 business in a single request, the system assigns a shared bulk_id to group them together. However, only Organization Admin and Organization Manager can use the bulk management endpoints to update/delete all posts in a bulk at once.

​
Creating a post for one business

All roles (Business Manager, Group Manager, Organization Manager, Organization Admin) can create posts for individual businesses they have access to.
curl -X POST 'https://api.partoo.co/v2/posts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "business_search": {
      "business__in": ["5409c35a97bbc544d8e26737"]
    },
    "publishers": ["google_my_business", "facebook"],
    "data": {
      "post_type": "news",
      "summary": "We are excited to announce our new summer menu! Come try our fresh seasonal dishes. 🌞"
    }
  }'

​
Creating posts for multiple businesses

Each business gets its own individual post. When targeting more than one business, all posts share a bulk_id for grouping purposes.
  • By Group
  • By Organization
Group Managers, Organization Managers, and Organization Admins can create posts for businesses in specific groups:
curl -X POST 'https://api.partoo.co/v2/posts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "business_search": {
      "group_ids__in": [111, 222]
    },
    "publishers": ["google_my_business"],
    "data": {
      "post_type": "news",
      "summary": "All our locations will be closed on December 25th for the holidays. Happy holidays!"
    }
  }'
What happens:
  • Each business gets its own separate Post record
  • All posts share the same bulk_id (assigned internally)
  • To get the bulk_id, query one of the created posts using its post_id
  • Only ORG_ADMIN/ORG_MANAGER can use bulk management endpoints to update/delete all posts at once

​
Publishing event posts with time constraints

Event posts are perfect for promoting time-specific events at your business locations.
1

Define event details

Prepare all required event information:
  • Event title (max 58 characters)
  • Start and end dates/times
  • Event description (optional)
  • Media files (optional)
2

Create the event post

curl -X POST 'https://api.partoo.co/v2/posts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "business_search": {
      "business__in": ["5409c35a97bbc544d8e26737"]
    },
    "publishers": ["google_my_business"],
    "data": {
      "post_type": "event",
      "title": "Live Jazz Night",
      "summary": "Join us for an evening of jazz with local popular artists. Free entry!",
      "start_at": "2024-12-20T19:00:00Z",
      "end_at": "2024-12-20T23:00:00Z"
    }
  }'
Event posts are only supported on Google. Do not include Facebook, Instagram, or Store Locator as publishers for event posts.
The post will be created with state pending and will transition to live once published. This process is asynchronous and may take a few minutes.

​
Publishing promotional offers with validity periods

Offer posts help you promote special deals, discounts, and limited-time promotions.
1

Prepare offer details

Gather all offer information:
  • Offer title (max 58 characters)
  • Validity period (start and end dates/times)
  • Offer description (optional)
  • Coupon code (optional, max 58 characters)
  • Terms and conditions (optional, max 5000 characters)
2

Create the offer post

curl -X POST 'https://api.partoo.co/v2/posts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "business_search": {
      "business__in": ["5409c35a97bbc544d8e26737"]
    },
    "publishers": ["google_my_business"],
    "data": {
      "post_type": "offer",
      "title": "Summer Sale - 20% Off",
      "summary": "Enjoy 20% off all summer items! Limited time only.",
      "coupon_code": "SUMMER20",
      "offer_terms": "Valid on all summer collection items. Cannot be combined with other offers. Expires August 31st.",
      "start_at": "2024-06-01T00:00:00Z",
      "end_at": "2024-08-31T23:59:59Z"
    }
  }'
Offer posts are only supported on Google. Do not include Facebook, Instagram, or Store Locator as publishers for offer posts.

​
Publishing posts at a specific future time

Scheduled posts allow you to prepare content in advance and have it automatically published at a specific time.
1

Understand scheduling vs validity

It’s important to distinguish between two different time concepts:
  • schedule_time: When the post should be published to the platforms
  • start_at / end_at: The validity period of the post content (for events and offers)
The schedule_time must be at least 2 hours in the future from the current time. You can schedule a news post, event post, or offer post. The schedule_time controls publication, while start_at/end_at control content validity.
2

Create a scheduled post

curl -X POST 'https://api.partoo.co/v2/posts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "business_search": {
      "business__in": ["5409c35a97bbc544d8e26737"]
    },
    "publishers": ["google_my_business", "facebook"],
    "data": {
      "post_type": "news",
      "summary": "Happy New Year! We wish you a prosperous 2026! 🎉",
      "schedule_time": "2025-01-01T00:00:00Z"
    }
  }'
The post will be created with state scheduled and will automatically transition to pending at the scheduled time, then to live once published.
You can update or delete scheduled posts before they’re published. Once they enter the pending state, updates are no longer possible (but deletion still works).

​
Creating drafts requiring approval before publishing

Draft posts allow organization admins to create posts that require validation from Business Managers or Group Managers before being published.
Draft Post Requirements:
  • User must have ORG_ADMIN role
  • Organization must have DRAFT_POST feature enabled
  • Organization must have more than 1 business
  • Local users (Business Managers or Group Managers) must exist to validate drafts
1

Check if you can create drafts

Verify you have permission to create draft posts:
curl -X GET 'https://api.partoo.co/v2/posts/allowed_operations' \
  -H 'Authorization: Bearer YOUR_API_KEY'
2

Create a draft post

Create a post that requires validation before publishing:
curl -X POST 'https://api.partoo.co/v2/posts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "business_search": {
      "group_ids__in": [111, 222]
    },
    "publishers": ["google_my_business", "facebook"],
    "is_draft": true,
    "send_notifications": true,
    "data": {
      "post_type": "news",
      "summary": "Exciting announcement coming soon! Stay tuned.",
      "expiration_time": "2024-12-31T23:59:59Z"
    }
  }'
When send_notifications: true, all Business Managers and Group Managers with access to the businesses will receive an email notification about the draft post requiring validation.
Draft posts must include an expiration_time. If not validated before this time, the draft will expire and cannot be published.
3

Validate and publish draft

Business Managers or Group Managers can validate drafts by updating them:
curl -X PUT 'https://api.partoo.co/v2/posts/POST_ID' \
  -H 'Authorization: Bearer BM_OR_GM_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "summary": "Updated announcement: Grand opening next week!"
  }'
Once a Business Manager or Group Manager updates the draft, it transitions from to_validate to pending and will be published to the selected platforms.

​
Including images in your posts

Images make your posts more engaging and increase visibility on platforms.
1

Understand image requirements

Different platforms have different image requirements:
  • Google My Business
  • Facebook
  • Instagram
  • Store Locator
  • Limit: 1 image
  • Min size: 250 × 250px
  • Max size: 10000 × 10000px
  • Max weight: 5MB
  • Formats: JPEG, JPG, PNG
2

Create post with images

Add images to your posts using the image_url field:
curl -X POST 'https://api.partoo.co/v2/posts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "business_search": {
      "business__in": ["5409c35a97bbc544d8e26737"]
    },
    "publishers": ["google_my_business", "instagram"],
    "data": {
      "post_type": "news",
      "summary": "Check out our brand new storefront!",
      "image_url": "https://example.com/storefront-image.jpg"
    }
  }'
3

Add multiple images

For platforms that support multiple images (Facebook, Instagram), provide an array of URL strings:
curl -X POST 'https://api.partoo.co/v2/posts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "business_search": {
      "business__in": ["5409c35a97bbc544d8e26737"]
    },
    "publishers": ["facebook", "instagram"],
    "data": {
      "post_type": "news",
      "summary": "Our team had an amazing time at the conference!",
      "image_url": [
        "https://example.com/photo1.jpg",
        "https://example.com/photo2.jpg",
        "https://example.com/photo3.jpg"
      ]
    }
  }'
  • Instagram: Requires at least 1 image (posts without images will fail). Supports JPEG/JPG only.
  • Google & Store Locator: Only support 1 image per post
  • Facebook: Supports up to 10 images

​
Managing Existing Bulks

Once you’ve created posts for multiple businesses (which automatically generates a bulk_id internally), Organization Admins and Organization Managers can use bulk management endpoints to search, update, or delete all posts in a bulk at once.
To get the bulk_id, you need to retrieve one of the created posts using its post_id (from the create response). The post object contains the bulk_id field.
Role Restriction: Bulk management endpoints (/posts/bulks, /posts/count_bulk, /posts/delete_bulk, /posts/edit_bulk) are restricted to Organization Admin and Organization Manager roles only.While Group Managers can create posts for multiple businesses (which generates a bulk_id), they cannot use the bulk management endpoints to search, update, or delete those bulks.

​
Finding and tracking posts in a bulk

Use the bulk search endpoint to retrieve all posts in a specific bulk. You can use the bulk_id if you know it, or search by business/group to find your posts.
curl -X GET 'https://api.partoo.co/v2/posts/bulks?bulk_id=12345' \
  -H 'Authorization: Bearer YOUR_API_KEY'
The bulk_id parameter is optional. Without it, /posts/bulks returns the list of all posts in bulk. You can combine bulk_id with other filters like state__in, topic_type, etc. The first post in results will contain the bulk_id field.

​
Getting the total count

Get the total count of posts in a bulk without retrieving all the data:
curl -X GET 'https://api.partoo.co/v2/posts/count_bulk/12345' \
  -H 'Authorization: Bearer YOUR_API_KEY'

​
Modifying content across multiple posts

You can update all posts in a bulk simultaneously, which is useful for correcting errors or updating information.
curl -X POST 'https://api.partoo.co/v2/posts/edit_bulk' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "bulk_id": 12345,
    "post_data": {
      "summary": "UPDATED: Extended hours continue through January 15th!"
    }
  }'
Platform Behavior:
  • Google & Facebook: Updates propagate asynchronously (a few minutes delay)
  • Store Locator: Updates apply instantly
  • Instagram: Cannot be edited once live (API limitation)

​
Removing multiple posts at once

Delete all posts in a bulk when content is no longer relevant or needs to be removed.
curl -X POST 'https://api.partoo.co/v2/posts/delete_bulk' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "bulk_id": 12345
  }'
Deletion Behavior:
  • Published posts transition through pending_deleted (asynchronous, a few minutes)
  • Unpublished posts are deleted immediately
  • Instagram: Only removes Partoo records, not the actual Instagram post (manual deletion required)

​
Platform-Specific Guidelines

Quick reference for key differences between platforms:
  • Google My Business
  • Facebook
  • Instagram
  • Store Locator
Supported Post Types: News, Event, OfferKey Limits:
  • Summary: 1500 characters
  • Title: 58 characters (events/offers)
  • Offer terms: 5000 characters
  • Images: 1 per post
Only platform supporting all three post types (News, Event, Offer).

​
Post Lifecycle and States

Understanding post states helps you track the publishing process and troubleshoot issues:
  • to_validate: draft post awaiting validation from a Business Manager or Group Manager
  • scheduled: scheduled for future publishing at the specified schedule_time
  • pending: queued for publishing
  • live: successfully published
  • to_configure: configuration error
  • error: publisher error
  • pending_deleted: queued for deletion
  • deleted: successfully deleted from platforms and Partoo
  • expired: draft post expired before validation, or post passed its end_at date
  • Draft posts: to_validate → pending (after validation) → live
  • Scheduled posts: scheduled → pending (at schedule time) → live
  • Immediate posts: pending → live (or error/to_configure on failure)
  • Deletions: → pending_deleted → deleted

​
Monitoring Post Progress

State transitions are asynchronous. To monitor post status:Use the search endpoint GET /api/v2/posts with filters like state__in=live or state__in=pending to check if posts are published successfully.
The /state endpoint (GET /api/v2/posts/{post_id}/state) only returns error information for publishers in to_configure state. It does NOT show live, pending, scheduled, or error state posts. Use it only for troubleshooting configuration issues.

​
Troubleshooting Failed Posts

If your post enters to_configure state, use the state diagnostics endpoint to understand what configuration is missing.
The /state endpoint only returns publishers in to_configure state. An empty response {} means no configuration errors were detected (posts may be pending, scheduled, live, or in other error states).
curl -X GET 'https://api.partoo.co/v2/posts/12345/state' \
  -H 'Authorization: Bearer YOUR_API_KEY'
The expected_error_message field contains an error key indicating what configuration is missing (e.g., "publisher_connection_required", "business_is_not_subscribed_to_pm").