> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seleqt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prospects connection status

## GET /api/v1/public/prospects/{prospect_id}/connection-status/

Checks whether a LinkedIn account connected to the workspace is already
connected (1st-degree relationship) with the given prospect on LinkedIn.

This endpoint queries the underlying LinkedIn provider (Unipile) in real time
using the prospect's LinkedIn profile URL and one of the workspace's connected
LinkedIn accounts. It is intended to be used before sending a connection
invitation, so a campaign can decide to skip the invite step when the user is
already connected.

The same endpoint is also exposed under the JWT-protected path
`GET /api/v1/prospects/{prospect_id}/connection-status/` for use from the
in-app client.

* Auth: `X-API-Key`
* Method: `GET`

### Path Parameters

* `prospect_id` (integer, required): ID of the prospect to check.

### Query Parameters

* `account_id` (integer, optional): ID of a specific LinkedIn `ConnectedAccount`
  to use for the check. If omitted, the first active LinkedIn account in the
  current workspace is used.

### Response

```json theme={null}
{
  "success": true,
  "is_connected": true,
  "connection_level": 1,
  "network_distance": "FIRST_DEGREE",
  "checked_with_account_id": 42
}
```

| Field                     | Type            | Description                                                                                                                                                              |
| ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `success`                 | boolean         | Always `true` on a successful response.                                                                                                                                  |
| `is_connected`            | boolean         | `true` when the prospect is a 1st-degree LinkedIn connection of the chosen account.                                                                                      |
| `connection_level`        | integer \| null | Numeric LinkedIn connection degree. `1` = 1st-degree (direct connection), `2` = 2nd-degree, `3` = 3rd-degree. `null` when the relationship is unknown or out of network. |
| `network_distance`        | string \| null  | Raw network distance reported by the provider. Typically one of `FIRST_DEGREE`, `SECOND_DEGREE`, `THIRD_DEGREE`, `OUT_OF_NETWORK`, or `null` if unknown.                 |
| `checked_with_account_id` | integer         | The id of the `ConnectedAccount` actually used to perform the check.                                                                                                     |

### Error Responses

| Status | `error`                                                                | When                                                                                                                      |
| ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `Prospect has no LinkedIn profile URL to check against`                | The prospect has no `linkedin_profile_url` set.                                                                           |
| `400`  | `No active LinkedIn account is connected to this workspace`            | No LinkedIn `ConnectedAccount` with status `OK / SYNC_SUCCESS / CREATION_SUCCESS / RECONNECTED` exists for the workspace. |
| `400`  | `Requested LinkedIn account not found or not active in this workspace` | An `account_id` was supplied but it does not match an active LinkedIn account in the workspace.                           |
| `403`  | `Access denied`                                                        | The prospect belongs to another workspace.                                                                                |
| `404`  | `Prospect not found`                                                   | No prospect exists with the given id.                                                                                     |
| `502`  | `Failed to fetch prospect profile from LinkedIn provider`              | Unipile call failed or returned a non-2xx response.                                                                       |

### Examples

```bash theme={null}
# Default: pick any active LinkedIn account in the workspace
curl -H "X-API-Key: <key>" \
  "https://api.staging.seleqt.ai/api/v1/public/prospects/12345/connection-status/"
```

```bash theme={null}
# Force the check to use a specific connected LinkedIn account
curl -H "X-API-Key: <key>" \
  "https://api.staging.seleqt.ai/api/v1/public/prospects/12345/connection-status/?account_id=42"
```

### Notes

* The endpoint performs a live call to the LinkedIn provider on every request
  and is therefore subject to provider rate limits. It is intended for
  on-demand checks (for example, immediately before launching a campaign or
  scheduling an invite), not for bulk polling.
* "Connected" is defined strictly as a 1st-degree LinkedIn relationship. A
  pending invitation does not count as connected.
* The chosen LinkedIn account is the perspective from which the check is made.
  If a workspace has multiple LinkedIn accounts and the prospect is connected
  to only one of them, you may get different answers depending on which
  account is used — pass `account_id` explicitly when this matters.