ProfileIQ API Documentation

Keyword-only discovery
{
  "limit": 25,
  "postedWithinHours": 24,
  "keywords": ["hiring", "raised", "launching"]
}

Author-headline-only discovery
{
  "limit": 25,
  "postedWithinHours": 168,
  "authorHeadline": ["founder", "ceo"]
}

Keyword + author + region + reactions
{
  "limit": 10,
  "postedWithinHours": 72,
  "minReactions": 25,
  "region": "United States",
  "keywords": ["fundraising", "series a"],
  "authorHeadline": ["founder", "partner"]
}

Any time, custom region
{
  "limit": 50,
  "postedWithinHours": null,
  "minReactions": 0,
  "region": "Dubai",
  "keywords": ["launching"]
}

Validation rules
- limit: 1-100.
- postedWithinHours: null or 1-4320.
- minReactions: 0 or higher.
- region: omit, empty string, or any 2-80 char string.
- keywords: max 10 terms, 1-80 chars each.
- authorHeadline: max 10 terms, 1-80 chars each.
- At least one of keywords or authorHeadline is required.

curl -X POST "https://api.profileiq.reachrd.tech/v1/discover/posts" \
  -H "Authorization: Bearer piq_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 10,
    "postedWithinHours": 24,
    "minReactions": 5,
    "region": "United States",
    "keywords": ["fundraising", "hiring"],
    "authorHeadline": ["founder", "ceo"]
  }'

{
  "data": {
    "feeds": [
      {
        "id": "feed_uuid",
        "platform": "linkedin",
        "linkedin_url": "https://www.linkedin.com/in/example/",
        "display_name": "Example Feed",
        "headline": "Founder",
        "profile_image_url": "https://media.licdn.com/...",
        "status": "active",
        "fetch_status": "active",
        "last_checked_at": "2026-06-05T10:00:00.000Z",
        "next_check_at": "2026-06-05T16:00:00.000Z",
        "tier": "B",
        "schedule_state": "strong_pattern",
        "pattern_confidence": 87
      }
    ]
  },
  "meta": {
    "count": 1
  },
  "error": null
}

{
  "data": {
    "draft": {
      "id": "draft_uuid",
      "platform": "linkedin",
      "status": "ready",
      "total": 2,
      "valid": 2,
      "invalid": 0,
      "rows": [
        {
          "input": "https://www.linkedin.com/in/example-one/",
          "status": "valid",
          "normalizedUrl": "https://www.linkedin.com/in/example-one/",
          "displayName": "Example One"
        }
      ]
    }
  },
  "meta": {},
  "error": null
}

Request line and headers
POST <your receiver URL>
content-type: application/json
user-agent: ProfileIQ-Webhooks/1.0
x-profileiq-timestamp: <unix seconds>
x-profileiq-signature: sha256=<hex digest>
x-profileiq-test: true   # only present on the test ping

Signature
expected = HMAC_SHA256(
  webhook_secret,
  timestamp + "." + raw_request_body
)
Compare with constant-time equality after stripping the "sha256=" prefix.

Body envelope (every event type)
{
  "id": "event_uuid",
  "type": "linkedin.posts.batch" | "test.ping",
  "createdAt": "2026-06-05T10:00:00.000Z",
  "data": { ... }
}

Expected response
- 2xx status within 30 seconds → delivery marked success.
- Non-2xx, network error, or timeout → delivery marked failed and retried with
  exponential backoff up to the configured max attempts.
- Response body is captured (first 1000 chars) and shown on the deliveries page,
  so plain-text error messages help debugging.

Idempotency
- The same event.id can arrive more than once on retries. Persist it (with a
  unique constraint) and treat duplicates as no-ops.
- test.ping events should be verified and acknowledged but never stored as posts.

POST https://example.com/profileiq/webhook
content-type: application/json
user-agent: ProfileIQ-Webhooks/1.0
x-profileiq-timestamp: 1780647200
x-profileiq-signature: sha256=2b7c...e9f1
x-profileiq-test: true   # only present on the test ping

{
  "id": "event_uuid",
  "type": "test.ping",
  "createdAt": "2026-06-05T10:00:00.000Z",
  "data": {
    "test": true,
    "mode": "ping"
  }
}

