> ## Documentation Index > Fetch the complete documentation index at: https://docs.loice.ai/llms.txt > Use this file to discover all available pages before exploring further. # Resolve a company LinkedIn page to structured data > Resolves a company or school LinkedIn page URL (`linkedinUrl`, the only identifier this operation accepts) into a structured company record — industry, size band, headquarters, website, founding year, specialities, social profiles and more — from our own datastore, fetching and parsing the public company page when we have not seen it before. A company we already hold is answered from our records (`cached: true`, same price) even when live fetching is unavailable. A school is answered from our dataset only, because LinkedIn does not serve school pages publicly. Pass `refresh: true` to bypass cached freshness (billed again; not available for a school). The address must be a FULL page URL: a bare slug such as `microsoft` is refused as `invalid-input` (400), as is a person, job, group or post URL. Reasons: `no-such-company` (200, charged — the page states no such company), `invalid-input` (400), `insufficient-credits` (402), `login-required` (422 — a login wall, a school we do not hold, or a numeric id we cannot prove; retrying cannot help) and `unavailable` (503 — the source could not be read). A refusal carries the same `data` body as a success. Fields the source does not state are returned as `null` and are never inferred. The company email is returned only when it is a generic role address on the company's own domain that passed verification and is not on the workspace's or the platform's do-not-contact list; the phone is always null until phone verification is available. Rate limited per workspace (shared with the web app). #### Billing - charged per completed lookup — whether a company was found or not, and whether the answer came from owned data or a live fetch — never when the source could not be read, never for a refusal. The current cost is shown in the app under Settings → Billing and in the live `GET /api/v1/openapi.json`. Calls that end in a system or provider error (HTTP 500) or are rate limited (HTTP 429) are not billed. The `charged` and `pointsCharged` fields of the response state what this call actually consumed. ## OpenAPI ````yaml /openapi.json post /api/v1/company openapi: 3.1.0 info: title: Loice API version: v1 description: >- The Loice API finds and verifies professional contact data. Every capability is exposed here, key-authenticated and rate-limited; the web app is a client of the same platform. **Authentication** — pass your workspace API key on every request (except the API description) as `Authorization: Bearer loice_sk_…`. Keys are created under Settings → API Keys. **Billing** — operations are billed in points against your workspace balance. Each operation below states when the charge applies. The current cost of every operation is shown in the app under [Settings → Billing](https://app.loice.ai/settings/account?tab=billing) and in the live API description, `GET /api/v1/openapi.json`. Calls that fail because of a system or provider error (timeouts, upstream failures, our defects) are not billed, and rate-limited calls are rejected before any billable work. Check headroom with `GET /api/v1/points`. Where an operation documents an `Idempotency-Key` header, send one to retry safely: a repeated request returns the original outcome and is not charged again. **Errors** — every non-200 response has the shape `{ "error": { "message": "…" } }`. Operations whose error responses document an `error.code` also return that machine-readable code beside the message; branch on the code, not the text. servers: - url: https://app.loice.ai security: [] paths: /api/v1/company: post: summary: Resolve a company LinkedIn page to structured data description: >- Resolves a company or school LinkedIn page URL (`linkedinUrl`, the only identifier this operation accepts) into a structured company record — industry, size band, headquarters, website, founding year, specialities, social profiles and more — from our own datastore, fetching and parsing the public company page when we have not seen it before. A company we already hold is answered from our records (`cached: true`, same price) even when live fetching is unavailable. A school is answered from our dataset only, because LinkedIn does not serve school pages publicly. Pass `refresh: true` to bypass cached freshness (billed again; not available for a school). The address must be a FULL page URL: a bare slug such as `microsoft` is refused as `invalid-input` (400), as is a person, job, group or post URL. Reasons: `no-such-company` (200, charged — the page states no such company), `invalid-input` (400), `insufficient-credits` (402), `login-required` (422 — a login wall, a school we do not hold, or a numeric id we cannot prove; retrying cannot help) and `unavailable` (503 — the source could not be read). A refusal carries the same `data` body as a success. Fields the source does not state are returned as `null` and are never inferred. The company email is returned only when it is a generic role address on the company's own domain that passed verification and is not on the workspace's or the platform's do-not-contact list; the phone is always null until phone verification is available. Rate limited per workspace (shared with the web app). #### Billing - charged per completed lookup — whether a company was found or not, and whether the answer came from owned data or a live fetch — never when the source could not be read, never for a refusal. The current cost is shown in the app under Settings → Billing and in the live `GET /api/v1/openapi.json`. Calls that end in a system or provider error (HTTP 500) or are rate limited (HTTP 429) are not billed. The `charged` and `pointsCharged` fields of the response state what this call actually consumed. parameters: - schema: type: string minLength: 1 maxLength: 255 description: >- Optional, 1–255 printable ASCII characters, scoped to your workspace. Send the same key when you retry the same request: the original outcome is replayed (`replay: true`, `charged: false`, `pointsCharged: 0`) instead of running and charging again. The same key with a different request is refused with 409 `idempotency_conflict`, as is a key reused after its replay record expired (kept 30 days); a key whose first request is still running answers 409 `idempotency_in_progress`. Without a key, every request is a new lookup, billed at most once on its own. required: false description: >- Optional, 1–255 printable ASCII characters, scoped to your workspace. Send the same key when you retry the same request: the original outcome is replayed (`replay: true`, `charged: false`, `pointsCharged: 0`) instead of running and charging again. The same key with a different request is refused with 409 `idempotency_conflict`, as is a key reused after its replay record expired (kept 30 days); a key whose first request is still running answers 409 `idempotency_in_progress`. Without a key, every request is a new lookup, billed at most once on its own. name: Idempotency-Key in: header requestBody: required: true content: application/json: schema: type: object properties: linkedinUrl: type: string description: >- A full LinkedIn company or school page URL (any locale subdomain, `/m/`, a sub-page, or a numeric id). A bare slug (`microsoft`) and a person, job, group or post URL are refused as `invalid-input`. refresh: type: boolean description: >- Bypass cached freshness and re-confirm against the source. Billed again. True only for the JSON literal `true`. Not available for a school (answered 422 `login-required`, never billed): school pages are not public, so there is no source to re-confirm against. required: - linkedinUrl example: linkedinUrl: https://www.linkedin.com/company/siemens-healthineers responses: '200': description: >- A completed lookup — a company found, or `no-such-company` (charged). Inspect `found`, `reason`, `charged` and `replay`. content: application/json: schema: type: object properties: data: type: object properties: found: type: boolean company: allOf: - $ref: '#/components/schemas/Company' - type: - object - 'null' reason: type: - string - 'null' enum: - no-such-company - login-required - unavailable - invalid-input - insufficient-credits description: >- null when a company was found. `no-such-company`: the page states no such company (a charged answer, 200). `invalid-input` (400): a bare slug, a person/job/post URL or junk. `insufficient-credits` (402). `login-required` (422): a login wall, a school we do not hold, or an unproven numeric id — retrying cannot help. `unavailable` (503): the source could not be read (timeout, rate limit, block, upstream error) or the lookup could not be completed. Only `no-such-company` is charged. cached: type: boolean description: >- Whether the answer came from owned data. Does NOT change the price. charged: type: boolean description: Whether this call consumed points. pointsCharged: type: integer description: Points consumed by this call. balance: type: - object - 'null' properties: available: type: integer reserved: type: integer granted: type: integer required: - available - reserved - granted description: >- The workspace balance after the call; null when it could not be read. replay: type: boolean description: >- True when this is the stored outcome of an earlier call with the same `Idempotency-Key` (never charged again). creditsCharged: type: integer description: >- = `pointsCharged` (legacy field name, kept for compatibility). servedFromCache: type: boolean description: >- = `cached` (legacy field name, kept for compatibility). required: - found - company - reason - cached - charged - pointsCharged - balance - replay - creditsCharged - servedFromCache required: - data example: data: found: true company: name: Siemens Healthineers linkedinUrl: https://www.linkedin.com/company/siemens-healthineers tagline: We pioneer breakthroughs in healthcare. For everyone. description: null industry: Hospitals and Health Care employeeBand: 10,001+ employees employeeCount: 54349 followerCount: 2089731 websiteUrl: http://siemens-healthineers.com websiteDomain: siemens-healthineers.com headquarters: Forchheim hqLocality: Forchheim hqRegion: null hqCountry: DE foundedYear: null companyType: Public Company specialties: [] logoUrl: null logoImageUrl: null phone: null email: null xUrl: null facebookUrl: null instagramUrl: null youtubeUrl: null confirmedAt: '2026-09-24T12:00:00.000Z' reason: null cached: false charged: true pointsCharged: 2 balance: available: 98 reserved: 0 granted: 100 replay: false creditsCharged: 2 servedFromCache: false '400': description: >- Either `{ error }` with `validation_error` — `linkedinUrl` missing (message: "`linkedinUrl` is required.") or a malformed `Idempotency-Key` — or `{ data }` with reason `invalid-input`: a bare slug, a person/job/post URL or junk. Never billed. content: application/json: schema: anyOf: - type: object properties: error: type: object properties: code: type: string enum: - validation_error - unauthenticated - not_found - forbidden - method_not_allowed - idempotency_conflict - idempotency_in_progress - rate_limited - internal_error - run_already_active - search_unavailable - invalid_continuation description: >- Machine-readable error code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. retryAfterSeconds: type: integer description: >- Present on a 429 only: seconds until the workspace may call again (same value as the `Retry-After` header). required: - code - message required: - error - type: object properties: data: type: object properties: found: type: boolean company: allOf: - $ref: '#/components/schemas/Company' - type: - object - 'null' reason: type: - string - 'null' enum: - no-such-company - login-required - unavailable - invalid-input - insufficient-credits description: >- null when a company was found. `no-such-company`: the page states no such company (a charged answer, 200). `invalid-input` (400): a bare slug, a person/job/post URL or junk. `insufficient-credits` (402). `login-required` (422): a login wall, a school we do not hold, or an unproven numeric id — retrying cannot help. `unavailable` (503): the source could not be read (timeout, rate limit, block, upstream error) or the lookup could not be completed. Only `no-such-company` is charged. cached: type: boolean description: >- Whether the answer came from owned data. Does NOT change the price. charged: type: boolean description: Whether this call consumed points. pointsCharged: type: integer description: Points consumed by this call. balance: type: - object - 'null' properties: available: type: integer reserved: type: integer granted: type: integer required: - available - reserved - granted description: >- The workspace balance after the call; null when it could not be read. replay: type: boolean description: >- True when this is the stored outcome of an earlier call with the same `Idempotency-Key` (never charged again). creditsCharged: type: integer description: >- = `pointsCharged` (legacy field name, kept for compatibility). servedFromCache: type: boolean description: >- = `cached` (legacy field name, kept for compatibility). required: - found - company - reason - cached - charged - pointsCharged - balance - replay - creditsCharged - servedFromCache required: - data '401': description: >- `unauthenticated`. API key missing (`Missing API key. Pass it as: Authorization: Bearer `), invalid (`Invalid API key`), or expired (`This API key has expired`). content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - unauthenticated - not_found - forbidden - method_not_allowed - idempotency_conflict - idempotency_in_progress - rate_limited - internal_error - run_already_active - search_unavailable - invalid_continuation description: >- Machine-readable error code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. retryAfterSeconds: type: integer description: >- Present on a 429 only: seconds until the workspace may call again (same value as the `Retry-After` header). required: - code - message required: - error '402': description: >- `{ data }` with reason `insufficient-credits`: not enough points. Refused before any work; never billed. content: application/json: schema: type: object properties: data: type: object properties: found: type: boolean company: allOf: - $ref: '#/components/schemas/Company' - type: - object - 'null' reason: type: - string - 'null' enum: - no-such-company - login-required - unavailable - invalid-input - insufficient-credits description: >- null when a company was found. `no-such-company`: the page states no such company (a charged answer, 200). `invalid-input` (400): a bare slug, a person/job/post URL or junk. `insufficient-credits` (402). `login-required` (422): a login wall, a school we do not hold, or an unproven numeric id — retrying cannot help. `unavailable` (503): the source could not be read (timeout, rate limit, block, upstream error) or the lookup could not be completed. Only `no-such-company` is charged. cached: type: boolean description: >- Whether the answer came from owned data. Does NOT change the price. charged: type: boolean description: Whether this call consumed points. pointsCharged: type: integer description: Points consumed by this call. balance: type: - object - 'null' properties: available: type: integer reserved: type: integer granted: type: integer required: - available - reserved - granted description: >- The workspace balance after the call; null when it could not be read. replay: type: boolean description: >- True when this is the stored outcome of an earlier call with the same `Idempotency-Key` (never charged again). creditsCharged: type: integer description: >- = `pointsCharged` (legacy field name, kept for compatibility). servedFromCache: type: boolean description: >- = `cached` (legacy field name, kept for compatibility). required: - found - company - reason - cached - charged - pointsCharged - balance - replay - creditsCharged - servedFromCache required: - data '405': description: >- `method_not_allowed` (`Method not allowed`) — see the `Allow` response header. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - unauthenticated - not_found - forbidden - method_not_allowed - idempotency_conflict - idempotency_in_progress - rate_limited - internal_error - run_already_active - search_unavailable - invalid_continuation description: >- Machine-readable error code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. retryAfterSeconds: type: integer description: >- Present on a 429 only: seconds until the workspace may call again (same value as the `Retry-After` header). required: - code - message required: - error '409': description: >- The `Idempotency-Key` cannot be used for this request. `idempotency_conflict`: the key was already used with a different request, or reused after its replay record expired — send a new key. `idempotency_in_progress`: the first request with this key is still running. Never billed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - unauthenticated - not_found - forbidden - method_not_allowed - idempotency_conflict - idempotency_in_progress - rate_limited - internal_error - run_already_active - search_unavailable - invalid_continuation description: >- Machine-readable error code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. retryAfterSeconds: type: integer description: >- Present on a 429 only: seconds until the workspace may call again (same value as the `Retry-After` header). required: - code - message required: - error '422': description: >- `{ data }` with reason `login-required`: the source serves this page only to signed-in users. LinkedIn does this for NUMERIC company ids we cannot prove (the company's vanity URL is public, so supply that) and for every school page (a school not in our dataset cannot be answered, and a school cannot be refreshed). Retrying cannot help. Never billed. content: application/json: schema: type: object properties: data: type: object properties: found: type: boolean company: allOf: - $ref: '#/components/schemas/Company' - type: - object - 'null' reason: type: - string - 'null' enum: - no-such-company - login-required - unavailable - invalid-input - insufficient-credits description: >- null when a company was found. `no-such-company`: the page states no such company (a charged answer, 200). `invalid-input` (400): a bare slug, a person/job/post URL or junk. `insufficient-credits` (402). `login-required` (422): a login wall, a school we do not hold, or an unproven numeric id — retrying cannot help. `unavailable` (503): the source could not be read (timeout, rate limit, block, upstream error) or the lookup could not be completed. Only `no-such-company` is charged. cached: type: boolean description: >- Whether the answer came from owned data. Does NOT change the price. charged: type: boolean description: Whether this call consumed points. pointsCharged: type: integer description: Points consumed by this call. balance: type: - object - 'null' properties: available: type: integer reserved: type: integer granted: type: integer required: - available - reserved - granted description: >- The workspace balance after the call; null when it could not be read. replay: type: boolean description: >- True when this is the stored outcome of an earlier call with the same `Idempotency-Key` (never charged again). creditsCharged: type: integer description: >- = `pointsCharged` (legacy field name, kept for compatibility). servedFromCache: type: boolean description: >- = `cached` (legacy field name, kept for compatibility). required: - found - company - reason - cached - charged - pointsCharged - balance - replay - creditsCharged - servedFromCache required: - data '429': description: >- `rate_limited` (`Rate limit exceeded`): this workspace’s request budget is spent. Retry after the `Retry-After` header (also `error.retryAfterSeconds`). Never billed. headers: Retry-After: schema: type: string description: Seconds to wait before calling again. required: true description: Seconds to wait before calling again. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - unauthenticated - not_found - forbidden - method_not_allowed - idempotency_conflict - idempotency_in_progress - rate_limited - internal_error - run_already_active - search_unavailable - invalid_continuation description: >- Machine-readable error code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. retryAfterSeconds: type: integer description: >- Present on a 429 only: seconds until the workspace may call again (same value as the `Retry-After` header). required: - code - message required: - error '500': description: >- `internal_error` (`Internal error`): an unexpected failure on our side. Never billed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - unauthenticated - not_found - forbidden - method_not_allowed - idempotency_conflict - idempotency_in_progress - rate_limited - internal_error - run_already_active - search_unavailable - invalid_continuation description: >- Machine-readable error code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. retryAfterSeconds: type: integer description: >- Present on a 429 only: seconds until the workspace may call again (same value as the `Retry-After` header). required: - code - message required: - error '503': description: >- `{ data }` with reason `unavailable`: company resolution could not be completed right now. Retryable. Never billed. content: application/json: schema: type: object properties: data: type: object properties: found: type: boolean company: allOf: - $ref: '#/components/schemas/Company' - type: - object - 'null' reason: type: - string - 'null' enum: - no-such-company - login-required - unavailable - invalid-input - insufficient-credits description: >- null when a company was found. `no-such-company`: the page states no such company (a charged answer, 200). `invalid-input` (400): a bare slug, a person/job/post URL or junk. `insufficient-credits` (402). `login-required` (422): a login wall, a school we do not hold, or an unproven numeric id — retrying cannot help. `unavailable` (503): the source could not be read (timeout, rate limit, block, upstream error) or the lookup could not be completed. Only `no-such-company` is charged. cached: type: boolean description: >- Whether the answer came from owned data. Does NOT change the price. charged: type: boolean description: Whether this call consumed points. pointsCharged: type: integer description: Points consumed by this call. balance: type: - object - 'null' properties: available: type: integer reserved: type: integer granted: type: integer required: - available - reserved - granted description: >- The workspace balance after the call; null when it could not be read. replay: type: boolean description: >- True when this is the stored outcome of an earlier call with the same `Idempotency-Key` (never charged again). creditsCharged: type: integer description: >- = `pointsCharged` (legacy field name, kept for compatibility). servedFromCache: type: boolean description: >- = `cached` (legacy field name, kept for compatibility). required: - found - company - reason - cached - charged - pointsCharged - balance - replay - creditsCharged - servedFromCache required: - data security: - workspaceApiKey: [] components: schemas: Company: type: object properties: name: type: - string - 'null' linkedinUrl: type: - string - 'null' tagline: type: - string - 'null' description: type: - string - 'null' industry: type: - string - 'null' employeeBand: type: - string - 'null' description: Size band as the source displays it. employeeCount: type: - integer - 'null' description: Exact headcount, when stated. followerCount: type: - integer - 'null' websiteUrl: type: - string - 'null' websiteDomain: type: - string - 'null' headquarters: type: - string - 'null' hqLocality: type: - string - 'null' hqRegion: type: - string - 'null' hqCountry: type: - string - 'null' foundedYear: type: - integer - 'null' companyType: type: - string - 'null' specialties: type: array items: type: string logoUrl: type: 'null' description: >- Always null. Reserved so the shape stays stable: a provider image address is never returned (it is signed, expires, and discloses the viewer). Render `logoImageUrl`. logoImageUrl: type: - string - 'null' description: >- Our own copy of the logo (`/api/images/`, same authentication as this API). Null when the source states no logo or no copy is held. phone: type: - string - 'null' description: >- The company phone. Always null until phone verification is available; reserved so the shape does not change when it is. email: type: - string - 'null' description: >- The company's general contact email: only a generic role address (info@, sales@, …) on the company's own domain, stated by the company, that passed email verification. Null when none is stated or it did not verify. Never a personal address. xUrl: type: - string - 'null' description: >- X (Twitter) profile the company states as its own, as `https://x.com/`. Null when not stated; never constructed from the name. facebookUrl: type: - string - 'null' description: >- Facebook page the company states as its own, as `https://www.facebook.com/`. Null when not stated. instagramUrl: type: - string - 'null' description: >- Instagram profile the company states as its own, as `https://www.instagram.com/`. Null when not stated. youtubeUrl: type: - string - 'null' description: >- YouTube channel the company states as its own, as `https://www.youtube.com/` followed by `@handle`, `channel/…`, `c/…` or `user/…`. Null when not stated. confirmedAt: type: - string - 'null' description: >- When this record was last confirmed against the source. Null when the Company is built only from what a lead or list row observed (no company record). required: - name - linkedinUrl - tagline - description - industry - employeeBand - employeeCount - followerCount - websiteUrl - websiteDomain - headquarters - hqLocality - hqRegion - hqCountry - foundedYear - companyType - specialties - logoUrl - logoImageUrl - phone - email - xUrl - facebookUrl - instagramUrl - youtubeUrl - confirmedAt description: >- The canonical Company for the current employer (same schema as `POST /api/v1/company`). securitySchemes: workspaceApiKey: type: http scheme: bearer description: >- Workspace API key (`loice_sk_` + 48 hex characters), created under Settings → API Keys. Sent as `Authorization: Bearer loice_sk_…`. Invalid, missing, or expired keys are rejected with 401 before any billable work happens. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.