Vessel Connections API

openapi: 3.1.0
info:
  title: Vessel CRM Accounts Connections API
  description: The Vessel CRM API provides a unified interface for CRM operations across Salesforce, HubSpot, Zoho, Pipedrive, Close, Freshsales, Microsoft Dynamics, Affinity, monday.com, and Freshdesk. Operations are normalized across all CRM systems with consistent object models for contacts, deals, accounts, leads, notes, tasks, emails, calls, events, and users. Authentication uses vessel-api-token header and accessToken query parameter.
  version: '1.0'
  contact:
    name: Vessel Support
    email: support@vessel.dev
    url: https://www.vessel.dev/
  license:
    name: Proprietary
    url: https://www.vessel.dev/
servers:
- url: https://api.vessel.land
  description: Vessel CRM API
security:
- apiToken: []
tags:
- name: Connections
paths:
  /connection/connection:
    delete:
      operationId: deleteConnection
      summary: Delete a Connection
      description: Permanently deletes a CRM connection and frees associated resources. Always call this when a user disconnects their CRM.
      tags:
      - Connections
      parameters:
      - name: accessToken
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Connection deleted
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /connections/list:
    post:
      operationId: listConnections
      summary: List All Connections
      description: Returns all active connections for your API token. Useful for managing user integrations and tracking connection status.
      tags:
      - Connections
      security:
      - apiToken: []
      responses:
        '200':
          description: List of connections
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      connections:
                        type: array
                        items:
                          $ref: '#/components/schemas/Connection'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
  /connections/get:
    post:
      operationId: getConnection
      summary: Get a Connection
      description: Returns details for a specific connection by connection ID.
      tags:
      - Connections
      security:
      - apiToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: Connection ID to retrieve
      responses:
        '200':
          description: Connection details
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Connection'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '404':
          description: Connection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
  /connections/delete:
    post:
      operationId: deleteConnection
      summary: Delete a Connection
      description: Permanently deletes a connection and frees associated resources. Call this when a user disconnects a third-party integration from your app.
      tags:
      - Connections
      security:
      - apiToken: []
      - accessToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: Connection ID to delete
      responses:
        '200':
          description: Connection deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      success:
                        type: boolean
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
components:
  schemas:
    Connection:
      type: object
      description: A user's authenticated connection to a third-party integration
      properties:
        connectionId:
          type: string
          description: Unique connection identifier
        integrationId:
          type: string
          description: Connected integration identifier
        status:
          type: string
          description: Current connection status
          enum:
          - NEW_CONNECTION
          - INITIAL_SYNCED
          - READY
        createdAt:
          type: string
          format: date-time
          description: Connection creation timestamp
    Error:
      type: object
      description: API error response
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
    Error_2:
      type: object
      description: API error response
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message
            code:
              type: string
              description: Error code identifier
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: vessel-api-token
      description: Your Vessel API token for server-side authentication