Linkwiz API · v1

Endpoint reference

Methods, parameters and response schemas from the downloadable OpenAPI contract.

Download OpenAPI 1.0.0-rc.1. All paths below are relative to https://app.linkwiz.ai/api/v1. Every endpoint requires a bearer key; resource IDs are UUIDs.

Method	Path	Purpose
GET	`/context`	Read the calling key's workspace and permissions
GET	`/workspace`	Read the bound workspace
GET	`/reports`	List workspace reports
POST	`/reports`	Create a report and queue supplied profiles
GET	`/reports/{report_id}`	Read one report
GET	`/reports/{report_id}/profiles`	List active personal profile attachments
GET	`/reports/{report_id}/scans/{scan_run_id}`	Read scan status and counts
POST	`/reports/{report_id}/profile-imports`	Validate or add people to an existing report
GET	`/reports/{report_id}/profile-imports/{import_id}`	Recover a saved import receipt

Pagination and responses

Successful responses contain data and request_id. List responses also contain page.next_cursor; stop when it is null. Pass the returned cursor unchanged with the same endpoint and filters. Lists default to 50 items, up to 100. Report lists exclude archived reports unless include_archived=true.

Report reads return company information, profile counts, analysis availability and report URLs. Profile reads return the roster, names, titles, headlines, LinkedIn URLs and analysis availability. Detailed scores, recommendations, individual posts, charts and exports remain in the report UI; this release does not expose them as API resources.

GET`/context`

Read the calling key's workspace and permissions

Required permissions: workspace:read.

Response codes and schemas

HTTP 200

Success. Cache-Control: no-store; X-Request-ID matches request_id.

getContext 200 schema

{
  "$ref": "#/components/schemas/ContextResponse"
}

HTTP 400

JSON error. No token, raw database error or submitted value is echoed.

getContext 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

JSON error. No token, raw database error or submitted value is echoed.

getContext 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

JSON error. No token, raw database error or submitted value is echoed.

getContext 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

JSON error. No token, raw database error or submitted value is echoed.

getContext 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

JSON error. No token, raw database error or submitted value is echoed.

getContext 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

JSON error. No token, raw database error or submitted value is echoed.

getContext 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

JSON error. No token, raw database error or submitted value is echoed.

getContext 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/workspace`

Read the bound workspace

Required permissions: workspace:read.

Response codes and schemas

HTTP 200

Success. Cache-Control: no-store; X-Request-ID matches request_id.

getWorkspace 200 schema

{
  "$ref": "#/components/schemas/WorkspaceResponse"
}

HTTP 400

JSON error. No token, raw database error or submitted value is echoed.

getWorkspace 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

JSON error. No token, raw database error or submitted value is echoed.

getWorkspace 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

JSON error. No token, raw database error or submitted value is echoed.

getWorkspace 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

JSON error. No token, raw database error or submitted value is echoed.

getWorkspace 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

JSON error. No token, raw database error or submitted value is echoed.

getWorkspace 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

JSON error. No token, raw database error or submitted value is echoed.

getWorkspace 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

JSON error. No token, raw database error or submitted value is echoed.

getWorkspace 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/reports`

List workspace reports

Required permissions: reports:read.

Parameter	Location	Required	Value
`limit`	query	No	{"type":"integer","minimum":1,"maximum":100,"default":50}
`cursor`	query	No	Signed opaque cursor bound to workspace, route, filters and the first-page upper watermark. Invalid or changed bindings return 400.
`company_root_domain`	query	No	Hostname or HTTP(S) company URL. Normalized using public and private suffix rules; matches the root and its subdomains.
`include_archived`	query	No	{"type":"boolean","default":false}

Response codes and schemas

HTTP 200

Success. Cache-Control: no-store; X-Request-ID matches request_id.

listReports 200 schema

{
  "$ref": "#/components/schemas/ReportCollection"
}

HTTP 400

JSON error. No token, raw database error or submitted value is echoed.

listReports 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

JSON error. No token, raw database error or submitted value is echoed.

listReports 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

JSON error. No token, raw database error or submitted value is echoed.

listReports 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

JSON error. No token, raw database error or submitted value is echoed.

listReports 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

JSON error. No token, raw database error or submitted value is echoed.

listReports 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

JSON error. No token, raw database error or submitted value is echoed.

listReports 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

JSON error. No token, raw database error or submitted value is echoed.

listReports 503 schema

{
  "$ref": "#/components/schemas/Error"
}

