vocabulary:
  name: Vessel Embedded Integrations Vocabulary
  description: >-
    Domain vocabulary for the Vessel developer-first embedded integrations
    platform covering CRM, sales engagement, authentication flows, connection
    management, and integration concepts.
  version: '2026-05-03'
  terms:
    - term: Access Token
      definition: >-
        A secret token obtained by exchanging a public token or session token
        that is used to make API calls on behalf of a user's connected
        integration. Must be stored securely on the backend and never exposed
        in the client.
      tags:
        - Authentication
        - Security

    - term: Actions API
      definition: >-
        Vessel's pre-built, validated interface for interacting with downstream
        integrations. Actions validate both request inputs and API responses
        using zod, standardize data types (ISO 8601 dates, string IDs), and
        abstract downstream provider quirks for a consistent developer
        experience.
      tags:
        - Actions
        - Integrations

    - term: Connection
      definition: >-
        A user's authenticated link to a specific third-party integration (e.g.,
        their Salesforce org, HubSpot account). Identified by a connectionId.
        Connections have lifecycle statuses: NEW_CONNECTION, INITIAL_SYNCED,
        and READY.
      tags:
        - Authentication
        - Connections

    - term: Connection Status
      definition: >-
        The current synchronization state of a CRM connection. NEW_CONNECTION
        blocks CRM API calls. INITIAL_SYNCED means the first 30 days of data
        has synced and CRM calls are unblocked. READY means all historical data
        has synced.
      tags:
        - Connections
        - Status

    - term: Embedded Integration
      definition: >-
        A native integration built into a product that allows end-users to
        connect their own third-party tools. Vessel provides the infrastructure
        to build embedded integrations without managing authentication,
        rate limits, or data normalization.
      tags:
        - Embedded Integrations

    - term: Link Token
      definition: >-
        A temporary token used to initiate the Vessel Link authentication flow
        in the CRM API. Retrieved from /link/token and passed to the
        @vesselapi/react-vessel-link component to open the OAuth modal.
      tags:
        - Authentication
        - CRM

    - term: Passthrough API
      definition: >-
        A Vessel API endpoint that forwards authenticated requests directly to
        the downstream integration provider. Authentication credentials are
        automatically attached. Useful for calling provider endpoints not yet
        covered by Vessel actions.
      tags:
        - Passthrough

    - term: Public Token
      definition: >-
        A temporary, non-sensitive token returned from the Vessel Link UI
        after a user successfully authenticates their integration. Must be
        immediately exchanged on the backend for an access token.
      tags:
        - Authentication
        - Security

    - term: Session Token
      definition: >-
        A temporary token generated by the Vessel Platform API that holds
        authentication session state. Passed to the Vessel client SDK to open
        the integration authentication modal.
      tags:
        - Authentication
        - Platform API

    - term: Unified API
      definition: >-
        Vessel's normalized API layer that provides a single interface for
        interacting with multiple CRM, sales engagement, chat, marketing
        automation, and dialer systems. Normalizes data models, field names,
        date formats, and ID types across providers.
      tags:
        - CRM
        - Unified API

    - term: Vessel Link
      definition: >-
        Vessel's drop-in React UI component (@vesselapi/react-vessel-link) that
        provides a pre-built OAuth authentication modal for connecting users'
        third-party integrations. Handles the OAuth flow and returns a public
        token on success.
      tags:
        - Authentication
        - SDK

    - term: GTM
      definition: >-
        Go-to-Market. In the Vessel context, GTM tools refer to the sales and
        marketing technology stack including CRM (Salesforce, HubSpot), sales
        engagement (Outreach, Apollo, Salesloft), chat (Slack, Teams), marketing
        automation (Mailchimp, Customer.io), and dialers (Aircall, RingCentral).
      tags:
        - CRM
        - GTM
        - Sales Engagement