API reference

Lists your connected accounts. Call it once and store the ids in your tool's configuration: a display name changes when you rename a page, an id never does.

curl https://hello-socials.com/api/v1/accounts \
  -H "Authorization: Bearer hs_live_xxx"

{
  "data": [
    {
      "id": "cmnj4p2z0000abcd",
      "network": "TWITTER",
      "username": "hellowesign",
      "displayName": "HelloWeSign",
      "status": "connected"
    },
    {
      "id": "cmnj53dc0000efgh",
      "network": "LINKEDIN_PAGE",
      "username": "hellowesign",
      "displayName": "HelloWeSign",
      "status": "connected"
    }
  ]
}

status tells you whether an account needs reconnecting before you send it anything: connected, expiring_soon or expired.

Creates a scheduled post: text only, with images, or with one video. X, LinkedIn, Facebook and Threads accept text on its own; Instagram, Pinterest and TikTok require an image or a video. YouTube is not available through the API yet.

curl -X POST https://hello-socials.com/api/v1/posts \
  -H "Authorization: Bearer hs_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Audit trail de signature électronique : retrouver chaque étape d'\''un document.",
    "socialAccountIds": ["cmnj53dc0000efgh"],
    "scheduledAt": "2026-09-04T09:30:00Z",
    "media": [
      { "url": "https://example.com/images/audit-trail.png" }
    ]
  }'

Video to TikTok and an Instagram reel in one call:

curl -X POST https://hello-socials.com/api/v1/posts \
  -H "Authorization: Bearer hs_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Nouvelle fonctionnalité #meetarabic",
    "socialAccountIds": ["<tiktok-account-id>", "<instagram-account-id>"],
    "scheduledAt": "2026-10-20T18:00:00+02:00",
    "media": [
      { "url": "https://example.com/videos/demo.mp4", "type": "video", "coverTimestampMs": 2500 }
    ],
    "postType": "reel",
    "tiktok": { "privacyLevel": "PUBLIC_TO_EVERYONE", "disableComment": false }
  }'

"2026-09-04T09:30:00Z"        ✓
"2026-09-04T11:30:00+02:00"   ✓
"2026-09-04T09:30:00"         ✗ no timezone
"2026-09-04"                  ✗

{
  "error": "Caption exceeds the character limit for at least one target network",
  "details": {
    "accounts": [{ "id": "cmnj4p2z0000abcd", "network": "TWITTER", "limit": 280, "length": 412 }]
  }
}

Returns the state of a post, network by network. Publishing is asynchronous: creation answers PENDING, and the real outcome only exists once the worker has run.

{
  "data": {
    "id": "cmtlg7ca2000004jp",
    "status": "PUBLISHED",
    "scheduledAt": "2026-09-04T09:30:00.000Z",
    "publishedAt": "2026-09-04T09:30:12.000Z",
    "media": [{ "url": "https://…/posts/…/k3J9x.jpg" }],
    "results": [
      {
        "socialAccountId": "cmnj53dc0000efgh",
        "network": "LINKEDIN_PAGE",
        "status": "PUBLISHED",
        "externalId": "urn:li:share:7123456789",
        "error": null
      }
    ]
  }
}