POST`/reports`

Create a report and queue supplied profiles

JSON only; maximum 1 MiB and 100 people. All rows validate before mutation. Unknown fields rejected. Duplicates keep the first occurrence. Empty reports queue no scans; populated reports queue full_profile for people and activity for people plus the company page. No external lookup occurs during creation. Default create permits separate reports for one company. return_existing returns workspace matches across all states without adding supplied people. Separate idempotency keys represent separate intents.

Required permissions: reports:create, reports:read.

Parameter	Location	Required	Value
`Idempotency-Key`	header	Yes	{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"}

JSON request schema

createReport request schema

{
  "$ref": "#/components/schemas/CreateReport"
}

Response codes and schemas

HTTP 200

All matching report references, capped at 100. Follow next_cursor through GET /reports?company_root_domain=...&include_archived=true. Supplied profiles are not added and no scans start.

createReport 200 schema

{
  "$ref": "#/components/schemas/ExistingReportsResponse"
}

HTTP 201

Report and queue records committed atomically. Location points to report GET. Scan completion is asynchronous.

createReport 201 schema

{
  "$ref": "#/components/schemas/CreatedReportResponse"
}

HTTP 400

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 409

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 409 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 413

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 413 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 415

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 415 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 422

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 422 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/reports/{report_id}`

Read one report

Required permissions: reports:read.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}

Response codes and schemas

HTTP 200

Success. Cache-Control: no-store; X-Request-ID matches request_id.

getReport 200 schema

{
  "$ref": "#/components/schemas/ReportResponse"
}

HTTP 400

JSON error. No token, raw database error or submitted value is echoed.

getReport 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

JSON error. No token, raw database error or submitted value is echoed.

getReport 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

JSON error. No token, raw database error or submitted value is echoed.

getReport 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

JSON error. No token, raw database error or submitted value is echoed.

getReport 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

JSON error. No token, raw database error or submitted value is echoed.

getReport 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

JSON error. No token, raw database error or submitted value is echoed.

getReport 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

JSON error. No token, raw database error or submitted value is echoed.

getReport 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/reports/{report_id}/profiles`

List active personal profile attachments

Required permissions: profiles:read.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}
`limit`	query	No	{"type":"integer","minimum":1,"maximum":100,"default":50}
`cursor`	query	No	Signed opaque cursor bound to workspace, route, filters and the first-page upper watermark. Invalid or changed bindings return 400.

Response codes and schemas

HTTP 200

Success. Cache-Control: no-store; X-Request-ID matches request_id.

listReportProfiles 200 schema

{
  "$ref": "#/components/schemas/ProfileCollection"
}

HTTP 400

JSON error. No token, raw database error or submitted value is echoed.

listReportProfiles 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

JSON error. No token, raw database error or submitted value is echoed.

listReportProfiles 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

JSON error. No token, raw database error or submitted value is echoed.

listReportProfiles 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

JSON error. No token, raw database error or submitted value is echoed.

listReportProfiles 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

JSON error. No token, raw database error or submitted value is echoed.

listReportProfiles 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

JSON error. No token, raw database error or submitted value is echoed.

listReportProfiles 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

JSON error. No token, raw database error or submitted value is echoed.

