> ## 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. # Read a list’s members > Returns one page (25) of a list’s members, each as the canonical Person plus the email and mobile this workspace revealed and the CRM sync state. Filter with `q`, `hasEmail`, `emailValid`, `hasMobile`, `crm` and `source`; order with `sort`. #### Billing Free — this endpoint does not consume points. ## OpenAPI ````yaml /openapi.json get /api/v1/lead-lists/{listId}/members 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/lead-lists/{listId}/members: get: summary: Read a list’s members description: >- Returns one page (25) of a list’s members, each as the canonical Person plus the email and mobile this workspace revealed and the CRM sync state. Filter with `q`, `hasEmail`, `emailValid`, `hasMobile`, `crm` and `source`; order with `sort`. #### Billing Free — this endpoint does not consume points. parameters: - schema: type: string description: The list id. required: true description: The list id. name: listId in: path - schema: type: integer minimum: 1 maximum: 100000 default: 1 required: false name: page in: query - schema: type: string maxLength: 200 required: false name: q in: query - schema: type: string enum: - 'true' - 'false' required: false name: hasEmail in: query - schema: type: string enum: - 'true' - 'false' required: false name: emailValid in: query - schema: type: string enum: - 'true' - 'false' required: false name: hasMobile in: query - schema: type: string enum: - synced - not_synced - failed - imported required: false name: crm in: query - schema: type: string enum: - lead_search - employee_search - finder - linkedin_finder - enrichment - bulk - list - manual - import - crm - icp - company_website required: false name: source in: query - schema: type: string enum: - added_desc - added_asc - name_asc - name_desc - company_asc default: added_desc required: false name: sort in: query responses: '200': description: One page of members. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string person: $ref: '#/components/schemas/Person' email: type: - string - 'null' description: The address this workspace revealed, if any. emailStatus: type: - string - 'null' mobile: type: - string - 'null' mobileStatus: type: - string - 'null' personalEmail: type: - string - 'null' description: >- The personal address this workspace revealed (always verified `valid`), if any. personalEmailStatus: type: - string - 'null' description: >- `valid`, or `not_found` for a charged miss; null when never asked. source: type: string enum: - lead_search - employee_search - finder - linkedin_finder - enrichment - bulk - list - manual - import - crm - icp - company_website sources: type: array items: type: string enum: - lead_search - employee_search - finder - linkedin_finder - enrichment - bulk - list - manual - import - crm - icp - company_website description: Every source that added this person to this list. sourceUrl: type: - string - 'null' description: >- For a person found on their company’s website (`company_website`): the page that states them. Null otherwise. statedDomain: type: - string - 'null' description: >- The domain the contact’s source stated: for an Employee Finder person, the domain that was searched. It can differ from `person.company.websiteDomain`. addedAt: type: string crm: type: - object - 'null' properties: status: type: string enum: - imported - created - updated - skipped - failed origin: type: string enum: - import - push description: >- `import`: the record came from the CRM; `push`: Loice created or found it. externalId: type: - string - 'null' errorCode: type: - string - 'null' syncedAt: type: - string - 'null' required: - status - origin - externalId - errorCode - syncedAt required: - id - person - email - emailStatus - mobile - mobileStatus - personalEmail - personalEmailStatus - source - sources - sourceUrl - statedDomain - addedAt - crm meta: type: object properties: page: type: integer pageSize: type: integer description: Always 25. total: type: integer pageCount: type: integer withheld: type: integer description: >- Members of this page withheld by a do-not-contact entry. required: - page - pageSize - total - pageCount - withheld required: - data - meta example: data: [] meta: page: 1 pageSize: 25 total: 0 pageCount: 1 withheld: 0 '400': description: '`validation_error`: a query parameter is invalid.' 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 - run_already_continued - search_unavailable - invalid_continuation - invalid_input - insufficient_credits - incomplete 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 '401': description: >- 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: message: type: string required: - message required: - error '404': description: '`not_found`: no such active list in this workspace.' 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 - run_already_continued - search_unavailable - invalid_continuation - invalid_input - insufficient_credits - incomplete 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 '405': description: Method not allowed — see the `Allow` response header. content: application/json: schema: type: object properties: error: type: object properties: message: type: string required: - message required: - error '429': description: >- Rate limit exceeded for this workspace. Retry after the number of seconds in the `Retry-After` header (60). Rate-limited calls are never billed. content: application/json: schema: type: object properties: error: type: object properties: message: type: string required: - message required: - error '500': description: '`internal_error`: the read failed on our side.' 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 - run_already_continued - search_unavailable - invalid_continuation - invalid_input - insufficient_credits - incomplete 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 security: - workspaceApiKey: [] components: schemas: Person: type: - object - 'null' properties: avatarUrl: type: - string - 'null' description: >- Owned image address (`/api/images/`, authenticated). Null ⇒ render initials. fullName: type: - string - 'null' description: The source's own statement of the name. firstName: type: - string - 'null' description: >- The first name, as the source stated it when it stated two names; otherwise `fullName` split at read time (as written). Null when the name does not split. lastName: type: - string - 'null' description: >- The last name (the whole surname, e.g. "van Beethoven"), on the same rule as `firstName`. linkedinUrl: type: string description: >- Canonical profile URL — the identity. Never null. The public profile URL (`https://www.linkedin.com/in/`) when known, else the member-ID URL. xUrl: type: - string - 'null' description: >- The person's own X (Twitter) profile as a source stated it, as `https://x.com/`. Null when no source stated one — never derived from a name, an address or another site's username. facebookUrl: type: - string - 'null' description: >- The person's own Facebook profile as a source stated it (`https://www.facebook.com/` or `…/profile.php?id=`). Null when unstated. instagramUrl: type: - string - 'null' description: >- The person's own Instagram profile as a source stated it, as `https://www.instagram.com/`. Null when unstated. telegramUrl: type: - string - 'null' description: >- The person's own Telegram profile as a source stated it, as `https://t.me/` (never an invite or a channel post). Null when unstated. title: type: - string - 'null' description: Title of the primary current position. about: type: - string - 'null' company: $ref: '#/components/schemas/Company' companyName: type: - string - 'null' description: Alias of `company.name`. companyLinkedinUrl: type: - string - 'null' description: Alias of `company.linkedinUrl`. companyLogoUrl: type: - string - 'null' description: Alias of `company.logoImageUrl` (owned). domain: type: - string - 'null' description: >- The company's website domain, else the domain the profile resolver stated. industry: type: - string - 'null' description: Alias of `company.industry`. location: type: - string - 'null' description: The person's own location (never company HQ). department: type: - string - 'null' enum: - Accounting - Administrative - Arts and Design - Business Development - Community & Social Services - Consulting - Customer Success and Support - Education - Engineering - Entrepreneurship - Finance - Healthcare Services - Human Resources - Information Technology - Legal - Marketing - Media and Communication - Military and Protective Services - Operations - Product Management - Program and Project Management - Purchasing - Quality Assurance - Real Estate - Research - Sales - null description: Source-stated only; never classified from the title. seniority: type: - string - 'null' enum: - In Training - Entry Level - Senior - Strategic - Entry Level Manager - Experienced Manager - Director - Vice President - CXO - Owner / Partner - null description: Source-stated only; never classified from the title. yearsOfExperience: type: - string - 'null' enum: - Less than 1 year - 1-2 years - 3-5 years - 6-10 years - 11-15 years - 16-20 years - 20+ years - null description: >- Overlap-free union of stated positions; null when any start is missing or the stated precision leaves it between two buckets. employment: type: array items: $ref: '#/components/schemas/EmploymentEntry' description: Source order; [] when not available. education: type: array items: $ref: '#/components/schemas/EducationEntry' description: Source order; [] when not available. historyStatus: type: object properties: employment: type: string enum: - available - not-yet-available description: >- `not-yet-available`: no source has supplied this history yet (the list is []). `available` with [] means the source supplied an empty history. education: type: string enum: - available - not-yet-available description: >- `not-yet-available`: no source has supplied this history yet (the list is []). `available` with [] means the source supplied an empty history. required: - employment - education required: - avatarUrl - fullName - firstName - lastName - linkedinUrl - xUrl - facebookUrl - instagramUrl - telegramUrl - title - about - company - companyName - companyLinkedinUrl - companyLogoUrl - domain - industry - location - department - seniority - yearsOfExperience - employment - education - historyStatus description: >- linkedin mode only: THE canonical Person, present whenever resolution found someone; otherwise null. 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`). EmploymentEntry: type: object properties: companyName: type: - string - 'null' companyLinkedinUrl: type: - string - 'null' title: type: - string - 'null' start: $ref: '#/components/schemas/StatedDate' end: $ref: '#/components/schemas/StatedDate' current: type: boolean location: type: - string - 'null' description: Where the position was held, as the source stated it. description: type: - string - 'null' description: The person's own description of the position, as stated. required: - companyName - companyLinkedinUrl - title - start - end - current - location - description EducationEntry: type: object properties: school: type: - string - 'null' schoolLinkedinUrl: type: - string - 'null' degree: type: - string - 'null' field: type: - string - 'null' start: $ref: '#/components/schemas/StatedDate' end: $ref: '#/components/schemas/StatedDate' required: - school - schoolLinkedinUrl - degree - field - start - end StatedDate: type: - object - 'null' properties: year: type: integer month: type: - integer - 'null' description: 1–12, or null when the source stated the year only (never padded). required: - year - month 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.