{
  "id": "event_uuid",
  "type": "linkedin.posts.batch",
  "createdAt": "2026-06-05T10:00:00.000Z",
  "data": {
    "mode": "live",
    "feedId": "feed_uuid",
    "feed": {
      "id": "feed_uuid",
      "platform": "linkedin",
      "sourceUrl": "https://www.linkedin.com/in/example/",
      "externalId": "urn:li:fsd_profile:abc",
      "linkedinUrl": "https://www.linkedin.com/in/example/",
      "linkedinUrn": "urn:li:fsd_profile:abc",
      "displayName": "Example Feed",
      "headline": "Founder at Example",
      "profileImageUrl": "https://media.licdn.com/...",
      "followerCount": 12450,
      "location": "United States",
      "about": "Building Example.",
      "currentCompany": "Example",
      "currentTitle": "Founder",
      "connections": 500,
      "education": [
        {
          "school": "Stanford University",
          "degree": "BS Computer Science",
          "field": "Computer Science",
          "startYear": 2010,
          "endYear": 2014
        }
      ],
      "metadata": {},
      "status": "active",
      "fetchStatus": "active",
      "lastCheckedAt": "2026-06-05T09:45:00.000Z",
      "nextCheckAt": "2026-06-05T10:00:00.000Z",
      "tier": "B",
      "scheduleState": "strong_pattern",
      "patternConfidence": 87,
      "lastPostAt": "2026-06-05T08:30:00.000Z",
      "predictedNextPostAt": "2026-06-06T08:30:00.000Z",
      "driftScore": 0,
      "createdAt": "2026-05-01T10:00:00.000Z",
      "updatedAt": "2026-06-05T10:00:00.000Z"
    },
    "posts": [
      {
        "id": "post_uuid",
        "feedId": "feed_uuid",
        "changeType": "created",
        "platform": "linkedin",
        "post": {
          "urn": "urn:li:activity:123",
          "url": "https://www.linkedin.com/posts/example_activity-123",
          "type": "image",
          "text": "We just raised our seed round...",
          "isRepost": false,
          "isActivity": false,
          "rootShare": true,
          "audience": "PUBLIC"
        },
        "author": {
          "type": "Person",
          "name": "Example Feed",
          "headline": "Founder at Example",
          "profileUrl": "https://www.linkedin.com/in/example/",
          "profileSlug": "example",
          "urn": "urn:li:fsd_profile:abc",
          "followersCount": 12450,
          "avatarUrl": "https://media.licdn.com/...",
          "details": {
            "location": "San Francisco, California, United States"
          }
        },
        "published": {
          "timestamp": 1780647120000,
          "iso": "2026-06-05T08:12:00.000Z",
          "relative": "2h"
        },
        "engagement": {
          "likesCount": 82,
          "commentsCount": 14,
          "sharesCount": 3,
          "comments": [
            {
              "id": "urn:li:comment:(activity:123,456)",
              "text": "Congrats!",
              "author": {
                "name": "Jane Reviewer",
                "profileUrl": "https://www.linkedin.com/in/jane/",
                "headline": "Investor",
                "avatarUrl": "https://media.licdn.com/..."
              },
              "createdAt": "2026-06-05T08:30:00.000Z",
              "likesCount": 3,
              "parentId": null
            }
          ],
          "reactions": [
            {
              "type": "LIKE",
              "actor": {
                "name": "Jane Reviewer",
                "profileUrl": "https://www.linkedin.com/in/jane/",
                "headline": "Investor",
                "avatarUrl": "https://media.licdn.com/..."
              }
            }
          ]
        },
        "permissions": {},
        "content": {
          "mediaType": "image",
          "mediaUrl": "https://media.licdn.com/dms/image/...",
          "article": null,
          "document": null,
          "resharedPost": null,
          "attributes": [
            { "type": "HASHTAG", "value": "fundraising" },
            { "type": "MENTION", "value": "urn:li:fsd_profile:xyz" }
          ]
        },
        "source": {
          "platform": "linkedin",
          "inputUrl": "https://www.linkedin.com/in/example/",
          "profileUrl": "https://www.linkedin.com/in/example/",
          "collector": "profile_posts"
        },
        "createdAt": "2026-06-05T10:00:00.000Z",
        "updatedAt": "2026-06-05T10:00:00.000Z"
      }
    ],
    "count": 1
  }
}

{
  "id": "event_uuid",
  "type": "test.ping",
  "createdAt": "2026-06-05T10:00:00.000Z",
  "data": {
    "test": true,
    "mode": "ping"
  }
}

import crypto from "node:crypto";
import express from "express";

const app = express();

// IMPORTANT: capture the raw body before JSON parsing — the signature is
// computed over the exact bytes ProfileIQ sent.
app.post(
  "/profileiq/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const timestamp = req.header("x-profileiq-timestamp");
    const signatureHeader = req.header("x-profileiq-signature") || "";
    const signature = signatureHeader.replace(/^sha256=/, "");
    const rawBody = req.body.toString("utf8");

    if (!timestamp || !signature) return res.status(400).end();

    // Reject anything older than 5 minutes to stop replay attacks.
    const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
    if (Number.isNaN(ageSeconds) || ageSeconds > 300) return res.status(400).end();

    const expected = crypto
      .createHmac("sha256", process.env.PROFILEIQ_WEBHOOK_SECRET)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");

    const ok =
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
    if (!ok) return res.status(401).end();

    const event = JSON.parse(rawBody);

    // Use event.id for idempotency — retries reuse the same id.
    if (event.type === "test.ping") return res.status(204).end();

    if (event.type === "linkedin.posts.batch") {
      for (const post of event.data.posts) {
        // post.changeType is "created" or "updated"
        // post.id is the ProfileIQ post id, post.post.url is the LinkedIn URL
      }
    }

    return res.status(200).end();
  }
);