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

# List resources for an end user, optionally filtered by provider

> Returns a paginated list of CRM resources across all connected providers for the given end user. Pass `provider` to scope results to a single provider. Supports cursor-based pagination.



## OpenAPI

````yaml /api-reference/openapi.json get /crm/{resource}
openapi: 3.0.0
info:
  title: RouteMCP API
  description: >-
    Unified API for integrations. Connect to multiple providers through a single
    API.
  version: '1.0'
  contact: {}
servers:
  - url: https://api.routemcp.io/api/v1
    description: Production
security:
  - bearerAuth: []
tags: []
paths:
  /crm/{resource}:
    get:
      tags:
        - CRM Resources
      summary: List resources for an end user, optionally filtered by provider
      description: >-
        Returns a paginated list of CRM resources across all connected providers
        for the given end user. Pass `provider` to scope results to a single
        provider. Supports cursor-based pagination.
      operationId: CrmResourceController_listResources
      parameters:
        - name: resource
          required: true
          in: path
          description: >-
            Canonical CRM resource type to query. Must be one of the values in
            the enum below. RouteMCP maps this to the equivalent provider-native
            object (e.g. `contact` → HubSpot Contacts, Pipedrive Persons, Zoho
            Contacts).
          schema:
            enum:
              - contact
              - lead
              - deal
              - meeting
              - owner
              - company
              - note
              - task
              - pipeline
              - activity
              - appointment
            type: string
        - $ref: '#/components/parameters/XEndUserIdHeader'
        - $ref: '#/components/parameters/ProviderQueryOptional'
        - $ref: '#/components/parameters/CursorQuery'
        - $ref: '#/components/parameters/LimitQuery'
        - $ref: '#/components/parameters/EnrichQuery'
      responses:
        '200':
          description: Paginated list of CRM resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCrmResourcesResponse'
              examples:
                contact:
                  summary: Contact list
                  value:
                    success: true
                    statusCode: 200
                    message: OK
                    data:
                      - id: '12345'
                        remote_id: '12345'
                        first_name: Jane
                        last_name: Doe
                        email: jane.doe@example.com
                        phone: +1-555-0100
                        job_title: VP of Sales
                        address:
                          street_1: 123 Main St
                          city: San Francisco
                          state: CA
                          postal_code: '94105'
                          country: US
                        lifecycle_stage: customer
                        owner: '67823451'
                        owner_name: John Smith
                        owner_email: john.smith@acme.com
                        source: null
                        remote_created_at: '2025-01-15T10:00:00.000Z'
                        remote_updated_at: '2025-03-01T14:30:00.000Z'
                        providerSlug: hubspot
                        providerId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    pagination:
                      cursor: null
                      hasMore: false
                      limit: 25
                lead:
                  summary: Lead list
                  value:
                    success: true
                    statusCode: 200
                    message: OK
                    data:
                      - id: lead_abc
                        remote_id: lead_abc
                        title: Hot inbound from Acme
                        first_name: Bob
                        last_name: Smith
                        email: bob.smith@acme.com
                        phone: +1-555-0200
                        company: Acme Corp
                        status: qualified
                        source: website
                        value: 15000
                        currency: USD
                        owner: '67823451'
                        owner_name: Jane Rep
                        owner_email: jane.rep@mycompany.com
                        contact: '12345'
                        account: comp_001
                        remote_created_at: '2025-02-01T09:00:00.000Z'
                        remote_updated_at: '2025-03-05T11:00:00.000Z'
                        providerSlug: hubspot
                        providerId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    pagination:
                      cursor: null
                      hasMore: false
                      limit: 25
                deal:
                  summary: Deal list
                  value:
                    success: true
                    statusCode: 200
                    message: OK
                    data:
                      - id: deal_xyz
                        remote_id: deal_xyz
                        name: Acme Enterprise Plan
                        amount: 48000
                        currency: USD
                        stage: negotiation
                        pipeline: default
                        status: open
                        close_date: '2025-06-30T00:00:00.000Z'
                        owner: '67823451'
                        owner_name: Jane Rep
                        owner_email: jane.rep@mycompany.com
                        contact: '12345'
                        contact_name: Jane Doe
                        contact_email: jane.doe@example.com
                        contact_phone: null
                        account: comp_001
                        companyName: Acme Corp
                        probability: 70
                        description: Annual enterprise subscription
                        remote_created_at: '2025-02-10T08:00:00.000Z'
                        remote_updated_at: '2025-03-08T16:00:00.000Z'
                        providerSlug: hubspot
                        providerId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    pagination:
                      cursor: null
                      hasMore: false
                      limit: 25
                meeting:
                  summary: Meeting list
                  value:
                    success: true
                    statusCode: 200
                    message: OK
                    data:
                      - id: meet_001
                        remote_id: meet_001
                        title: Acme Corp Discovery Call
                        description: Discuss enterprise requirements and pricing
                        start_time: '2025-04-10T14:00:00.000Z'
                        end_time: '2025-04-10T15:00:00.000Z'
                        duration: 60
                        location: Google Meet
                        meeting_url: https://meet.google.com/abc-defg-hij
                        status: scheduled
                        owner: '67823451'
                        owner_name: Jane Rep
                        owner_email: jane.rep@mycompany.com
                        contacts:
                          - '12345'
                        organizer: jane.rep@mycompany.com
                        attendees:
                          - email: jane.doe@example.com
                            name: Jane Doe
                            status: accepted
                        remote_created_at: '2025-04-01T10:00:00.000Z'
                        remote_updated_at: '2025-04-05T12:00:00.000Z'
                        providerSlug: hubspot
                        providerId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    pagination:
                      cursor: null
                      hasMore: false
                      limit: 25
                owner:
                  summary: Owner list
                  value:
                    success: true
                    statusCode: 200
                    message: OK
                    data:
                      - id: '67823451'
                        remote_id: '67823451'
                        name: Jane Rep
                        first_name: Jane
                        last_name: Rep
                        email: jane.rep@mycompany.com
                        is_active: true
                        remote_created_at: '2020-01-01T00:00:00.000Z'
                        remote_updated_at: '2024-06-01T00:00:00.000Z'
                        providerSlug: hubspot
                        providerId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    pagination:
                      cursor: null
                      hasMore: false
                      limit: 25
                company:
                  summary: Company list
                  value:
                    success: true
                    statusCode: 200
                    message: OK
                    data:
                      - id: comp_001
                        remote_id: comp_001
                        name: Acme Corp
                        domain: acme.com
                        industry: Technology
                        description: Enterprise SaaS provider
                        number_of_employees: 500
                        phone: +1-555-0100
                        website: https://acme.com
                        address:
                          street_1: 123 Main St
                          city: San Francisco
                          state: CA
                          postal_code: '94105'
                          country: US
                        owner: '67823451'
                        owner_name: Jane Rep
                        owner_email: jane.rep@mycompany.com
                        annual_revenue: 10000000
                        remote_created_at: '2025-01-10T08:00:00.000Z'
                        remote_updated_at: '2025-03-01T14:30:00.000Z'
                    pagination:
                      cursor: null
                      hasMore: false
                      limit: 25
                note:
                  summary: Note list
                  value:
                    success: true
                    statusCode: 200
                    message: OK
                    data:
                      - id: note_001
                        remote_id: note_001
                        title: Meeting follow-up
                        content: Discussed pricing and next steps for Q2 rollout.
                        owner: '67823451'
                        owner_name: Jane Rep
                        owner_email: jane.rep@mycompany.com
                        contact: '12345'
                        account: comp_001
                        opportunity: null
                        lead: null
                        leadName: null
                        remote_created_at: '2025-03-01T10:00:00.000Z'
                        remote_updated_at: '2025-03-01T10:00:00.000Z'
                    pagination:
                      cursor: null
                      hasMore: false
                      limit: 25
                task:
                  summary: Task list
                  value:
                    success: true
                    statusCode: 200
                    message: OK
                    data:
                      - id: task_001
                        remote_id: task_001
                        subject: Follow up with Acme Corp
                        body: Send updated proposal with Q2 pricing
                        status: open
                        priority: high
                        due_date: '2025-06-15T17:00:00.000Z'
                        completed_date: null
                        owner: '67823451'
                        owner_name: Jane Rep
                        owner_email: jane.rep@mycompany.com
                        contact: '12345'
                        account: comp_001
                        opportunity: deal_xyz
                        lead: null
                        leadName: null
                        remote_created_at: '2025-03-05T09:00:00.000Z'
                        remote_updated_at: '2025-03-05T09:00:00.000Z'
                    pagination:
                      cursor: null
                      hasMore: false
                      limit: 25
                activity:
                  summary: Activity list
                  value:
                    success: true
                    statusCode: 200
                    message: OK
                    data:
                      - id: act_001
                        remote_id: act_001
                        type: call
                        subject: Discovery call with Acme
                        body: Discussed pricing and timeline for Q2
                        status: completed
                        start_time: '2025-04-10T14:00:00.000Z'
                        end_time: '2025-04-10T14:30:00.000Z'
                        duration: 30
                        direction: outbound
                        owner: '67823451'
                        owner_name: Jane Rep
                        owner_email: jane.rep@mycompany.com
                        contact: '12345'
                        account: comp_001
                        opportunity: deal_xyz
                        lead: null
                        leadName: null
                        remote_created_at: '2025-04-10T14:00:00.000Z'
                        remote_updated_at: '2025-04-10T14:35:00.000Z'
                    pagination:
                      cursor: null
                      hasMore: false
                      limit: 25
                pipeline:
                  summary: Pipeline list
                  value:
                    success: true
                    statusCode: 200
                    message: OK
                    data:
                      - id: pipe_001
                        remote_id: pipe_001
                        name: Sales Pipeline
                        is_active: true
                        display_order: 0
                        stages:
                          - id: stage_1
                            name: Qualification
                            display_order: 0
                            probability: 20
                            is_closed: false
                          - id: stage_2
                            name: Proposal
                            display_order: 1
                            probability: 50
                            is_closed: false
                          - id: stage_3
                            name: Closed Won
                            display_order: 2
                            probability: 100
                            is_closed: true
                        remote_created_at: null
                        remote_updated_at: null
                    pagination:
                      cursor: null
                      hasMore: false
                      limit: 25
        '400':
          description: Missing X-End-User-Id header or invalid resource type
        '401':
          description: Missing or invalid API key
        '404':
          description: End user or provider not found
        '422':
          description: Validation Errors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                    example: false
                  statusCode:
                    type: integer
                    example: 400
                    default: 400
                  message:
                    type: string
                    example: Validation Errors.
                    default: Validation Errors.
                  errors:
                    type: object
                    additionalProperties:
                      type: string
                    example:
                      email: email should not be empty
                  timestamp:
                    type: string
                    format: date-time
                    example: '2026-02-06T12:00:00.000Z'
                  path:
                    type: string
                    example: /api/v1/example
                required:
                  - success
                  - statusCode
                  - message
                  - errors
                  - timestamp
                  - path
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                    example: false
                  statusCode:
                    type: integer
                    example: 429
                    default: 429
                  message:
                    type: string
                    example: Too Many Requests
                    default: Too Many Requests
                  timestamp:
                    type: string
                    format: date-time
                    example: '2026-02-06T12:00:00.000Z'
                  path:
                    type: string
                    example: /api/v1/example
                required:
                  - success
                  - statusCode
                  - message
                  - timestamp
                  - path
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                    example: false
                  statusCode:
                    type: integer
                    example: 500
                    default: 500
                  message:
                    type: string
                    example: Internal server error.
                    default: Internal server error.
                  timestamp:
                    type: string
                    format: date-time
                    example: '2026-02-06T12:00:00.000Z'
                  path:
                    type: string
                    example: /api/v1/example
                required:
                  - success
                  - statusCode
                  - message
                  - timestamp
                  - path
      security:
        - bearerAuth: []
