> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.beanrails.com/llms.txt > Use this file to discover all available pages before exploring further. # List contacts > Returns the contacts your key can see, newest first. Requires the `contacts:read` scope. ## OpenAPI ````yaml /openapi.yaml get /contacts openapi: 3.1.0 info: title: BeanRails Public API version: 1.0.0 description: > Read and write BeanRails contacts, works, invoices, quotations and invoice payments from your own systems. Authenticate every request with an API key. See the guides for scopes, pagination and error handling. servers: - url: https://{host}/api/public/v1 description: Public API v1 variables: host: default: app.beanrails.com description: The host your BeanRails workspace is served from. security: - bearerAuth: [] tags: - name: Contacts description: Customers and leads. - name: Contact addresses description: Billing, shipping and service addresses of a contact. - name: Works description: Service or delivery jobs. - name: Work PODs description: Proof of delivery records submitted by drivers (read only). - name: Invoices description: Invoices, including status changes. - name: Quotations description: Quotations, including status changes. - name: Invoice payments description: Payments recorded against an invoice. paths: /contacts: get: tags: - Contacts summary: List contacts description: >- Returns the contacts your key can see, newest first. Requires the `contacts:read` scope. operationId: listContacts parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Search' - name: lifecycle_stage in: query description: Filter by lifecycle stage. schema: type: string enum: - lead - customer - name: status in: query description: Filter by contact status value. schema: type: string - name: user_id in: query description: Filter by assigned user ID. schema: type: integer responses: '200': description: A page of contacts. content: application/json: schema: $ref: '#/components/schemas/ContactList' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' components: parameters: Limit: name: limit in: query description: Records per page. Defaults to 10, capped at 100. schema: type: integer minimum: 1 maximum: 100 default: 10 Page: name: page in: query description: Page number, starting at 1. schema: type: integer minimum: 1 default: 1 Search: name: search in: query description: >- Free-text search across the record's main fields, such as its number, name or email. schema: type: string schemas: ContactList: type: object properties: data: type: array items: $ref: '#/components/schemas/Contact' links: $ref: '#/components/schemas/PaginationLinks' meta: $ref: '#/components/schemas/PaginationMeta' Contact: type: object additionalProperties: true properties: id: type: integer contact_number: type: string company_name: type: - string - 'null' first_name: type: - string - 'null' last_name: type: - string - 'null' email: type: - string - 'null' phone: type: - string - 'null' lifecycle_stage: type: string enum: - lead - customer status: type: - string - 'null' status_name: type: - string - 'null' user: type: - object - 'null' description: The assigned user. properties: id: type: integer name: type: string email: type: string groups: type: array items: type: object additionalProperties: true primary_address: oneOf: - $ref: '#/components/schemas/ContactAddress' - type: 'null' works_count: type: - integer - 'null' quotations_count: type: - integer - 'null' invoices_count: type: - integer - 'null' created_at: type: string updated_at: type: string PaginationLinks: type: object properties: first: type: - string - 'null' last: type: - string - 'null' prev: type: - string - 'null' next: type: - string - 'null' PaginationMeta: type: object properties: current_page: type: integer last_page: type: integer per_page: type: integer from: type: - integer - 'null' to: type: - integer - 'null' total: type: integer Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: A stable, machine readable code. examples: - not_found message: type: string description: A human readable explanation. ContactAddress: type: object additionalProperties: true properties: id: type: integer name: type: string attention: type: - string - 'null' email: type: - string - 'null' company_name: type: - string - 'null' mobile_no: type: - string - 'null' office_no: type: - string - 'null' address1: type: - string - 'null' address2: type: - string - 'null' city: type: - string - 'null' state: type: - string - 'null' postcode: type: - string - 'null' country: type: - string - 'null' description: Two letter country code. country_name: type: - string - 'null' zone_id: type: - integer - 'null' is_primary: type: boolean responses: Unauthorized: description: The API key is missing, invalid, revoked or expired. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key message: The API key is invalid, revoked, or expired. Forbidden: description: >- The key lacks the required scope, the key owner's role no longer allows it, or the owner's account is suspended. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_scope message: This API key does not have the required scope. RateLimited: description: >- You exceeded the key's requests per minute. Wait for the number of seconds in the `Retry-After` header. headers: Retry-After: description: Seconds until you can retry. schema: type: integer securitySchemes: bearerAuth: type: http scheme: bearer description: An API key created in BeanRails, for example `brk_live_...`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.