Linkwiz API · v1

Your first API workflow

Create a key, choose a report and add profiles. Scanning follows automatically.

Examples use placeholder credentials and fictitious profiles. Replace them with your own values. In a preview, replace the base URL with the supplied preview URL.

1. Create a key

Sign in as a workspace owner or admin. Open Workspace settings → API access, enter a name and select Create key. Copy the secret from the key table. Store it in your integration’s secret settings, never in a public page or repository.

2. Confirm workspace access

Read context

curl "https://app.linkwiz.ai/api/v1/context" \
  -H "Authorization: Bearer YOUR_API_KEY"

A 200 response identifies the key’s workspace and permissions. Use that workspace for every request; a key cannot switch workspaces by passing another ID.

3. Choose or create a report

List reports

curl "https://app.linkwiz.ai/api/v1/reports?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use a report’s id, or create a new private report:

Create report

curl -X POST "https://app.linkwiz.ai/api/v1/reports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: report:first-001" \
  -H "Content-Type: application/json" \
  --data '{
  "company": {
    "name": "Example Company",
    "domain": "example.com",
    "linkedin_company_url": "https://www.linkedin.com/company/example-company/"
  },
  "name": "Team report",
  "visibility": "private",
  "on_existing": "create",
  "profiles": []
}'

Replace the example company values. A new report returns 201 and data.report.id. This example starts empty and queues no scans. Supplying initial profiles queues both person scan modes and company-page activity.

4. Validate profiles, then import

Validate profiles

curl -X POST "https://app.linkwiz.ai/api/v1/reports/REPORT_ID/profile-imports?validation_only=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "profiles": [
    {
      "linkedin_url": "https://www.linkedin.com/in/alex-example/",
      "name": "Alex Example",
      "title": "Marketing Director"
    },
    {
      "linkedin_url": "https://www.linkedin.com/in/jordan-example/",
      "name": "Jordan Example"
    }
  ]
}'

Replace REPORT_ID in the URL. A successful preview returns proposed outcomes without adding profiles or reserving a retry key. Then commit the same JSON:

Import profiles

curl -X POST "https://app.linkwiz.ai/api/v1/reports/REPORT_ID/profile-imports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: profiles:first-001" \
  -H "Content-Type: application/json" \
  --data '{
  "profiles": [
    {
      "linkedin_url": "https://www.linkedin.com/in/alex-example/",
      "name": "Alex Example",
      "title": "Marketing Director"
    },
    {
      "linkedin_url": "https://www.linkedin.com/in/jordan-example/",
      "name": "Jordan Example"
    }
  ]
}'

Expect 201 with receipt data.id, per-row outcomes and scan_requests. Save the receipt ID and your idempotency key.

5. Read the receipt and scan progress

Retrieve receipt

curl "https://app.linkwiz.ai/api/v1/reports/REPORT_ID/profile-imports/IMPORT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Read one scan run

curl "https://app.linkwiz.ai/api/v1/reports/REPORT_ID/scans/SCAN_RUN_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use each returned scan run ID with its report ID. This reads a specific run, not every report, and does not start another scan. Poll periodically, slowing down between attempts and respecting Retry-After. A completed receipt means the profiles were saved and queued; scan status separately reports queued, running or a final outcome.

6. Read the roster and open the report

Read report profiles

curl "https://app.linkwiz.ai/api/v1/reports/REPORT_ID/profiles?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Read the report’s workspace_url to open the full insights in Linkwiz. The workspace URL requires normal workspace access. A public_url is returned only when public sharing is enabled. Check usage in the API settings page.