API overview

The API is organized around actions and runs. Submit an action with a bounded input; inspect the run and its output using the returned ID. API paths are versioned under /v1.

Download the OpenAPI specification for the machine-readable HTTP contract.

Base URL and headers

Use the API host configured for your workspace. The examples use $API_URL for that host, without the /v1 suffix. Requests and responses use JSON.

Authorization: Bearer YOUR_SECRET_API_KEY
Content-Type: application/json
Idempotency-Key: a-unique-work-item-001

The idempotency header is required on action submissions. It is not needed for read requests.

Data actions

All 17 actions and the 2 aliases support POST /v1/actions/{action}/run/live and POST /v1/actions/{action}/run/async. The aliases linkedin-search-person and salesnavigator-search-person resolve to person-lookup. Each action's inputs, result limit, and price are specified in features/action-runs/action-runs.feature.yaml (ACTIONS). linkedin-enrich-engager accepts an engager member ID, name, or headline and runs a four-step cascade: Sales Navigator search, progressively broader fallback searches, then a profile fetch by the original member ID. A search result is accepted only when its member number equals the engager's. A fetched profile is returned only when its identity matches the submitted ID; otherwise the run fails with engager_identity_mismatch, no row is returned, no credit is charged, and the submitted and returned identities are recorded for review. Results use one schema: full_name, linkedin_member_id, and match_method are always present, and linkedin_member_number is present whenever the submitted ID decodes to one (always for ACo/ACw IDs); common optional fields are first_name, last_name, headline, summary, location, company_name, job_title, tenure_start, tenure_length, profile_image_url, linkedin_profile_url, linkedin_profile_id, connection_degree, and experiences. Search-only fields are sales_navigator_company_id, sales_navigator_company_url, sales_navigator_profile_url, sales_navigator_profile_id, recently_hired, and recently_promoted; profile-only fields are education, skills, and languages. Unavailable values are omitted. Live mode returns 200 when the run settles before the deadline, otherwise 202; poll the run or configure a signed webhook. Async submissions return 202 unless an idempotent replay is already terminal.

Connect actions together

1. Enrich all profile data with its public handle or LinkedIn URL.
2. Copy output[0].linkedin_profile_identifier into the profile-posts action’s input.identifier.
3. Copy a returned post’s social_id into the comments or reactions action’s input.social_id. Post search returns the same input field.

The source may return a share, ugcPost, or activity social ID. Pass it exactly as returned. These are public LinkedIn resource identifiers. They are distinct from the numeric member ID and activity ID. The API does not return provider account IDs or credentials.

Run management

Run IDs are UUIDs and are scoped to the authenticated workspace. Configure PUT /v1/workspace/webhook with an HTTPS public port-443 URL to receive signed run.completed, run.failed, and run.cancelled events; DELETE removes it.

Each event is sent once. Failed sends (non-2xx, timeout after 5 s) are retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. In the rare case that your endpoint accepted an event but ProfileGlide could not record the acknowledgement, the event is sent again; the run id in the payload identifies repeats.

Workspace and key management

Key management requires an account session. Creating a key returns { id, api_key, prefix, name, created_at }. Listing keys returns { keys: [...] } without secrets.

Common run response

id, action, and status identify the work. output is always an array; enrichment actions still use a one-element array. credits_used is the final customer cost, while credits_reserved is the outstanding reservation. The response also includes timestamps and completeness.

completeness.scope is currently single_page. has_more: true is a source signal, not a continuation cursor. Do not loop the same request expecting subsequent pages.

Response handling

HTTP 202 means the run is still queued or processing. HTTP 200 means the API returned a terminal run; its status can still be failed. Inspect the response body before treating the extraction as successful.

See runs and retries, errors, and the individual action references for complete integration behavior.