> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitmy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List contacts

> Returns contacts owned by the API key's user.
Results never accept an owner id — they are always scoped to the key.
Soft-merged duplicates and the owner's self row are excluded.




## OpenAPI

````yaml /openapi.yaml get /api/v1/contacts
openapi: 3.1.0
info:
  title: Orbit API
  version: 1.0.0
  description: |
    Read-only public API for your private Orbit network.
    Authenticate with a Pro API key (`orb_live_…`) from Settings → API.
  contact:
    name: Orbit Support
    email: support@orbitmy.co
    url: https://docs.orbitmy.co
servers:
  - url: https://orbitmy.co
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Contacts
    description: Read contacts in the authenticated user's Orbit
paths:
  /api/v1/contacts:
    get:
      tags:
        - Contacts
      summary: List contacts
      description: |
        Returns contacts owned by the API key's user.
        Results never accept an owner id — they are always scoped to the key.
        Soft-merged duplicates and the owner's self row are excluded.
      operationId: listContacts
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size (1–100). Defaults to 50.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          required: false
          description: Number of contacts to skip for pagination.
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Paginated contact list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactListResponse'
              example:
                data:
                  - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    name: Ada Lovelace
                    email: ada@analytical.example
                    phone: null
                    company: Analytical Engines
                    title: Chief Visionary
                    school: University of London
                    linkedin_url: https://www.linkedin.com/in/ada
                    location: London, UK
                    description: Mathematician and writer
                    tags:
                      - founder
                      - advisor
                    enrichment: {}
                    enriched_at: '2026-07-01T12:00:00.000Z'
                    source: linkedin
                    birthday: null
                    created_at: '2026-06-01T12:00:00.000Z'
                    updated_at: '2026-07-01T12:00:00.000Z'
                pagination:
                  limit: 50
                  offset: 0
                  total: 1
                  nextOffset: null
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Invalid or inactive API key
        '403':
          description: Key lacks contacts:read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: API key lacks contacts:read
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ContactListResponse:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    Contact:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        company:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        school:
          type: string
          nullable: true
        linkedin_url:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
          nullable: true
        enrichment:
          type: object
          additionalProperties: true
          nullable: true
        enriched_at:
          type: string
          format: date-time
          nullable: true
        source:
          type: string
          nullable: true
        birthday:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Pagination:
      type: object
      required:
        - limit
        - offset
        - total
        - nextOffset
      properties:
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
        nextOffset:
          type: integer
          nullable: true
          description: Offset for the next page, or null when finished
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: orb_live_
      description: Personal Orbit API key from Settings → API

````