listReportProfiles 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/reports/{report_id}/scans/{scan_run_id}`

Read scan status and counts

Required permissions: reports:read.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}
`scan_run_id`	path	Yes	{"type":"string","format":"uuid"}

Response codes and schemas

HTTP 200

Success. Cache-Control: no-store; X-Request-ID matches request_id.

getReportScan 200 schema

{
  "$ref": "#/components/schemas/ScanResponse"
}

HTTP 400

JSON error. No token, raw database error or submitted value is echoed.

getReportScan 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

JSON error. No token, raw database error or submitted value is echoed.

getReportScan 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

JSON error. No token, raw database error or submitted value is echoed.

getReportScan 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

JSON error. No token, raw database error or submitted value is echoed.

getReportScan 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

JSON error. No token, raw database error or submitted value is echoed.

getReportScan 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

JSON error. No token, raw database error or submitted value is echoed.

getReportScan 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

JSON error. No token, raw database error or submitted value is echoed.

getReportScan 503 schema

{
  "$ref": "#/components/schemas/Error"
}

POST`/reports/{report_id}/profile-imports`

Validate or add people to an existing report

JSON only, 1–100 people, at most 1 MiB. Whole-batch validation. validation_only=true creates no roster changes, receipt, retry reservation or scans, but counts against request admission. Commit rechecks current state. Added/restored people queue full-profile and activity jobs; duplicates queue nothing. Removed people are restored with a note and preserved details/history. Receipts omit supplied names and URLs. Idempotency-Key is required for commits, scoped to workspace, operation and report; same normalized ordered body replays the saved receipt for 30 days, different body returns 409. Existing archived reports return 409. Shares configurable write limits with report creation. Default ceilings: 10 requests/key/minute, 50/workspace/minute and 1000 submitted rows/workspace/minute; workspace settings may differ.

Required permissions: reports:read, profiles:add.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}
`validation_only`	query	No	{"type":"boolean","default":false}
`Idempotency-Key`	header	No	Required unless validation_only=true. Use a new key for each intended commit; reuse it only to recover that request.

JSON request schema

importProfiles request schema

{
  "$ref": "#/components/schemas/ProfileImport"
}

Response codes and schemas

HTTP 200

Preview only; state may change before commit.

importProfiles 200 schema

{
  "$ref": "#/components/schemas/ImportValidationResponse"
}

HTTP 201

Import committed or saved receipt replayed. Scan status is a separate read.

importProfiles 201 schema

{
  "$ref": "#/components/schemas/ImportReceiptResponse"
}

HTTP 400

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 409

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 409 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 413

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 413 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 415

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 415 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 422

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 422 schema

{
  "$ref": "#/components/schemas/ImportValidationError"
}

HTTP 429

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/reports/{report_id}/profile-imports/{import_id}`

Recover a saved import receipt

Requires current access; receipt contents are immutable and are not live scan status. Known authorized receipts expire after 30 days (410); wrong report/workspace or unknown receipt returns 404. Shares read limits: 60 requests/key/minute and 300/workspace/minute.

Required permissions: imports:read.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}
`import_id`	path	Yes	{"type":"string","format":"uuid"}

Response codes and schemas

HTTP 200

Saved receipt.

getProfileImport 200 schema

{
  "$ref": "#/components/schemas/ImportReceiptResponse"
}

HTTP 400

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

getProfileImport 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

getProfileImport 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

getProfileImport 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

getProfileImport 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 410

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

getProfileImport 410 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

getProfileImport 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

getProfileImport 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

getProfileImport 503 schema

{
  "$ref": "#/components/schemas/Error"
}

Schema definitions

A $ref points to a definition below and in the OpenAPI download. Expand a definition to see required fields, types and allowed values.

Error

Error schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "error",
    "request_id"
  ],
  "additionalProperties": false
}

Context

Context schema

{
  "type": "object",
  "properties": {
    "key_id": {
      "type": "string",
      "format": "uuid"
    },
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "workspace_id": {
      "type": "string",
      "format": "uuid"
    },
    "scopes": {
      "type": "array",
      "items": {
        "enum": [
          "*",
          "workspace:read",
          "reports:read",
          "profiles:read",
          "reports:create",
          "profiles:add"
        ]
      }
    },
    "limits": {
      "type": "object",
      "properties": {
        "reads_per_minute_per_key": {
          "const": 60
        },
        "reads_per_minute_per_workspace": {
          "const": 300
        },
        "page_size_max": {
          "const": 100
        },
        "writes_per_minute_per_key": {
          "type": "integer",
          "const": 10
        },
        "writes_per_minute_per_workspace": {
          "type": "integer",
          "const": 50
        },
        "submitted_profiles_per_minute_per_workspace": {
          "type": "integer",
          "const": 1000
        },
        "profiles_per_write_max": {
          "type": "integer",
          "const": 100
        }
      },
      "required": [
        "reads_per_minute_per_key",
        "reads_per_minute_per_workspace",
        "page_size_max",
        "writes_per_minute_per_key",
        "writes_per_minute_per_workspace",
        "submitted_profiles_per_minute_per_workspace",
        "profiles_per_write_max"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "key_id",
    "user_id",
    "workspace_id",
    "scopes",
    "limits"
  ],
  "additionalProperties": false
}

Workspace

Workspace schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "status": {
      "const": "active"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "name",
    "slug",
    "status",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

Report

Report schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "workspace_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "supplied_domain": {
          "type": "string"
        },
        "root_domain": {
          "type": [
            "string",
            "null"
          ]
        },
        "linkedin_company_url": {
          "type": "string",
          "format": "uri"
        }
      },
      "required": [
        "name",
        "supplied_domain",
        "root_domain",
        "linkedin_company_url"
      ],
      "additionalProperties": false
    },
    "visibility": {
      "enum": [
        "private",
        "public"
      ]
    },
    "archived": {
      "type": "boolean"
    },
    "analysis_state": {
      "enum": [
        "not_requested",
        "queued",
        "running",
        "available",
        "failed"
      ]
    },
    "profile_count": {
      "type": "integer",
      "minimum": 0
    },
    "analyzed_profile_count": {
      "type": "integer",
      "minimum": 0
    },
    "public_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri"
    },
    "workspace_url": {
      "type": "string",
      "format": "uri"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "workspace_id",
    "name",
    "company",
    "visibility",
    "archived",
    "analysis_state",
    "profile_count",
    "analyzed_profile_count",
    "public_url",
    "workspace_url",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

Profile

Profile schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "report_id": {
      "type": "string",
      "format": "uuid"
    },
    "linkedin_url": {
      "type": "string",
      "format": "uri"
    },
    "name": {
      "type": [
        "string",
        "null"
      ]
    },
    "title": {
      "type": [
        "string",
        "null"
      ]
    },
    "headline": {
      "type": [
        "string",
        "null"
      ]
    },
    "source": {
      "enum": [
        "urls",
        "finder",
        "ops",
        "migration",
        "api_import"
      ]
    },
    "analysis_available": {
      "type": "boolean"
    },
    "added_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "report_id",
    "linkedin_url",
    "name",
    "title",
    "headline",
    "source",
    "analysis_available",
    "added_at"
  ],
  "additionalProperties": false
}

