Truto Opportunities API

openapi: 3.2.0
info:
  title: Truto Unified CRM Opportunities API
  description: The Truto Unified CRM API provides a single normalized interface for reading and writing CRM data across 27 CRM providers including Salesforce, HubSpot, Pipedrive, Attio, Outreach, Wealthbox, Teamleader, and more. Offers 17 unified resources covering the full CRM data model. Data is accessed in real-time via pass-through. Schema can be extended using JSONata mappings without code deploys.
  version: 1.0.0
  contact:
    url: https://truto.one/docs/api-reference/unified-crm-api
servers:
- url: https://api.truto.one/unified/crm
  description: Truto Unified CRM API
security:
- bearerAuth: []
tags:
- name: Opportunities
  description: Sales opportunities and deals
paths:
  /opportunities:
    get:
      operationId: listOpportunities
      summary: List opportunities
      description: List sales opportunities from the connected CRM provider.
      tags:
      - Opportunities
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/IntegratedAccountId'
      - name: account_id
        in: query
        description: Filter by account ID.
        required: false
        schema:
          type: string
      - name: stage_id
        in: query
        description: Filter by pipeline stage ID.
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: Filter by opportunity status.
        required: false
        schema:
          type: string
          enum:
          - open
          - won
          - lost
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: List of opportunities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createOpportunity
      summary: Create opportunity
      description: Create a new opportunity in the connected CRM provider.
      tags:
      - Opportunities
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/IntegratedAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOpportunityRequest'
      responses:
        '201':
          description: Opportunity created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Opportunity'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    OpportunityListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Opportunity'
        nextCursor:
          type: string
    CreateOpportunityRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        accountId:
          type: string
        stageId:
          type: string
        amount:
          type: number
        currency:
          type: string
        closeDate:
          type: string
          format: date
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    Opportunity:
      type: object
      description: A sales opportunity or deal in the connected CRM.
      properties:
        id:
          type: string
        remoteId:
          type: string
        name:
          type: string
          description: Opportunity name or deal title.
        status:
          type: string
          enum:
          - open
          - won
          - lost
        stageId:
          type: string
          description: Current pipeline stage identifier.
        accountId:
          type: string
          description: Associated account identifier.
        amount:
          type: number
          description: Deal value.
        currency:
          type: string
          description: ISO 4217 currency code.
        probability:
          type: integer
          description: Probability of closing (0-100).
        closeDate:
          type: string
          format: date
          description: Expected or actual close date.
        ownerId:
          type: string
          description: CRM user responsible for this opportunity.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  parameters:
    IntegratedAccountId:
      name: integrated_account_id
      in: query
      required: true
      description: The ID of the integrated account (connected CRM provider instance) to query. Required for all Unified API requests.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication failed or token is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Tenant Bearer token from the Truto dashboard.