Linked APILinked API

Monitoring the inbox

Inbox monitoring lets you track every incoming conversation on an account, instead of syncing people one by one. It involves 2 key steps:

  1. Enabling. Enable inbox sync once per account. From that point on, Linked API watches your whole inbox in the background and captures new messages across all threads.
  2. Polling. After inbox sync is enabled, poll a single endpoint to retrieve captured messages and receive new ones — without syncing each conversation.

💡 Inbox monitoring vs. conversation syncing. st.syncConversation watches one specific person and retrieves that conversation's full history. st.syncInbox watches your entire inbox but only captures messages that arrive after it is enabled. Use conversation syncing when you need the history of specific people; use inbox monitoring when you need to react to any new incoming message.

Enabling

Execute a workflow with the st.syncInbox action (or nv.syncInbox for Sales Navigator). You only need to do this once per account. Standard and Sales Navigator inboxes can both be enabled on the same account; polled messages are tagged with a type so you can tell them apart.

Workflow:

json
{
  "actionType": "st.syncInbox"
}

Completion:

json
{
  "actionType": "st.syncInbox",
  "success": true
}

Enabling only switches monitoring on: the action records the setting and returns. The messages themselves are picked up afterwards by a sync that runs periodically, so the first ones appear on the next sync rather than the moment the action completes.

Note: When that sync finds new messages in a thread – including messages you send yourself – it opens the profile page of the other participant in that thread to resolve their public URL – but only when Linked API does not already know it, so a person is visited once rather than on every message. Those visits are made from your own account, and such a visit is visible to the person whose profile is opened.

Polling

Unlike enabling, you don't execute workflows to poll the inbox. Instead, send a POST request to the following endpoint:

POST https://api.linkedapi.io/inbox/poll

The request body is a single object. All fields are optional:

json
{
  "since": "2023-01-01T00:00:00Z",
  "type": "st",
  "threadId": "2-abc123..."
}
  • since (optional) – timestamp indicating the starting point for retrieving messages. If not provided, all captured messages are returned.
  • type (optional) – enum to filter by inbox type. If omitted, both standard and Sales Navigator messages are returned:
    • st – standard inbox messages only.
    • nv – Sales Navigator inbox messages only.
  • threadId (optional) – restrict the result to a single conversation thread.

If your request is correct, you will receive the following response:

json
{
  "success": true,
  "result": {
    "messages": [
      {
        "id": "f4d92946-8821-6da6-ff4c-c36f0671292a",
        "type": "nv",
        "threadId": "2-abb123...",
        "personUrn": "urn:li:member:987654321",
        "personHashedUrl": "https://www.linkedin.com/in/ACwAA9FmKpQ4T1r7XbNz",
        "personPublicUrl": null,
        "sender": "them",
        "text": "Saw your post on pipeline automation. Can you share more?",
        "time": "2023-01-02T10:42:00Z"
      },
      {
        "id": "2a1b7f25-daba-5e20-70e9-c6427bb4f660",
        "type": "st",
        "threadId": "2-abc123...",
        "personUrn": "urn:li:member:123456789",
        "personHashedUrl": "https://www.linkedin.com/in/ACoAA2DdsSV83B48UDvgO5jPo3Gho0o",
        "personPublicUrl": "https://www.linkedin.com/in/person1",
        "sender": "us",
        "text": "Sure, let's talk this afternoon.",
        "time": "2023-01-02T10:38:00Z"
      },
      {
        "id": "f4d92946-8821-6da6-ff4c-c36f0671292a",
        "type": "st",
        "threadId": "2-abc123...",
        "personUrn": "urn:li:member:123456789",
        "personHashedUrl": "https://www.linkedin.com/in/ACoAA2DdsSV83B48UDvgO5jPo3Gho0o",
        "personPublicUrl": "https://www.linkedin.com/in/person1",
        "sender": "them",
        "text": "Hi! Are you available for a quick chat?",
        "time": "2023-01-02T10:35:00Z"
      }
    ]
  }
}
  • messages – flat array of messages across all threads, ordered newest first.
    • id – unique identifier for the message.
    • type – inbox type the message belongs to (st or nv).
    • threadId – identifier of the conversation thread. Pass it to st.sendMessage / nv.sendMessage to reply directly into the thread.
    • personUrn – URN of the other participant, or null if LinkedIn does not expose it.
    • personHashedUrl – hashed LinkedIn URL of the other participant. This is the form the inbox exposes; every action that takes a person URL accepts it. The standard and Sales Navigator inboxes return different hashed values for the same person, so match people on personUrn rather than on the personUrl string when you need identity across both surfaces.
    • personPublicUrl – public LinkedIn URL of the other participant, or null if it has not been resolved. It can be null on any message, including the first one in a thread.
    • personUrl – deprecated, replaced by personHashedUrl, which carries the same value. Still returned so existing integrations keep working; do not use it in new code.
    • sender – enum indicating who sent the message. Possible values:
      • us – message was sent by you (through the LinkedIn UI or the Linked API).
      • them – message was sent by the other person.
    • text – message text.
    • time – timestamp when the message was sent or received.

💡 Handling personPublicUrl. A person is resolved by the periodic sync, and only when their thread produces a message after monitoring was enabled. The field is therefore null for everyone you have not heard from yet, and some people are never resolvable at all – so always handle null rather than assuming a message carries a public URL. Messages captured before this field existed, and people whose resolution did not succeed, stay null until that person sends another message or Linked API learns their public URL another way, for example through st.openPersonPage. personHashedUrl is always present and is the safe input for follow-up actions.

Recommended flow for integrations:

  1. Leave since empty on the first request to retrieve everything captured so far.
  2. For subsequent requests, pass the timestamp of the most recent message you received as since to fetch only newer messages.
  3. Continue polling with an advancing since. Whenever new messages arrive, update since to the latest message time.

💡 For push-based delivery instead of polling, subscribe to the inbox Webhook Events. They fire for accounts with inbox monitoring enabled and carry the same message fields.

This page provides examples of workflows and their completions. For detailed documentation on constraints, parameters, and possible results of specific actions, always refer to the corresponding action documentation pages.

PreviousWorking with ConversationsNextChecking Connection Status