Scan

Scan schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "report_id": {
      "type": "string",
      "format": "uuid"
    },
    "mode": {
      "enum": [
        "full_profile",
        "activity"
      ]
    },
    "status": {
      "enum": [
        "queued",
        "running",
        "completed",
        "partial",
        "failed",
        "inaccessible",
        "cancelled"
      ]
    },
    "counts": {
      "type": "object",
      "properties": {
        "requested": {
          "type": "integer",
          "minimum": 0
        },
        "completed": {
          "type": "integer",
          "minimum": 0
        },
        "warnings": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "requested",
        "completed",
        "warnings",
        "failed"
      ],
      "additionalProperties": false
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "started_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "terminal_reason": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "failed",
        "inaccessible",
        "cancelled",
        null
      ]
    }
  },
  "required": [
    "id",
    "report_id",
    "mode",
    "status",
    "counts",
    "created_at",
    "started_at",
    "completed_at",
    "terminal_reason"
  ],
  "additionalProperties": false
}

ContextResponse

ContextResponse schema

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Context"
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "request_id"
  ],
  "additionalProperties": false
}

WorkspaceResponse

WorkspaceResponse schema

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Workspace"
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "request_id"
  ],
  "additionalProperties": false
}

ReportResponse

ReportResponse schema

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Report"
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "request_id"
  ],
  "additionalProperties": false
}

ProfileResponse

ProfileResponse schema

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Profile"
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "request_id"
  ],
  "additionalProperties": false
}

ScanResponse

ScanResponse schema

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Scan"
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "request_id"
  ],
  "additionalProperties": false
}

ReportCollection

ReportCollection schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Report"
      }
    },
    "page": {
      "type": "object",
      "properties": {
        "next_cursor": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 2048
        }
      },
      "required": [
        "next_cursor"
      ],
      "additionalProperties": false
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "page",
    "request_id"
  ],
  "additionalProperties": false
}

ProfileCollection

ProfileCollection schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Profile"
      }
    },
    "page": {
      "type": "object",
      "properties": {
        "next_cursor": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 2048
        }
      },
      "required": [
        "next_cursor"
      ],
      "additionalProperties": false
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "page",
    "request_id"
  ],
  "additionalProperties": false
}

CreateProfile

CreateProfile schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "linkedin_url"
  ],
  "properties": {
    "linkedin_url": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "headline": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    }
  }
}

CreateReport

CreateReport schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "company",
    "name"
  ],
  "properties": {
    "company": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "domain",
        "linkedin_company_url"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "domain": {
          "type": "string",
          "maxLength": 2048
        },
        "linkedin_company_url": {
          "type": "string",
          "format": "uri",
          "maxLength": 2048
        }
      }
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "visibility": {
      "enum": [
        "private",
        "public"
      ],
      "default": "private"
    },
    "on_existing": {
      "enum": [
        "create",
        "return_existing"
      ],
      "default": "create"
    },
    "profiles": {
      "type": "array",
      "maxItems": 100,
      "default": [],
      "items": {
        "$ref": "#/components/schemas/CreateProfile"
      }
    }
  }
}

