Data model
Organizations, profiles, accounts, posts, targets and media, and how they fit together.
Organization
Your team in FeedHorizon. It holds the plan, the members, the API keys, the webhooks and the media library. Everything you create belongs to exactly one organization, and an API key only ever sees its own organization. GET /me shows which organization a key belongs to.
Profile
A brand, a client or a project inside the organization. Accounts, posts and the queue belong to a profile, and each profile has its own time zone.
- Every organization starts with a default profile. It cannot be deleted.
- If you build a product on FeedHorizon, create one profile per customer and store your customer id in
externalId.GET /profiles?externalId=…finds it again. - An API key can be limited to some profiles. It then sees only their accounts and posts.
- Deleting a profile deletes its accounts, posts and queue.
Account
One connected social account, for example a LinkedIn profile or an Instagram business account. You connect it in the dashboard under Connections, or your customer connects it through a connect link. The same social account can be connected to several profiles.
status tells you whether FeedHorizon can post with it:
| Status | Meaning |
|---|---|
active | Ready to post |
needs_reauth | The platform ended the connection, for example because the user revoked it or it expired. Posts to it fail with account_needs_reauth until it is connected again. The account.needs_reauth webhook tells you |
revoked | Reserved for disconnected accounts. Today, disconnecting deletes the account instead, so you will not see this value yet |
Deleting an account removes its stored tokens. Its scheduled posts on this account are deleted with it; posts already published stay on the platform.
Connect link
A link for one platform and one profile that you send to a customer. They open it, sign in at the platform, and the account lands in that profile. No FeedHorizon login is needed. A link is valid for 7 days and works once. See Connect links.
Post
What you want to publish: the text, media, and when. A post belongs to one profile and goes to one or more of its accounts. It is a draft, scheduled for a time, put in the queue, or published right away, see Scheduling.
Target
The post on exactly one account, in targets[] of the post. Each target has its own:
- text, when that account needs a different one (
targets[].content, for example a shorter text for X), - settings for its platform (
targets[].options, for example the Pinterest board or TikTok privacy), - status, and once published,
platformPostIdandplatformUrl, - error, when it failed, with a code, category and who can fix it (see Publishing errors).
The post's status sums up its targets: published when all succeeded, partially_failed when some did, failed when none did. Webhooks arrive per target (post.target.published, post.target.failed) and per post (post.published, post.partial, post.failed).
Media
An image, video or PDF in the organization's media library. Upload it once, then use its id in mediaIds of as many posts as you like, on any profile. A file that a post still uses cannot be deleted. See Media uploads.
Queue slots
Weekly posting times of a profile, such as Monday and Thursday at 09:00 in the profile's time zone. A post created with addToQueue: true takes the next free slot. See The queue.
Ids
Every object has an id with a prefix that says what it is, such as prof_, acc_, post_ or tgt_. The full list is in API basics.