> ## 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.

# Create a new resource



## OpenAPI

````yaml /api-reference/openapi.json post /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}:
    post:
      tags:
        - CRM Resources
      summary: Create a new resource
      operationId: CrmResourceController_createResource
      parameters:
        - name: resource
          required: true
          in: path
          description: >-
            Canonical CRM resource type to create. 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). `owner` and `pipeline` are read-only and cannot be
            created.
          schema:
            enum:
              - contact
              - lead
              - deal
              - meeting
              - company
              - note
              - task
              - activity
              - appointment
            type: string
        - $ref: '#/components/parameters/ProviderQueryRequired'
        - $ref: '#/components/parameters/XEndUserIdHeader'
      requestBody:
        required: true
        description: >-
          CRM resource body. Pick an example from the dropdown to see the schema
          for each resource type.
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CreateContactDto'
                - $ref: '#/components/schemas/CreateLeadDto'
                - $ref: '#/components/schemas/CreateDealDto'
                - $ref: '#/components/schemas/CreateMeetingDto'
                - $ref: '#/components/schemas/CreateCompanyDto'
                - $ref: '#/components/schemas/CreateNoteDto'
                - $ref: '#/components/schemas/CreateTaskDto'
                - $ref: '#/components/schemas/CreateActivityDto'
                - $ref: '#/components/schemas/CreateAppointmentDto'
              discriminator:
                propertyName: resource
                mapping:
                  contact:
                    $ref: '#/components/schemas/CreateContactDto'
                  lead:
                    $ref: '#/components/schemas/CreateLeadDto'
                  deal:
                    $ref: '#/components/schemas/CreateDealDto'
                  meeting:
                    $ref: '#/components/schemas/CreateMeetingDto'
                  company:
                    $ref: '#/components/schemas/CreateCompanyDto'
                  note:
                    $ref: '#/components/schemas/CreateNoteDto'
                  task:
                    $ref: '#/components/schemas/CreateTaskDto'
                  activity:
                    $ref: '#/components/schemas/CreateActivityDto'
                  appointment:
                    $ref: '#/components/schemas/CreateAppointmentDto'
            examples:
              contact:
                summary: Contact — all fields optional
                value:
                  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
              lead:
                summary: Lead — title required
                value:
                  title: Hot inbound from Acme
                  first_name: Bob
                  last_name: Smith
                  email: bob.smith@acme.com
                  company: Acme Corp
                  status: qualified
                  source: website
                  value: 15000
                  currency: USD
                  contact: '12345'
              deal:
                summary: Deal — name required
                value:
                  name: Acme Enterprise Plan
                  amount: 48000
                  currency: USD
                  stage: negotiation
                  pipeline: default
                  close_date: '2025-06-30'
                  contact: '12345'
                  account: comp_001
                  probability: 70
                  description: Annual enterprise subscription
              meeting:
                summary: Meeting — title + start_time required
                value:
                  title: Acme Corp Discovery Call
                  description: Discuss enterprise requirements
                  start_time: '2025-04-10T14:00:00.000Z'
                  end_time: '2025-04-10T15:00:00.000Z'
                  location: Google Meet
                  meeting_url: https://meet.google.com/abc-defg-hij
                  contacts:
                    - '12345'
              company:
                summary: Create company
                value:
                  name: Acme Corp
                  industry: Technology
                  website: https://acme.com
              note:
                summary: Create note
                value:
                  title: Meeting follow-up
                  content: Discussed pricing and next steps for Q2 rollout.
                  contact: '12345'
                  account: comp_001
              task:
                summary: Create task
                value:
                  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'
                  contact: '12345'
                  opportunity: deal_xyz
              activity:
                summary: Create activity
                value:
                  type: call
                  subject: Discovery call with Acme
                  body: Discuss pricing and timeline
                  status: scheduled
                  start_time: '2025-04-10T14:00:00.000Z'
                  end_time: '2025-04-10T14:30:00.000Z'
                  direction: outbound
                  contact: '12345'
              appointment:
                summary: Appointment — start_time required
                value:
                  title: Discovery Call
                  start_time: '2026-04-15T10:00:00Z'
                  end_time: '2026-04-15T10:30:00Z'
                  calendar_id: parth-v1
                  contact_email: john@example.com
                  contact_name: John Doe
                  duration: 30
                  timezone: UTC
      responses:
        '201':
          description: Resource created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCrmResourceResponse'
              examples:
                contact:
                  summary: Contact created
                  value:
                    success: true
                    statusCode: 201
                    message: Created
                    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'
                lead:
                  summary: Lead created
                  value:
                    success: true
                    statusCode: 201
                    message: Created
                    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'
                deal:
                  summary: Deal created
                  value:
                    success: true
                    statusCode: 201
                    message: Created
                    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'
                meeting:
                  summary: Meeting created
                  value:
                    success: true
                    statusCode: 201
                    message: Created
                    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'
                company:
                  summary: Company created
                  value:
                    success: true
                    statusCode: 201
                    message: Created
                    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'
                note:
                  summary: Note created
                  value:
                    success: true
                    statusCode: 201
                    message: Created
                    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'
                task:
                  summary: Task created
                  value:
                    success: true
                    statusCode: 201
                    message: Created
                    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'
                activity:
                  summary: Activity created
                  value:
                    success: true
                    statusCode: 201
                    message: Created
                    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'
        '400':
          description: Validation failed or missing params
        '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:
    ProviderQueryRequired:
      name: provider
      required: true
      in: query
      description: >-
        Provider slug identifying which connected provider to target (e.g.
        `hubspot`, `pipedrive`, `zoho-crm`, `quickbooks-online`, `xero`,
        `zoho-books`). Required — single-record operations always target a
        specific provider.
      schema:
        example: hubspot
        type: string
    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
  schemas:
    CreateContactDto:
      type: object
      properties:
        first_name:
          type: string
          example: Gil
          description: Given name of the contact.
        last_name:
          type: string
          example: Feig
          description: Family name of the contact.
        account:
          type: string
          example: '420578000000250001'
          description: >-
            Provider-native ID of the associated account (company). Format is
            provider-specific.
        owner:
          type: string
          example: '420578000000250001'
          description: Provider-native ID of the record owner.
        addresses:
          type: array
          description: >-
            Postal addresses for this contact. Most providers persist only the
            first (primary) address.
          items:
            $ref: '#/components/schemas/AddressDto'
        email_addresses:
          type: array
          description: >-
            Email addresses for this contact. The first entry is treated as the
            primary email.
          items:
            $ref: '#/components/schemas/EmailAddressDto'
        phone_numbers:
          type: array
          description: >-
            Phone numbers for this contact. The first entry is treated as the
            primary phone.
          items:
            $ref: '#/components/schemas/PhoneNumberDto'
      additionalProperties: false
      title: Contact
    CreateLeadDto:
      type: object
      properties:
        first_name:
          type: string
          example: Bob
          description: Given name of the lead.
        last_name:
          type: string
          example: Smith
          description: Family name of the lead.
        title:
          type: string
          example: VP of Sales
          description: >-
            Short label or job title for the lead, depending on provider
            semantics.
        company:
          type: string
          example: Acme Corp
          description: >-
            Name of the company the lead is associated with (free-text, not an
            id).
        lead_source:
          type: string
          example: website
          description: >-
            Origin of the lead (e.g. `website`, `referral`, `event`).
            Provider-specific values are accepted.
        status:
          type: string
          example: OPEN
          description: Unified lead status. Mapped to the closest provider-native value.
          enum:
            - OPEN
            - CLOSED
            - UNQUALIFIED
            - QUALIFIED
        remote_status:
          type: string
          example: Not Contacted
          description: >-
            Provider-native status value. Bypasses unified enum validation and
            is written directly to the provider. Takes precedence over `status`
            when both are supplied.
        owner:
          type: string
          example: '67823451'
          description: Provider-native owner ID
        addresses:
          type: array
          description: >-
            Postal addresses for this lead. Most providers persist only the
            first (primary) address.
          items:
            $ref: '#/components/schemas/AddressDto'
        email_addresses:
          type: array
          description: >-
            Email addresses for this lead. The first entry is treated as the
            primary email.
          items:
            $ref: '#/components/schemas/EmailAddressDto'
        phone_numbers:
          type: array
          description: >-
            Phone numbers for this lead. The first entry is treated as the
            primary phone.
          items:
            $ref: '#/components/schemas/PhoneNumberDto'
        converted_date:
          type: string
          format: date-time
          example: '2026-04-15T00:00:00.000Z'
          description: >-
            ISO-8601 timestamp marking when the lead was converted into a
            contact/account. Only meaningful for converted leads.
        converted_contact:
          type: string
          example: '67823451'
          description: Provider-native id of the contact this lead was converted into.
        converted_account:
          type: string
          example: comp_001
          description: >-
            Provider-native id of the account/company this lead was converted
            into.
      additionalProperties: false
      title: Lead
    CreateDealDto:
      type: object
      properties:
        name:
          type: string
          example: Acme Enterprise Plan
          description: Human-readable name of the deal/opportunity.
        amount:
          type: number
          example: 48000
          description: Deal amount expressed in `currency`.
        currency:
          type: string
          example: USD
          description: ISO 4217 currency code for `amount`.
        stage:
          type: string
          example: negotiation
          description: Provider-native pipeline stage name/ID
        pipeline:
          type: string
          example: default
          description: >-
            Provider-native pipeline id the deal belongs to. Defaults to the
            provider's primary pipeline when omitted.
        status:
          type: string
          example: open
          description: Unified deal status. Mapped to the closest provider-native value.
          enum:
            - open
            - won
            - lost
        remote_status:
          type: string
          example: qualifiedtobuy
          description: >-
            Provider-native status value. Bypasses unified enum validation and
            is written directly to the provider. Takes precedence over `status`
            when both are supplied.
        probability:
          type: number
          example: 70
          description: Win probability 0–100
        description:
          type: string
          example: Annual enterprise subscription
          description: Free-text notes or summary about the deal.
        close_date:
          type: string
          example: '2025-06-30'
          description: ISO 8601 date or datetime string
        owner:
          type: string
          example: owner_001
          description: Provider-native owner ID
        contact:
          type: string
          example: '12345'
          description: Associated contact ID (provider-native)
        account:
          type: string
          example: comp_001
          description: Associated company/account ID (provider-native)
      required:
        - name
      additionalProperties: false
      title: Deal
    CreateMeetingDto:
      type: object
      properties:
        title:
          type: string
          example: Acme Corp Discovery Call
          description: Subject/title of the meeting.
        description:
          type: string
          example: Discuss enterprise requirements and pricing
          description: Free-text agenda or details for the meeting.
        location:
          type: string
          example: Google Meet
          description: >-
            Physical location or conferencing platform label (e.g. `Google
            Meet`, `Zoom`, `Acme HQ — Room 3`).
        status:
          type: string
          example: scheduled
          description: Lifecycle state of the meeting.
          enum:
            - scheduled
            - completed
            - cancelled
            - rescheduled
        organizer:
          type: string
          example: jane.rep@mycompany.com
          description: Email of the meeting organizer.
        attendees:
          type: array
          description: List of meeting attendees with their response status.
          items:
            $ref: '#/components/schemas/AttendeeDto'
        start_time:
          type: string
          example: '2025-04-10T14:00:00.000Z'
          description: ISO 8601 datetime
        end_time:
          type: string
          example: '2025-04-10T15:00:00.000Z'
          description: ISO 8601 datetime
        meeting_url:
          type: string
          example: https://meet.google.com/abc-defg-hij
          description: Join URL for virtual meetings.
        owner:
          type: string
          example: owner_001
          description: Provider-native id of the record owner.
        contacts:
          example:
            - '12345'
            - '67890'
          description: Provider-native contact IDs to associate
          type: array
          items:
            type: string
      required:
        - title
        - start_time
      additionalProperties: false
      title: Meeting
    CreateCompanyDto:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: Acme Corp
          description: Legal or display name of the company.
        domain:
          type: string
          example: acme.com
          description: Primary web domain (host only, no protocol).
        industry:
          type: string
          example: Technology
          description: Industry sector. Provider-specific taxonomies apply.
        description:
          type: string
          example: Enterprise software company
          description: Free-text summary about the company.
        phone:
          type: string
          example: +1-555-0100
          description: Primary phone number.
        website:
          type: string
          example: https://acme.com
          description: Primary website URL including protocol.
        number_of_employees:
          type: number
          example: 500
          description: Headcount as reported by the customer.
        annual_revenue:
          type: number
          example: 10000000
          description: Annual revenue (typically in the company's reporting currency).
        owner:
          type: string
          example: owner-1
          description: Provider-native id of the record owner.
        addresses:
          type: array
          description: >-
            Business addresses for this company. Most providers persist only the
            first (primary) address.
          items:
            $ref: '#/components/schemas/AddressDto'
      additionalProperties: false
      title: Company
    CreateNoteDto:
      type: object
      properties:
        content:
          type: string
          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
          example: '67823451'
          description: Provider-native id of the record owner.
        contact:
          type: string
          example: '12345'
          description: Provider-native id of the contact this note is associated with.
        account:
          type: string
          example: comp_001
          description: >-
            Provider-native id of the company/account this note is associated
            with.
        opportunity:
          type: string
          example: deal_xyz
          description: >-
            Provider-native id of the deal/opportunity this note is associated
            with.
      additionalProperties: false
      title: Note
    CreateTaskDto:
      type: object
      required:
        - subject
      properties:
        subject:
          type: string
          example: Follow up with client
          description: Short summary/title of the task.
        status:
          type: string
          description: Unified task status. Mapped to the closest provider-native value.
          enum:
            - OPEN
            - CLOSED
          example: OPEN
        content:
          type: string
          example: Send updated proposal with Q2 pricing
          description: Detailed description / body of the task.
        due_date:
          type: string
          format: date-time
          example: '2026-03-25T17:00:00Z'
          description: ISO-8601 timestamp by which the task should be completed.
        completed_date:
          type: string
          format: date-time
          example: '2026-06-15T17:00:00.000Z'
          description: >-
            ISO-8601 timestamp when the task was completed. Only meaningful when
            `status` is `CLOSED`.
        owner:
          type: string
          example: owner-1
          description: Provider-native id of the record owner.
        contact:
          type: string
          example: '12345'
          description: Provider-native id of the contact this task is associated with.
        account:
          type: string
          example: comp_001
          description: >-
            Provider-native id of the company/account this task is associated
            with.
        opportunity:
          type: string
          example: deal_xyz
          description: Provider-native opportunity/deal ID
      additionalProperties: false
      title: Task
    CreateActivityDto:
      type: object
      properties:
        type:
          type: string
          description: Kind of interaction being logged.
          enum:
            - call
            - email
            - other
          example: call
        subject:
          type: string
          example: Discovery call with prospect
          description: Short summary/title of the activity.
        body:
          type: string
          example: Discussed product features and pricing
          description: Free-text notes about the activity.
        status:
          type: string
          description: Lifecycle state of the activity.
          enum:
            - scheduled
            - completed
            - cancelled
          example: completed
        duration:
          type: number
          description: Duration in seconds
          example: 1800
        direction:
          type: string
          description: '`inbound` or `outbound`. Primarily for call/email activities.'
          enum:
            - inbound
            - outbound
          example: outbound
        start_time:
          type: string
          format: date-time
          example: '2026-03-18T14:00:00Z'
          description: ISO-8601 timestamp when the activity started.
        end_time:
          type: string
          format: date-time
          example: '2026-03-18T14:30:00Z'
          description: ISO-8601 timestamp when the activity ended.
        owner:
          type: string
          example: owner-1
          description: Provider-native id of the record owner.
        contact:
          type: string
          example: '12345'
          description: Provider-native id of the contact this activity is associated with.
        account:
          type: string
          example: comp_001
          description: >-
            Provider-native id of the company/account this activity is
            associated with.
        opportunity:
          type: string
          example: deal_xyz
          description: >-
            Provider-native id of the deal/opportunity this activity is
            associated with.
        lead:
          type: string
          example: lead_abc
          description: Provider-native id of the lead this activity is associated with.
      additionalProperties: false
      title: Activity
    CreateAppointmentDto:
      type: object
      properties:
        title:
          type: string
          example: Discovery Call
          description: Subject/title shown on the booked appointment.
        description:
          type: string
          example: Initial consultation to discuss project
          description: Free-text agenda or details for the appointment.
        duration:
          type: number
          example: 30
          description: Duration in minutes. Required for HubSpot booking.
        location:
          type: string
          example: 123 Main St, Suite 100
          description: Physical address or conferencing label for the appointment.
        timezone:
          type: string
          example: America/New_York
          description: >-
            IANA timezone in which `start_time` / `end_time` should be
            interpreted by the provider's UI.
        status:
          type: string
          description: Lifecycle state of the appointment.
          enum:
            - scheduled
            - confirmed
            - cancelled
            - completed
            - no_show
          example: scheduled
        start_time:
          type: string
          format: date-time
          example: '2026-04-15T10:00:00Z'
          description: ISO-8601 timestamp when the appointment starts.
        end_time:
          type: string
          format: date-time
          example: '2026-04-15T10:30:00Z'
          description: >-
            ISO-8601 timestamp when the appointment ends. Optional when
            `duration` is supplied.
        calendar_id:
          type: string
          example: parth-v1
          description: Scheduling page / calendar / service ID
        contact:
          type: string
          example: con_xyz789
          description: >-
            Provider-native id of the contact being booked. Use `contact_email`
            + `contact_name` instead for HubSpot inline booking when no contact
            exists yet.
        contact_email:
          type: string
          example: john@example.com
          description: Used by HubSpot for inline booking
        contact_name:
          type: string
          example: John Doe
          description: Used by HubSpot for inline booking
        owner:
          type: string
          example: owner_123
          description: Provider-native id of the host/owner of the appointment.
        meeting_location_type:
          type: string
          description: >-
            How the meeting will be held. Maps to provider-native conferencing
            options.
          enum:
            - custom
            - zoom
            - google_meet
            - microsoft_teams
            - phone
            - in_person
          example: zoom
      required:
        - start_time
      additionalProperties: false
      title: Appointment
    CreateCrmResourceResponse:
      type: object
      title: CreateCrmResourceResponse
      description: >-
        Standard envelope returned by `POST /crm/{resource}`. Contains the newly
        created record. The shape of `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: 201
          description: >-
            HTTP status code mirrored inside the envelope. `201` for successful
            creation.
        message:
          type: string
          example: Created
        data:
          $ref: '#/components/schemas/CreatableCrmResource'
      required:
        - success
        - statusCode
        - message
        - data
    AddressDto:
      type: object
      properties:
        street_1:
          type: string
          example: 50 Bowling Green Dr
          description: First line of the street address.
        street_2:
          type: string
          example: Golden Gate Park
          description: Second line of the street address (apartment, suite, unit, etc.).
        city:
          type: string
          example: San Francisco
          description: City / locality.
        state:
          type: string
          example: CA
          description: State, province, or region.
        postal_code:
          type: string
          example: '94122'
          description: Postal / ZIP code.
        country:
          type: string
          example: US
          description: ISO 3166-1 alpha-2 country code.
        address_type:
          type: string
          example: SHIPPING
          description: Category of the address. Defaults to a primary address when omitted.
          enum:
            - SHIPPING
            - BILLING
      additionalProperties: false
      title: Address
    EmailAddressDto:
      type: object
      properties:
        email_address:
          type: string
          format: email
          example: hello@example.com
          description: Email address value.
        email_address_type:
          type: string
          example: Work
          description: >-
            Label for the address (e.g. `Work`, `Personal`, `Other`).
            Provider-specific values are accepted.
      additionalProperties: false
      title: EmailAddress
    PhoneNumberDto:
      type: object
      properties:
        phone_number:
          type: string
          example: '+13785579223'
          description: Phone number in E.164 format where supported.
        phone_number_type:
          type: string
          example: Mobile
          description: >-
            Label for the phone number (e.g. `Mobile`, `Work`, `Home`).
            Provider-specific values are accepted.
      additionalProperties: false
      title: PhoneNumber
    AttendeeDto:
      type: object
      properties:
        email:
          type: string
          format: email
          example: jane.doe@example.com
          description: Email address of the attendee.
        name:
          type: string
          example: Jane Doe
          description: Display name of the attendee.
        status:
          type: string
          example: accepted
          description: Attendee response status.
          enum:
            - accepted
            - declined
            - tentative
            - pending
      additionalProperties: false
      title: Attendee
    CreatableCrmResource:
      title: CrmResource
      description: >-
        A CRM record returned after creation. The concrete shape depends on the
        `{resource}` path parameter — switch tabs to see each variant. `owner`
        and `pipeline` are not creatable.
      oneOf:
        - $ref: '#/components/schemas/ContactResponse'
        - $ref: '#/components/schemas/LeadResponse'
        - $ref: '#/components/schemas/DealResponse'
        - $ref: '#/components/schemas/MeetingResponse'
        - $ref: '#/components/schemas/CompanyResponse'
        - $ref: '#/components/schemas/NoteResponse'
        - $ref: '#/components/schemas/TaskResponse'
        - $ref: '#/components/schemas/ActivityResponse'
        - $ref: '#/components/schemas/AppointmentResponse'
    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.
    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
    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).
  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)

````