CreationScan

CreationScan schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "mode",
    "status",
    "person_count",
    "company_page_count"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "mode": {
      "enum": [
        "full_profile",
        "activity"
      ]
    },
    "status": {
      "const": "queued"
    },
    "person_count": {
      "type": "integer",
      "minimum": 0
    },
    "company_page_count": {
      "type": "integer",
      "minimum": 0
    }
  }
}

CreationRow

CreationRow schema

{
  "oneOf": [
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "row_number",
        "status",
        "profile_id"
      ],
      "properties": {
        "row_number": {
          "type": "integer",
          "minimum": 1
        },
        "status": {
          "const": "added"
        },
        "profile_id": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "row_number",
        "status",
        "first_row_number"
      ],
      "properties": {
        "row_number": {
          "type": "integer",
          "minimum": 1
        },
        "status": {
          "const": "duplicate_in_input"
        },
        "first_row_number": {
          "type": "integer",
          "minimum": 1
        }
      }
    }
  ]
}

CreatedReportResponse

CreatedReportResponse schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "request_id",
    "data"
  ],
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "data": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "outcome",
        "report",
        "scan_requests",
        "profiles"
      ],
      "properties": {
        "outcome": {
          "const": "created"
        },
        "report": {
          "$ref": "#/components/schemas/Report"
        },
        "scan_requests": {
          "type": "array",
          "maxItems": 2,
          "items": {
            "$ref": "#/components/schemas/CreationScan"
          }
        },
        "profiles": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "submitted",
            "added",
            "duplicate_in_input",
            "rows"
          ],
          "properties": {
            "submitted": {
              "type": "integer",
              "minimum": 0
            },
            "added": {
              "type": "integer",
              "minimum": 0
            },
            "duplicate_in_input": {
              "type": "integer",
              "minimum": 0
            },
            "rows": {
              "type": "array",
              "maxItems": 100,
              "items": {
                "$ref": "#/components/schemas/CreationRow"
              }
            }
          }
        }
      }
    }
  }
}

ExistingReportsResponse

ExistingReportsResponse schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "request_id",
    "data"
  ],
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "data": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "outcome",
        "existing_reports",
        "next_cursor"
      ],
      "properties": {
        "outcome": {
          "const": "existing"
        },
        "existing_reports": {
          "type": "array",
          "minItems": 1,
          "maxItems": 100,
          "items": {
            "$ref": "#/components/schemas/Report"
          }
        },
        "next_cursor": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  }
}

ProfileImport

ProfileImport schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "profiles"
  ],
  "properties": {
    "profiles": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateProfile"
      },
      "minItems": 1,
      "maxItems": 100
    }
  }
}

ImportPreviewRow

ImportPreviewRow schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "row_number",
    "status"
  ],
  "properties": {
    "row_number": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "status": {
      "enum": [
        "would_add",
        "would_restore",
        "already_present",
        "duplicate_in_input"
      ]
    },
    "duplicate_of_row": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "const": "previously_removed_profile_restored"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}

ImportRow

ImportRow schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "row_number",
    "status"
  ],
  "properties": {
    "row_number": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "status": {
      "enum": [
        "added",
        "restored",
        "already_present",
        "duplicate_in_input"
      ]
    },
    "duplicate_of_row": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "const": "previously_removed_profile_restored"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "profile_id": {
      "type": "string",
      "format": "uuid"
    },
    "scan_requests": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "scan_run_id",
          "mode"
        ],
        "properties": {
          "scan_run_id": {
            "type": "string",
            "format": "uuid"
          },
          "mode": {
            "enum": [
              "full_profile",
              "activity"
            ]
          }
        }
      },
      "minItems": 2,
      "maxItems": 2
    }
  }
}

ImportScan

ImportScan schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "scan_run_id",
    "mode",
    "status_at_commit",
    "jobs_created",
    "jobs_coalesced"
  ],
  "properties": {
    "scan_run_id": {
      "type": "string",
      "format": "uuid"
    },
    "mode": {
      "enum": [
        "full_profile",
        "activity"
      ]
    },
    "status_at_commit": {
      "enum": [
        "queued",
        "running",
        "completed",
        "partial",
        "failed",
        "cancelled"
      ]
    },
    "jobs_created": {
      "type": "integer",
      "minimum": 0
    },
    "jobs_coalesced": {
      "type": "integer",
      "minimum": 0
    }
  }
}

