> ## Documentation Index > Fetch the complete documentation index at: https://docs.yo-lead.com/llms.txt > Use this file to discover all available pages before exploring further. # Get contact list > Returns a list and a page of its members, newest first. Required API key scope: `read`. ## OpenAPI ````yaml /openapi/public-api-v1.json get /v1/lists/{listId} openapi: 3.1.0 info: title: YoLead Public API version: 1.0.0 description: >- Public REST API for YoLead integrations. Only endpoints mounted under /v1 are included. Management endpoints used by the YoLead UI, including /integrations/*, are intentionally excluded. servers: - url: https://api.yo-lead.com description: Production security: - YoLeadPublicKey: [] YoLeadTimestamp: [] YoLeadSignature: [] tags: - name: Employees description: Employee data available to integrations. - name: Embed description: Iframe session creation for embedding YoLead UI. - name: Tickets description: Ticket history, status, and assignee operations. - name: Contacts description: Contacts available to the API key company. - name: Lists description: Contact lists available to the API key company. paths: /v1/lists/{listId}: get: tags: - Lists summary: Get contact list description: >- Returns a list and a page of its members, newest first. Required API key scope: `read`. operationId: getList parameters: - $ref: '#/components/parameters/ListId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' responses: '200': description: List and members. content: application/json: schema: $ref: '#/components/schemas/GetListResponse' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: parameters: ListId: name: listId in: path required: true description: List id. schema: $ref: '#/components/schemas/ObjectId' example: 64f000000000000000000006 Page: name: page in: query required: false description: Page number; defaults to 1. schema: type: integer minimum: 1 default: 1 Limit: name: limit in: query required: false description: Items per page; defaults to 20 and cannot exceed 100. schema: type: integer minimum: 1 maximum: 100 default: 20 schemas: GetListResponse: type: object additionalProperties: false required: - data properties: data: type: object additionalProperties: false required: - list - members - pagination properties: list: $ref: '#/components/schemas/ContactList' members: type: array items: $ref: '#/components/schemas/ListMember' pagination: $ref: '#/components/schemas/Pagination' ObjectId: type: string pattern: ^[0-9a-fA-F]{24}$ description: MongoDB ObjectId represented as a 24-character hexadecimal string. example: 64f000000000000000000001 ContactList: type: object additionalProperties: false required: - id - name - contactsCount properties: id: $ref: '#/components/schemas/ObjectId' name: type: string minLength: 1 maxLength: 100 example: Newsletter description: type: string maxLength: 1000 example: Contacts subscribed to our newsletter contactsCount: type: integer minimum: 0 createdAt: $ref: '#/components/schemas/IsoDateTime' updatedAt: $ref: '#/components/schemas/IsoDateTime' ListMember: type: object additionalProperties: false required: - id - contact properties: id: $ref: '#/components/schemas/ObjectId' contact: $ref: '#/components/schemas/Contact' createdAt: $ref: '#/components/schemas/IsoDateTime' Pagination: type: object additionalProperties: false required: - page - limit - total - totalPages - hasNext - hasPrev properties: page: type: integer minimum: 1 limit: type: integer minimum: 1 maximum: 100 total: type: integer minimum: 0 totalPages: type: integer minimum: 0 hasNext: type: boolean hasPrev: type: boolean ErrorResponse: type: object additionalProperties: false required: - code - message properties: code: type: integer example: 40001 message: type: string example: Validation error IsoDateTime: type: string format: date-time description: ISO 8601 date-time string. example: '2026-05-08T12:00:00.000Z' Contact: type: object additionalProperties: false required: - id - firstName - identities properties: id: $ref: '#/components/schemas/ObjectId' firstName: type: string minLength: 1 maxLength: 100 example: Alex lastName: type: string minLength: 1 maxLength: 100 example: Smith identities: $ref: '#/components/schemas/ContactIdentities' createdAt: $ref: '#/components/schemas/IsoDateTime' updatedAt: $ref: '#/components/schemas/IsoDateTime' ContactIdentities: type: object additionalProperties: false description: >- At least one identity type is required when creating a contact. Each provided identity type contains 1 to 20 trimmed values of at most 512 characters. properties: phone: $ref: '#/components/schemas/IdentityValues' whatsapp_phone: $ref: '#/components/schemas/IdentityValues' whatsapp_user_id: $ref: '#/components/schemas/IdentityValues' whatsapp_parent_user_id: $ref: '#/components/schemas/IdentityValues' email: $ref: '#/components/schemas/IdentityValues' telegram_user_id: $ref: '#/components/schemas/IdentityValues' telegram_username: $ref: '#/components/schemas/IdentityValues' telegram_phone: $ref: '#/components/schemas/IdentityValues' max_user_id: $ref: '#/components/schemas/IdentityValues' max_username: $ref: '#/components/schemas/IdentityValues' max_phone: $ref: '#/components/schemas/IdentityValues' vk_user_id: $ref: '#/components/schemas/IdentityValues' facebook_user_id: $ref: '#/components/schemas/IdentityValues' instagram_user_id: $ref: '#/components/schemas/IdentityValues' instagram_username: $ref: '#/components/schemas/IdentityValues' IdentityValues: type: array minItems: 1 maxItems: 20 items: type: string minLength: 1 maxLength: 512 responses: ValidationError: description: Validation or business-rule error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 40001 message: Validation error Unauthorized: description: Invalid API credentials, stale timestamp, or invalid request signature. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 40121 message: Invalid API credentials Forbidden: description: >- API key scope is not sufficient for this operation, or the required feature is unavailable on the company's current plan. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientScope: value: code: 40361 message: API key scope is not sufficient apiAccessUnavailable: value: code: 40351 message: API access is unavailable on your current plan NotFound: description: Requested entity was not found or is not accessible for this company. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 40471 message: Ticket not found InternalServerError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 50001 message: Internal server error securitySchemes: YoLeadPublicKey: type: apiKey in: header name: X-YoLead-Key description: Public API key generated in the YoLead UI. YoLeadTimestamp: type: apiKey in: header name: X-YoLead-Timestamp description: >- Unix timestamp in milliseconds. Requests must be signed within a 5-minute window. YoLeadSignature: type: apiKey in: header name: X-YoLead-Signature description: >- Hex HMAC-SHA256 signature over `.` using the API secret. ````