openapi: 3.1.0
info:
  title: Vessel CRM Accounts Contacts 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: Contacts
paths:
  /crm/contacts:
    get:
      operationId: getAllContacts
      summary: Get All Contacts
      description: Returns all contacts from the connected CRM.
      tags:
      - Contacts
      parameters:
      - name: accessToken
        in: query
        required: true
        schema:
          type: string
        description: User connection access token
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Pagination cursor for next page
      responses:
        '200':
          description: List of CRM contacts
          content:
            application/json:
              schema:
                type: object
                properties:
                  contacts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  nextCursor:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /crm/contacts/create:
    post:
      operationId: createContact
      summary: Create a Contact
      description: Creates a new contact in the connected CRM.
      tags:
      - Contacts
      parameters:
      - name: accessToken
        in: query
        required: true
        schema:
          type: string
        description: User connection access token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactInput'
      responses:
        '200':
          description: Contact created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /crm/contacts/update:
    post:
      operationId: updateContact
      summary: Update a Contact
      description: Updates an existing contact in the connected CRM.
      tags:
      - Contacts
      parameters:
      - name: accessToken
        in: query
        required: true
        schema:
          type: string
        description: User connection access token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - type: object
                required:
                - id
                properties:
                  id:
                    type: string
                    description: Contact ID to update
              - $ref: '#/components/schemas/ContactInput'
      responses:
        '200':
          description: Contact updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      description: API error response
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
    ContactInput:
      type: object
      description: Input for creating or updating a CRM contact
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
        title:
          type: string
        company:
          type: string
    Contact:
      type: object
      description: A CRM contact record
      properties:
        id:
          type: string
          description: Unique contact ID (string-normalized)
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        title:
          type: string
        company:
          type: string
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: vessel-api-token
      description: Your Vessel API token for server-side authentication