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.

Workflow:

{
  "actionType": "st.syncInbox"
}

Completion:

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

💡 To monitor the Sales Navigator inbox, use the nv.syncInbox action. 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.

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:

{
  "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:

{
  "success": true,
  "result": {
    "messages": [
      {
        "id": "f4d92946-8821-6da6-ff4c-c36f0671292a",
        "type": "st",
        "threadId": "2-abc123...",
        "personUrl": "https://www.linkedin.com/in/person1",
        "sender": "them",
        "text": "Hi! Are you available for a quick chat?",
        "time": "2023-01-02T10:35:00Z"
      },
      {
        "id": "2a1b7f25-daba-5e20-70e9-c6427bb4f660",
        "type": "st",
        "threadId": "2-abc123...",
        "personUrl": "https://www.linkedin.com/in/person1",
        "sender": "us",
        "text": "Sure, let's talk this afternoon.",
        "time": "2023-01-02T10:38: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.
  • personUrl – LinkedIn URL of the other participant.
  • 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.

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 linkedin.messageReceived and linkedin.messageSent 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.