Map external records to App9 Post posts

Use a brand-scoped external ID to reconcile CRM campaigns, CMS entries, migrations, and automated publishing jobs.

Developer operationsReviewed 2026-07-153 min readCurrent guidance

Direct answer

Set external_id when creating a post when another system needs a durable business-level reference. App9 Post keeps that value unique within the brand and lets clients filter GET /v1/social-posts by external_id. Continue using Idempotency-Key as well: the external ID identifies the business record, while the idempotency key protects one side-effecting HTTP request from replay.

What this means in practice

Use the documented brand and account boundaries consistently across the scheduler, REST API, SDK, MCP tools, SSE consumers, and webhooks. That makes the same social operation explainable to an operator and reproducible by an integration.

Implementation checklist

Choose an opaque value that is stable in the source system, such as crm-campaign-42 or cms-post-8841.
Namespace values when more than one source writes into the same App9 Post brand.
Send external_id on the initial post creation request and store the returned App9 Post post ID.
Use GET /v1/social-posts?external_id=VALUE when rebuilding mappings or processing asynchronous events.
Use a separate Idempotency-Key for each intended creation attempt and preserve target-level remote IDs for provider reconciliation.

Example request

This example uses a server-side API key and an explicit brand selection. Replace placeholder values and keep credentials out of browser bundles, client logs, and source control.

Shell

curl --request POST \
  --url 'https://postapi.app9.co/v1/social-posts' \
  --header 'Authorization: Bearer APP9_POST_API_KEY' \
  --header 'X-App9-Post-Brand: BRAND_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "external_id": "cms-post-8841",
  "mode": "scheduled",
  "publish_at": "2026-08-01T14:00:00Z",
  "target_account_ids": [
    "wordpress_site_123",
    "linkedin_456"
  ],
  "caption": "A new article is ready.",
  "timezone": "America/New_York"
}'

Open the complete API reference

Operational details

external_id is optional, immutable in the current contract, limited to 255 characters, and unique only within one brand.

A duplicate external_id returns a structured 409 external_id_conflict instead of creating a second post.

The value can appear in App9 Post post resources and creation events, so avoid secrets and unnecessary personal data.

Common mistakes to avoid

Protect intent, tenant boundaries, and provider state.

Do not use a timestamp or random retry token when the source record already has a stable identifier.
Do not treat external_id as a substitute for target remote_post_id or for HTTP idempotency.
Do not reuse a customer-visible identifier across tenants unless each tenant has a separate brand boundary.

Frequently asked questions

Is external_id the same as Idempotency-Key?

No. external_id maps a durable source record to a post. Idempotency-Key deduplicates the processing of one mutation request.

Can two brands use the same external ID?

Yes. Uniqueness is enforced within a brand so independent tenants and environments can use their own identifier spaces.