ImportValidationResponse

ImportValidationResponse schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "request_id",
    "data"
  ],
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "data": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "validation_only",
        "valid",
        "counts",
        "rows"
      ],
      "properties": {
        "validation_only": {
          "const": true
        },
        "valid": {
          "const": true
        },
        "counts": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "submitted",
            "would_add",
            "would_restore",
            "already_present",
            "duplicate_in_input",
            "would_queue_profiles"
          ],
          "properties": {
            "submitted": {
              "type": "integer",
              "minimum": 0
            },
            "would_add": {
              "type": "integer",
              "minimum": 0
            },
            "would_restore": {
              "type": "integer",
              "minimum": 0
            },
            "already_present": {
              "type": "integer",
              "minimum": 0
            },
            "duplicate_in_input": {
              "type": "integer",
              "minimum": 0
            },
            "would_queue_profiles": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "rows": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/ImportPreviewRow"
          },
          "minItems": 1,
          "maxItems": 100
        }
      }
    }
  }
}

ImportReceipt

ImportReceipt schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "report_id",
    "state",
    "counts",
    "rows",
    "scan_requests",
    "created_at",
    "expires_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "report_id": {
      "type": "string",
      "format": "uuid"
    },
    "state": {
      "const": "completed",
      "description": "Import admission is complete. Scan completion is read separately using the returned report and scan IDs."
    },
    "counts": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "submitted",
        "added",
        "restored",
        "already_present",
        "duplicate_in_input",
        "profiles_queued"
      ],
      "properties": {
        "submitted": {
          "type": "integer",
          "minimum": 0
        },
        "added": {
          "type": "integer",
          "minimum": 0
        },
        "restored": {
          "type": "integer",
          "minimum": 0
        },
        "already_present": {
          "type": "integer",
          "minimum": 0
        },
        "duplicate_in_input": {
          "type": "integer",
          "minimum": 0
        },
        "profiles_queued": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "rows": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ImportRow"
      },
      "minItems": 1,
      "maxItems": 100
    },
    "scan_requests": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ImportScan"
      }
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

ImportReceiptResponse

ImportReceiptResponse schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "request_id",
    "data"
  ],
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "data": {
      "$ref": "#/components/schemas/ImportReceipt"
    }
  }
}

ImportValidationError

ImportValidationError schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "request_id",
    "error"
  ],
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "error": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "message",
        "retryable",
        "details"
      ],
      "properties": {
        "code": {
          "const": "import_validation_failed"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "const": false
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "field",
              "code"
            ],
            "properties": {
              "row_number": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100
              },
              "field": {
                "enum": [
                  "profiles",
                  "linkedin_url",
                  "name",
                  "title",
                  "headline"
                ]
              },
              "code": {
                "type": "string"
              }
            }
          },
          "maxItems": 100
        }
      }
    }
  }
}

Endpoint reference

Pagination and responses

GET/context

Read the calling key's workspace and permissions

HTTP 200

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 429

HTTP 500

HTTP 503

GET/workspace

Read the bound workspace

HTTP 200

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 429

HTTP 500

HTTP 503

GET/reports

List workspace reports

HTTP 200

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 429

HTTP 500

HTTP 503

POST/reports

Create a report and queue supplied profiles

HTTP 200

HTTP 201

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 409

HTTP 413

HTTP 415

HTTP 422

HTTP 429

HTTP 500

HTTP 503

GET/reports/{report_id}

Read one report

HTTP 200

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 429

HTTP 500

HTTP 503

GET/reports/{report_id}/profiles

List active personal profile attachments

HTTP 200

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 429

HTTP 500

HTTP 503

GET/reports/{report_id}/scans/{scan_run_id}

Read scan status and counts

HTTP 200

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 429

HTTP 500

HTTP 503

POST/reports/{report_id}/profile-imports

Validate or add people to an existing report

HTTP 200

GET`/context`

GET`/workspace`

GET`/reports`

POST`/reports`

GET`/reports/{report_id}`

GET`/reports/{report_id}/profiles`

GET`/reports/{report_id}/scans/{scan_run_id}`

POST`/reports/{report_id}/profile-imports`

GET`/reports/{report_id}/profile-imports/{import_id}`