Executing workflows

Linked API is built around the concept of workflows. This means that any automation you want to perform (such as sending a connection request, commenting on a post, retrieving company data, etc.) must be executed as a workflow.

For details on how to build workflows, visit the building workflows page.

Executing a workflow consists of 2 key steps:

Starting a workflow and receiving its workflowId, current workflowStatus, and human-readable message.
Periodically checking for the result using the workflowId.

Starting workflows

To start executing a workflow, make a POST request to the following endpoint:

POST https://api.linkedapi.io/workflows

In the request body, include a JSON that describes your workflow, for example:

json

{
  "actionType": "st.checkConnectionStatus",
  "personUrl": "https://www.linkedin.com/in/person1"
}

Upon successful request, you will receive the following response:

json

{
  "success": true,
  "result": {
    "workflowId": "wf-64835e7c-a0gc-40ae-8338-108f02sSe643",
    "workflowStatus": "pending",
    "pendingReason": "queued",
    "message": "This workflow is scheduled and will start after 2 other workflows already scheduled ahead of it."
  }
}

workflowId – unique workflow identifier for checking the result.
workflowStatus – current workflow status. Possible values at start are pending and running.
pendingReason – why the workflow has not started yet. queued means it is waiting its turn behind other work on the same account; outsideWorkingHours means it is parked until the account working hours reopen. It is null once the workflow is no longer pending.
message – human-readable execution message, such as queue position or estimated duration. This value can change while polling.

In case of an unsuccessful request, you will receive the following response:

json

{
  "success": false,
  "error": {
    "type": "linkedApiTokenRequired",
    "message": "'linked-api-token' is missing in request headers."
  }
}

error – either a common error or one of the following specific errors:
- invalidWorkflow – workflow configuration is not valid due to violated action constraints or invalid action parameters: {validation_details}.
- outsideWorkingHours – the account is outside its configured working hours and its off-hours policy is set to reject. Nothing is queued.

Checking for result

Prefer to be notified instead of polling? Register a webhook and Linked API will POST an event to your endpoint when the workflow completes.

After starting your workflow and receiving the workflowId, you need to periodically check the workflow result. To do this, send a GET request to the following endpoint:

GET https://api.linkedapi.io/workflows/{workflowId}

Depending on the workflow execution status, you'll receive one of these results:

Workflow is pending (queued for execution):

json

{
  "success": true,
  "result": {
    "workflowStatus": "pending",
    "pendingReason": "queued",
    "message": "This workflow is scheduled and will start after 2 other workflows already scheduled ahead of it."
  }
}

Workflows are executed sequentially per LinkedIn account. If you submit multiple workflows, the first one starts executing immediately while the others are queued. The pending status means the workflow is waiting in the queue and will start running once the previous workflows complete.

A workflow can also be pending because the account is outside its working hours. In that case pendingReason is outsideWorkingHours and the workflow will not move until the window reopens, which can be the next working day:

json

{
  "success": true,
  "result": {
    "workflowStatus": "pending",
    "pendingReason": "outsideWorkingHours",
    "message": "This workflow is scheduled and will start when the account working hours open at Mon, Aug 10, 09:00 (Europe/Berlin)."
  }
}

Back off your polling in that case rather than retrying every few seconds – the message names the time the window opens.

Workflow is running:

json

{
  "success": true,
  "result": {
    "workflowStatus": "running",
    "pendingReason": null,
    "message": "This workflow usually takes about 30-60 seconds."
  }
}

While a workflow is pending or running, the message field may update between polling requests. For example, a queued workflow can first return a queue-position message and later return an estimated-duration message after it starts running.

Workflow completed successfully:

json

{
  "success": true,
  "result": {
    "workflowStatus": "completed",
    "completion": {
      "actionType": "st.checkConnectionStatus",
      "success": true,
      "data": {
        "connectionStatus": "pending"
      }
    }
  }
}

completion – results of all actions included in this workflow.

Workflow completed with action error:

json

{
  "success": true,
  "result": {
    "workflowStatus": "completed",
    "completion": {
      "actionType": "st.checkConnectionStatus",
      "success": false,
      "error": {
        "type": "limitExceeded",
        "message": "The configured limit for this action category has been exceeded."
      }
    }
  }
}

Workflow failed:

json

{
  "success": true,
  "result": {
    "workflowStatus": "failed",
    "failure": {
      "reason": "linkedinAccountSignedOut",
      "message": "This LinkedIn account has been signed out in our cloud browser."
    }
  }
}

failure – object describing the workflow failure reason:
- linkedinAccountSignedOut – your LinkedIn account has been signed out in our cloud browser. This occasionally happens as LinkedIn may sign out accounts after an extended period. You'll need to visit our platform and reconnect your account.
- languageNotSupported – your LinkedIn account uses a language other than English, which is currently the only supported option. If you encounter this issue, please contact our support. We prioritize adding new languages based on user requests, so your feedback is important.

In case of an unsuccessful request, you'll receive one of the common errors.

Cancelling workflows

Some workflows in Linked API can take a long time to complete. If you decide you no longer need a workflow to finish, you have the option to cancel it.

You can cancel a running or pending workflow directly on our platform. Simply click the three dots menu next to the workflow and select "Cancel".

Alternatively, you can cancel a workflow via API. To do this, you need to make a DELETE request to the following endpoint:

DELETE https://api.linkedapi.io/workflows/{workflowId}

Upon successful cancellation, you will receive the following response:

json

{
  "success": true,
  "result": {
    "cancelled": true
  }
}

In case of an unsuccessful request, you'll receive one of the common errors.

Important notes:

Partial execution. The workflow is cancelled at its current execution point. Any actions that have already been completed cannot be undone. For example, if the workflow has already sent messages or connection requests from your LinkedIn account, these actions will remain executed.
No intermediate data. Once a workflow is cancelled, no data is preserved or returned. You will not receive any intermediate results or partial data that may have been collected before cancellation.

PreviousMaking Requests NextWorking Hours