components:
  parameters:
    XEndUserIdHeader:
      name: X-End-User-Id
      required: true
      in: header
      description: >-
        Identifier of the end user whose connected provider should be queried.
        This is the same `endUserId` you supplied when creating the connect
        token. Required on every CRM and accounting call.
      schema:
        example: user-001
        type: string
    ProviderQueryOptional:
      name: provider
      required: false
      in: query
      description: >-
        Provider slug to scope the query to a single connected provider (e.g.
        `hubspot`, `pipedrive`, `zoho-crm`, `quickbooks-online`, `xero`,
        `zoho-books`). When omitted, RouteMCP fans out across every provider the
        end user has connected and returns a merged, paginated result.
      schema:
        example: hubspot
        type: string
    CursorQuery:
      name: cursor
      required: false
      in: query
      description: >-
        Opaque pagination cursor returned in the previous response's top-level
        `pagination.cursor` field. Pass it back unchanged to fetch the next
        page. Omit on the first request.
      schema:
        example: eyJodWJzcG90IjoiMTAwIn0
        type: string
    LimitQuery:
      name: limit
      required: false
      in: query
      description: >-
        Maximum number of records to return per page. Defaults to the provider's
        native page size (typically 25–100) when omitted. Values are clamped to
        each provider's supported maximum.
      schema:
        example: '25'
        type: string
    EnrichQuery:
      name: enrich
      required: false
      in: query
      description: >-
        Controls enrichment of related-record fields such as `owner_name`,
        `owner_email`, `contact_name`, `companyName`, etc. Accepts:

        - `true` *(default)* — enrich all supported fields. Adds extra provider
        calls; slower but more complete.

        - `false` — skip enrichment entirely. Fastest; returns only ids for
        related records.

        - A comma-separated list of field names (e.g. `owner_name,owner_email`)
        — enrich only the listed fields.
      schema:
        example: 'true'
        type: string
  schemas:
    ListCrmResourcesResponse:
      type: object
      title: ListCrmResourcesResponse
      description: >-
        Standard envelope returned by `GET /crm/{resource}`. The shape of each
        item inside `data` depends on the `{resource}` path parameter — see the
        tabs to switch between resource variants.
      properties:
        success:
          type: boolean
          example: true
          description: Always `true` for successful (2xx) responses.
        statusCode:
          type: integer
          example: 200
          description: HTTP status code mirrored inside the envelope.
        message:
          type: string
          example: OK
        data:
          type: array
          description: >-
            The list of CRM resources. The item shape depends on the
            `{resource}` path parameter.
          items:
            $ref: '#/components/schemas/CrmResource'
        pagination:
          $ref: '#/components/schemas/CrmPaginationMeta'
      required:
        - success
        - statusCode
        - message
        - data
        - pagination
    CrmResource:
      title: CrmResource
      description: >-
        A CRM record. The concrete shape depends on the `{resource}` path
        parameter — switch tabs to see each variant.
      oneOf:
        - $ref: '#/components/schemas/ContactResponse'
        - $ref: '#/components/schemas/LeadResponse'
        - $ref: '#/components/schemas/DealResponse'
        - $ref: '#/components/schemas/MeetingResponse'
        - $ref: '#/components/schemas/OwnerResponse'
        - $ref: '#/components/schemas/CompanyResponse'
        - $ref: '#/components/schemas/NoteResponse'
        - $ref: '#/components/schemas/TaskResponse'
        - $ref: '#/components/schemas/ActivityResponse'
        - $ref: '#/components/schemas/PipelineResponse'
        - $ref: '#/components/schemas/AppointmentResponse'
    CrmPaginationMeta:
      type: object
      title: Pagination
      description: Cursor-based pagination metadata returned with every list response.
      properties:
        cursor:
          type: string
          nullable: true
          example: eyJodWJzcG90IjoiMTAwIn0
          description: >-
            Opaque cursor for the next page. `null` when no more results are
            available. Pass this value back as the `cursor` query parameter to
            fetch the next page (from the top-level `pagination.cursor` field).
        hasMore:
          type: boolean
          example: false
          description: Indicates whether additional pages exist after the current one.
        limit:
          type: integer
          example: 25
          description: >-
            Page size that was applied to this response (matches the `limit`
            query parameter, or the provider default if not supplied).
      required:
        - cursor
        - hasMore
        - limit
    ContactResponse:
      type: object
      title: Contact
      description: A person record (typically associated with a company/account).
      allOf:
        - $ref: '#/components/schemas/CrmCommonResourceFields'
      properties:
        first_name:
          type: string
          nullable: true
          example: Jane
        last_name:
          type: string
          nullable: true
          example: Doe
        email:
          type: string
          format: email
          nullable: true
          example: jane.doe@example.com
          description: Primary email address.
        phone:
          type: string
          nullable: true
          example: +1-555-0100
          description: Primary phone number.
        job_title:
          type: string
          nullable: true
          example: VP of Sales
        address:
          allOf:
            - $ref: '#/components/schemas/CrmAddressResponse'
          nullable: true
          description: Primary postal address.
        lifecycle_stage:
          type: string
          nullable: true
          example: customer
          description: >-
            Lifecycle/funnel stage as reported by the provider (e.g. `lead`,
            `opportunity`, `customer`).
        owner:
          type: string
          nullable: true
          example: '67823451'
          description: Provider-native id of the record owner.
        owner_name:
          type: string
          nullable: true
          example: John Smith
          description: >-
            Enriched owner name. Only populated when `enrich=true` (default) or
            `enrich=owner_name`.
        owner_email:
          type: string
          format: email
          nullable: true
          example: john.smith@acme.com
          description: >-
            Enriched owner email. Only populated when `enrich=true` (default) or
            `enrich=owner_email`.
        source:
          type: string
          nullable: true
          example: website
          description: Original lead source (provider-specific value).
    LeadResponse:
      type: object
      title: Lead
      description: An unqualified prospect, before becoming a Contact + Deal.
      allOf:
        - $ref: '#/components/schemas/CrmCommonResourceFields'
      properties:
        title:
          type: string
          nullable: true
          example: Hot inbound from Acme
          description: Short label or job title for the lead, depending on provider.
        first_name:
          type: string
          nullable: true
          example: Bob
        last_name:
          type: string
          nullable: true
          example: Smith
        email:
          type: string
          format: email
          nullable: true
          example: bob.smith@acme.com
        phone:
          type: string
          nullable: true
          example: +1-555-0200
        company:
          type: string
          nullable: true
          example: Acme Corp
        status:
          type: string
          nullable: true
          example: qualified
          description: >-
            Lead status (`open`, `qualified`, `unqualified`, `closed`, or a
            provider-native value).
        source:
          type: string
          nullable: true
          example: website
        value:
          type: number
          nullable: true
          example: 15000
          description: Expected revenue for the lead (numeric, in `currency`).
        currency:
          type: string
          nullable: true
          example: USD
          description: ISO 4217 currency code for `value`.
        owner:
          type: string
          nullable: true
          example: '67823451'
        owner_name:
          type: string
          nullable: true
          example: Jane Rep
        owner_email:
          type: string
          format: email
          nullable: true
          example: jane.rep@mycompany.com
        contact:
          type: string
          nullable: true
          example: '12345'
          description: >-
            Provider-native id of the converted contact (if the lead has been
            converted).
        account:
          type: string
          nullable: true
          example: comp_001
          description: Provider-native id of the associated company/account.
    DealResponse:
      type: object
      title: Deal
      description: A sales opportunity tied to a contact and/or company.
      allOf:
        - $ref: '#/components/schemas/CrmCommonResourceFields'
      properties:
        name:
          type: string
          nullable: true
          example: Acme Enterprise Plan
        amount:
          type: number
          nullable: true
          example: 48000
          description: Deal amount in `currency`.
        currency:
          type: string
          nullable: true
          example: USD
          description: ISO 4217 currency code for `amount`.
        stage:
          type: string
          nullable: true
          example: negotiation
          description: Provider-native pipeline stage id or name.
        pipeline:
          type: string
          nullable: true
          example: default
          description: Provider-native pipeline id.
        status:
          type: string
          nullable: true
          example: open
          description: Deal status (`open`, `won`, `lost`, or a provider-native value).
        close_date:
          type: string
          format: date-time
          nullable: true
          example: '2025-06-30T00:00:00.000Z'
          description: Expected (or actual, if closed) close date.
        owner:
          type: string
          nullable: true
          example: '67823451'
        owner_name:
          type: string
          nullable: true
          example: Jane Rep
        owner_email:
          type: string
          format: email
          nullable: true
          example: jane.rep@mycompany.com
        contact:
          type: string
          nullable: true
          example: '12345'
        contact_name:
          type: string
          nullable: true
          example: Jane Doe
          description: Enriched contact name. Populated when `enrich=true`.
        contact_email:
          type: string
          format: email
          nullable: true
          example: jane.doe@example.com
        contact_phone:
          type: string
          nullable: true
          example: +1-555-0100
        account:
          type: string
          nullable: true
          example: comp_001
        companyName:
          type: string
          nullable: true
          example: Acme Corp
          description: >-
            Enriched name of the associated company. Populated when
            `enrich=true`.
        probability:
          type: number
          nullable: true
          example: 70
          description: Win probability as a percentage (0–100).
        description:
          type: string
          nullable: true
          example: Annual enterprise subscription
    MeetingResponse:
      type: object
      title: Meeting
      description: A scheduled meeting or call.
      allOf:
        - $ref: '#/components/schemas/CrmCommonResourceFields'
      properties:
        title:
          type: string
          nullable: true
          example: Acme Corp Discovery Call
        description:
          type: string
          nullable: true
          example: Discuss enterprise requirements and pricing
        start_time:
          type: string
          format: date-time
          nullable: true
          example: '2025-04-10T14:00:00.000Z'
        end_time:
          type: string
          format: date-time
          nullable: true
          example: '2025-04-10T15:00:00.000Z'
        duration:
          type: integer
          nullable: true
          example: 60
          description: Duration in minutes.
        location:
          type: string
          nullable: true
          example: Google Meet
        meeting_url:
          type: string
          format: uri
          nullable: true
          example: https://meet.google.com/abc-defg-hij
        status:
          type: string
          nullable: true
          example: scheduled
          description: >-
            Meeting status (`scheduled`, `completed`, `cancelled`, or a
            provider-native value).
        owner:
          type: string
          nullable: true
          example: '67823451'
        owner_name:
          type: string
          nullable: true
          example: Jane Rep
        owner_email:
          type: string
          format: email
          nullable: true
          example: jane.rep@mycompany.com
        contacts:
          type: array
          items:
            type: string
          example:
            - '12345'
          description: Provider-native ids of contacts invited to the meeting.
        organizer:
          type: string
          nullable: true
          example: jane.rep@mycompany.com
          description: Email address of the meeting organizer.
        attendees:
          type: array
          items:
            $ref: '#/components/schemas/CrmMeetingAttendeeResponse'
          description: List of meeting attendees with their response status.
    OwnerResponse:
      type: object
      title: Owner
      description: A user in the source CRM (typically a sales rep) that can own records.
      allOf:
        - $ref: '#/components/schemas/CrmCommonResourceFields'
      properties:
        name:
          type: string
          nullable: true
          example: Jane Rep
          description: Full display name.
        first_name:
          type: string
          nullable: true
          example: Jane
        last_name:
          type: string
          nullable: true
          example: Rep
        email:
          type: string
          format: email
          nullable: true
          example: jane.rep@mycompany.com
        is_active:
          type: boolean
          nullable: true
          example: true
          description: '`true` if the user is still active in the source CRM.'
    CompanyResponse:
      type: object
      title: Company
      description: A company / account record.
      allOf:
        - $ref: '#/components/schemas/CrmCommonResourceFields'
      properties:
        name:
          type: string
          nullable: true
          example: Acme Corp
        domain:
          type: string
          nullable: true
          example: acme.com
          description: Primary web domain (host only, no protocol).
        industry:
          type: string
          nullable: true
          example: Technology
        description:
          type: string
          nullable: true
          example: Enterprise SaaS provider
        number_of_employees:
          type: integer
          nullable: true
          example: 500
        phone:
          type: string
          nullable: true
          example: +1-555-0100
        website:
          type: string
          format: uri
          nullable: true
          example: https://acme.com
        address:
          allOf:
            - $ref: '#/components/schemas/CrmAddressResponse'
          nullable: true
          description: Primary business address.
        owner:
          type: string
          nullable: true
          example: '67823451'
        owner_name:
          type: string
          nullable: true
          example: Jane Rep
        owner_email:
          type: string
          format: email
          nullable: true
          example: jane.rep@mycompany.com
        annual_revenue:
          type: number
          nullable: true
          example: 10000000
          description: >-
            Annual revenue as reported by the provider (typically in the
            company's reporting currency).
    NoteResponse:
      type: object
      title: Note
      description: A free-form note attached to one or more CRM records.
      allOf:
        - $ref: '#/components/schemas/CrmCommonResourceFields'
      properties:
        title:
          type: string
          nullable: true
          example: Meeting follow-up
        content:
          type: string
          nullable: true
          example: Discussed pricing and next steps for Q2 rollout.
          description: >-
            Body of the note. May contain HTML on providers that support rich
            text.
        owner:
          type: string
          nullable: true
          example: '67823451'
        owner_name:
          type: string
          nullable: true
          example: Jane Rep
        owner_email:
          type: string
          format: email
          nullable: true
          example: jane.rep@mycompany.com
        contact:
          type: string
          nullable: true
          example: '12345'
        account:
          type: string
          nullable: true
          example: comp_001
        opportunity:
          type: string
          nullable: true
          example: deal_xyz
          description: Provider-native id of the associated deal/opportunity.
        lead:
          type: string
          nullable: true
          example: lead_abc
        leadName:
          type: string
          nullable: true
          example: Hot inbound from Acme
          description: Enriched name/title of the associated lead.
    TaskResponse:
      type: object
      title: Task
      description: A to-do or follow-up assigned to an owner.
      allOf:
        - $ref: '#/components/schemas/CrmCommonResourceFields'
      properties:
        subject:
          type: string
          nullable: true
          example: Follow up with Acme Corp
        body:
          type: string
          nullable: true
          example: Send updated proposal with Q2 pricing
        status:
          type: string
          nullable: true
          example: open
          description: >-
            Task status (`open`, `in_progress`, `completed`, `deferred`, or a
            provider-native value).
        priority:
          type: string
          nullable: true
          example: high
          description: Task priority (`low`, `medium`, `high`, or a provider-native value).
        due_date:
          type: string
          format: date-time
          nullable: true
          example: '2025-06-15T17:00:00.000Z'
        completed_date:
          type: string
          format: date-time
          nullable: true
          example: null
        owner:
          type: string
          nullable: true
          example: '67823451'
        owner_name:
          type: string
          nullable: true
          example: Jane Rep
        owner_email:
          type: string
          format: email
          nullable: true
          example: jane.rep@mycompany.com
        contact:
          type: string
          nullable: true
          example: '12345'
        account:
          type: string
          nullable: true
          example: comp_001
        opportunity:
          type: string
          nullable: true
          example: deal_xyz
        lead:
          type: string
          nullable: true
          example: null
        leadName:
          type: string
          nullable: true
          example: null
    ActivityResponse:
      type: object
      title: Activity
      description: An interaction logged against a CRM record (call, email, note, etc.).
      allOf:
        - $ref: '#/components/schemas/CrmCommonResourceFields'
      properties:
        type:
          type: string
          nullable: true
          example: call
          description: >-
            Activity type (`call`, `email`, `meeting`, `note`, `task`, or a
            provider-native value).
        subject:
          type: string
          nullable: true
          example: Discovery call with Acme
        body:
          type: string
          nullable: true
          example: Discussed pricing and timeline for Q2
        status:
          type: string
          nullable: true
          example: completed
        start_time:
          type: string
          format: date-time
          nullable: true
          example: '2025-04-10T14:00:00.000Z'
        end_time:
          type: string
          format: date-time
          nullable: true
          example: '2025-04-10T14:30:00.000Z'
        duration:
          type: integer
          nullable: true
          example: 30
          description: Duration in minutes.
        direction:
          type: string
          nullable: true
          example: outbound
          description: '`inbound` or `outbound` (primarily for call/email activities).'
        owner:
          type: string
          nullable: true
          example: '67823451'
        owner_name:
          type: string
          nullable: true
          example: Jane Rep
        owner_email:
          type: string
          format: email
          nullable: true
          example: jane.rep@mycompany.com
        contact:
          type: string
          nullable: true
          example: '12345'
        account:
          type: string
          nullable: true
          example: comp_001
        opportunity:
          type: string
          nullable: true
          example: deal_xyz
        lead:
          type: string
          nullable: true
          example: null
        leadName:
          type: string
          nullable: true
          example: null
    PipelineResponse:
      type: object
      title: Pipeline
      description: A named sales pipeline composed of ordered stages.
      allOf:
        - $ref: '#/components/schemas/CrmCommonResourceFields'
      properties:
        name:
          type: string
          nullable: true
          example: Sales Pipeline
        is_active:
          type: boolean
          nullable: true
          example: true
        display_order:
          type: integer
          nullable: true
          example: 0
          description: Position of the pipeline in the provider's UI (zero-based).
        stages:
          type: array
          items:
            $ref: '#/components/schemas/CrmPipelineStageResponse'
          description: Ordered list of stages that make up this pipeline.
    AppointmentResponse:
      type: object
      title: Appointment
      description: A booked appointment slot.
      allOf:
        - $ref: '#/components/schemas/CrmCommonResourceFields'
      properties:
        title:
          type: string
          nullable: true
          example: Strategy Session
        description:
          type: string
          nullable: true
          example: 60-minute discovery and planning session.
        start_time:
          type: string
          format: date-time
          nullable: true
          example: '2025-04-10T14:00:00.000Z'
        end_time:
          type: string
          format: date-time
          nullable: true
          example: '2025-04-10T15:00:00.000Z'
        status:
          type: string
          nullable: true
          example: scheduled
        owner:
          type: string
          nullable: true
          example: '67823451'
        contact:
          type: string
          nullable: true
          example: '12345'
    CrmCommonResourceFields:
      type: object
      description: Fields present on every CRM resource returned by RouteMCP.
      properties:
        id:
          type: string
          example: '12345'
          description: >-
            Canonical RouteMCP identifier. For most resources this matches
            `remote_id`; for resources that span multiple provider entities it
            is a composite URN.
        remote_id:
          type: string
          nullable: true
          example: '12345'
          description: Provider-native record id.
        remote_created_at:
          type: string
          format: date-time
          nullable: true
          example: '2025-01-15T10:00:00.000Z'
          description: >-
            ISO-8601 timestamp of when the record was created in the provider
            system.
        remote_updated_at:
          type: string
          format: date-time
          nullable: true
          example: '2025-03-01T14:30:00.000Z'
          description: >-
            ISO-8601 timestamp of when the record was last updated in the
            provider system.
        providerSlug:
          type: string
          example: hubspot
          description: >-
            Slug of the source provider (e.g. `hubspot`, `pipedrive`,
            `zoho-crm`, `gohighlevel`, `monday-crm`).
        providerId:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          description: >-
            Internal RouteMCP connection id linking the record to a specific
            tenant-provider connection.
    CrmAddressResponse:
      type: object
      title: Address
      description: Postal address embedded on a CRM resource.
      properties:
        street_1:
          type: string
          nullable: true
          example: 123 Main St
          description: First line of the street address.
        street_2:
          type: string
          nullable: true
          example: Suite 400
          description: Second line of the street address (apartment, suite, unit, etc.).
        city:
          type: string
          nullable: true
          example: San Francisco
        state:
          type: string
          nullable: true
          example: CA
          description: State, province, or region.
        postal_code:
          type: string
          nullable: true
          example: '94105'
        country:
          type: string
          nullable: true
          example: US
          description: ISO 3166-1 alpha-2 country code.
    CrmMeetingAttendeeResponse:
      type: object
      title: MeetingAttendee
      description: Person attending a meeting.
      properties:
        email:
          type: string
          format: email
          example: jane.doe@example.com
        name:
          type: string
          nullable: true
          example: Jane Doe
        status:
          type: string
          nullable: true
          example: accepted
          description: >-
            Attendee response status (`accepted`, `declined`, `tentative`,
            `needs_action`, or a provider-native value).
    CrmPipelineStageResponse:
      type: object
      title: PipelineStage
      description: Stage within a sales pipeline.
      properties:
        id:
          type: string
          example: stage_1
          description: Provider-native stage id.
        name:
          type: string
          example: Qualification
        display_order:
          type: integer
          example: 0
          description: Zero-based position of the stage in the pipeline.
        probability:
          type: number
          nullable: true
          example: 20
          description: >-
            Default win probability for deals in this stage, expressed as a
            percentage (0–100).
        is_closed:
          type: boolean
          example: false
          description: '`true` if the stage is a terminal closed-won or closed-lost stage.'
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Enter your API key with the Bearer prefix — e.g. Bearer sk_live_xxx
        (production) or Bearer sk_test_xxx (sandbox)

````