Vessel

Vessel Engagement API (v1, legacy)

The first-generation Vessel Sales Engagement API, published under /engagement/* on api.vessel.land. Covers users, accounts, contacts, tasks, actions, calls, emails, call dispositions, sequences, sequence steps and mailboxes, plus the Link and connection endpoints. Superseded by the v2 engagement unification surface. Published by Vessel as OpenAPI 3.1.0 with 44 operations.

GitHub OpenAPI

Documentation

📖
Documentation
https://github.com/vesselapi/all-api-docs
📖
APIReference
https://github.com/vesselapi/all-api-docs/tree/main/docs/pages

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/vessel/refs/heads/main/openapi/vessel-engagement-v1-openapi.yml

SDKs

📦
GitHubRepository
https://github.com/vesselapi/all-api-docs

Other Resources

🔗
SpectralRuleset
https://raw.githubusercontent.com/api-evangelist/vessel/refs/heads/main/rules/vessel-api-rules.yml

OpenAPI Specification

vessel-engagement-v1-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: API Reference
  version: "2.0"
  summary: API
  description: |-
    Vessel's APIs requires an access token to be used together with your Vessel API token. Ensure the following headers are provided when making API calls:

    Key | Value | Description
    ---------|----------|----------
     vessel-api-token | `<VESSEL_API_TOKEN>` | The API token provided by us
     
    Additionally, in the query or body parameters of each request depending on whether it is a GET or POST, make sure to include the `accessToken` for the connection you want to access.
servers:
  - url: "https://api.vessel.land"
tags:
  - name: users
  - name: contacts
  - name: notes
  - name: tasks
  - name: deals
  - name: accounts
  - name: emails
  - name: events
  - name: attendees
  - name: leads
  - name: passthrough
  - name: links
  - name: connections
  - name: webhooks
  - name: integrations
  - name: tokens
  - name: engAccounts
  - name: engUsers
  - name: engContacts
  - name: engCalls
  - name: engTasks
  - name: engActions
  - name: engDispositions
  - name: engPassthrough
x-speakeasy-name-override:
  - operationId: post-*
    methodNameOverride: create
  - operationId: put-*
    methodNameOverride: update
  - operationId: delete-*
    methodNameOverride: delete
  - operationId: get-one-*
    methodNameOverride: find
  - operationId: get-all-*
    methodNameOverride: list
  - operationId: get-details-*
    methodNameOverride: details
  - operationId: get-batch-*
    methodNameOverride: batch
  - operationId: search-*
    methodNameOverride: search
paths:
  /engagement/users:
    get:
      summary: Get All Users
      tags: 
        - engUsers
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: "#/components/schemas/EngUser"
                  nextPageCursor:
                    type: string
              examples:
                example-1:
                  value:
                    users:
                      - id: 34f5b4b0b6b650c981a174b02753c390
                        firstName: Micheal
                        lastName: Scott
                        email: micheal@dundermifflin.com
                        createdTime: "2019-08-24T14:15:22Z"
                        modifiedTime: "2019-08-24T14:15:22Z"
                        associations:
                          taskIds:
                            - 2322707bbc41577d9806400e2daa25de
                          actionIds:
                            - 006b4db16b6b50c981a174b02753c390
                        additional: {}
                    nextPageCursor: string
      operationId: get-all-engagement-users
      parameters:
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/allFields'
      description: Retrieve all Users
    parameters: []
  /engagement/user:
    get:
      summary: Get User
      tags: 
        - engUsers
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  user:
                    $ref: "#/components/schemas/EngUser"
              examples:
                example-1:
                  value:
                    user:
                      id: 34f5b4b0b6b650c981a174b02753c390
                      firstName: Micheal
                      lastName: Scott
                      email: micheal@dundermifflin.com
                      createdTime: "2019-08-24T14:15:22Z"
                      modifiedTime: "2019-08-24T14:15:22Z"
                      associations:
                        taskIds:
                          - 2322707bbc41577d9806400e2daa25de
                        actionIds:
                          - 006b4db16b6b50c981a174b02753c390
                      additional: {}
      operationId: get-one-engagement-user
      parameters:
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/allFields'
      description: Retrieve a single User by Id
    parameters: []
  /engagement/accounts:
    get:
      summary: Get All Accounts
      tags: 
        - engAccounts
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: "#/components/schemas/EngAccount"
                  nextPageCursor:
                    type: string
              examples:
                example-1:
                  value:
                    accounts:
                      - id: 59f5b4b0b6b650c981a174b02753c390
                        name: Blue Cross
                        description: Blue Cross of Pennsylvania is responsible for providing services to the good people of Scranton
                        industry: TV and Media
                        numberOfEmployees: 100
                        website: www.bluecross.penn
                        createdTime: "2019-08-24T14:15:22Z"
                        modifiedTime: "2019-08-24T14:15:22Z"
                        phone: "8192223333"
                        locality: Scranton
                        address:
                          line1: 100 Blue Dr
                          line2: Suite 100
                          city: Scranton
                          state: Pennsylvania
                          postalCode: "281332"
                          country: USA
                        associations:
                          contactIds:
                            - e5f32d4fd2115220bd20a2ccf81210ec
                          actionIds:
                            - 006b4db16b6b50c981a174b02753c390
                          taskIds:
                            - 2322707bbc41577d9806400e2daa25de
                          ownerUserId: 56f653659ea9524b9e0fb0ba67e6f8a0
                        additional: {}
                    nextPageCursor: string
      operationId: get-all-engagement-accounts
      parameters:
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/allFields'
      description: |-
        Retrieve all Accounts
    parameters: []
  /engagement/account:
    get:
      summary: Get Account
      tags: 
        - engAccounts
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  account:
                    $ref: "#/components/schemas/EngAccount"
              examples:
                example-1:
                  value:
                    account:
                      - id: 59f5b4b0b6b650c981a174b02753c390
                        name: Blue Cross
                        description: Blue Cross of Pennsylvania is responsible for providing services to the good people of Scranton
                        industry: TV and Media
                        numberOfEmployees: 100
                        website: www.bluecross.penn
                        createdTime: "2019-08-24T14:15:22Z"
                        modifiedTime: "2019-08-24T14:15:22Z"
                        phone: "8192223333"
                        locality: Scranton
                        address:
                          line1: 100 Blue Dr
                          line2: Suite 100
                          city: Scranton
                          state: Pennsylvania
                          postalCode: "281332"
                          country: USA
                        associations:
                          contactIds:
                            - e5f32d4fd2115220bd20a2ccf81210ec
                          actionIds:
                            - 006b4db16b6b50c981a174b02753c390
                          taskIds:
                            - 2322707bbc41577d9806400e2daa25de
                          ownerUserId: 56f653659ea9524b9e0fb0ba67e6f8a0
                        additional: {}
      operationId: get-one-engagement-account
      parameters:
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/allFields'
      description: Retrieve a single Account by Id
    post:
      summary: Create Account
      tags: 
        - engAccounts
      operationId: post-engagement-account
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  id:
                    type: string
              examples:
                example-1:
                  value:
                    id: "0"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessToken:
                  type: string
                account:
                  $ref: "#/components/schemas/EngAccountCreate"
              required:
                - accessToken
                - account
            examples:
              example-1:
                value:
                  accessToken: string
                  account:
                    name: Blue Cross
                    description: Blue Cross of Pennsylvania is responsible for providing services to the good people of Scranton
                    industry: TV and Media
                    numberOfEmployees: 100
                    website: www.bluecross.penn
                    phone: "8192223333"
                    address:
                      line1: 100 Blue Dr
                      line2: Suite 100
                      city: Scranton
                      state: Pennsylvania
                      postalCode: "281332"
                      country: USA
                    additional: {}
      description: Create a new account.
    patch:
      summary: Update Account
      tags: 
        - engAccounts
      operationId: put-engagement-account
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                description: ""
                type: object
                x-examples:
                  example-1:
                    id: "0"
                properties:
                  id:
                    type: string
                required:
                  - id
              examples:
                example-1:
                  value:
                    id: "0"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessToken:
                  type: string
                id:
                  type: string
                account:
                  $ref: "#/components/schemas/EngAccountUpdate"
              required:
                - accessToken
                - id
                - account
            examples:
              example-1:
                value:
                  accessToken: string
                  id: string
                  account:
                    name: Blue Cross
                    description: Blue Cross of Pennsylvania is responsible for providing services to the good people of Scranton
                    industry: TV and Media
                    numberOfEmployees: 100
                    website: www.bluecross.penn
                    phone: "8192223333"
                    address:
                      line1: 100 Blue Dr
                      line2: Suite 100
                      city: Scranton
                      state: Pennsylvania
                      postalCode: "281332"
                      country: USA
                    additional: {}
          application/xml:
            schema:
              type: object
              properties: {}
        description: ""
      description: Update an existing account.
    parameters: []
  /engagement/accounts/search:
    post:
      summary: Search Accounts
      tags: 
        - engAccountss
      operationId: search-engagement-account
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: "#/components/schemas/EngAccount"
                  nextPageCursor:
                    type: string
              examples:
                example-1:
                  value:
                    accounts:
                      - id: "15"
                        name: "test account"
                        createdTime: "2023-02-17T21:28:30.000Z"
                        modifiedTime: "2023-02-18T01:57:12.000Z"
                        description: null
                        industry: null
                        numberOfEmployees: null
                        domain: "vessel.land"
                        website: null
                        address: null
                        phone: null
                        locality: "San Francisco"
                        associations:
                            ownerUserId: "1"
                        additional: {}
                    nextPageCursor: d9806400e2daa25de2322707bbc41577
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessToken:
                  type: string
                filters:
                  type: object
                  properties: 
                    name:
                      type: object
                      properties:
                        equals:
                          type: string
                      required: equals
                    domain:
                      type: object
                      properties:
                        equals:
                          type: string
                      required: equals
              required:
                - accessToken
                - filters
            examples:
              example-1:
                value:
                  accessToken: string
                  filters:
                    name:
                      equals:
                        "Acme Co."
      description: Search accounts.
  /engagement/contacts:
    get:
      summary: Get All Contacts
      tags: 
        - engContacts
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  contacts:
                    type: array
                    items:
                      $ref: "#/components/schemas/EngContact"
                  nextPageCursor:
                    type: string
              examples:
                example-1:
                  value:
                    contacts:
                      - id: 34f5b4b0b6b650c981a174b02753c390
                        firstName: Tom
                        lastName: Smith
                        jobTitle: Director of Operations
                        phones: 
                          - number: "8192223333"
                            type: "work"
                            isPrimary: true
                        emails: 
                          - address: "tom@dunder.com"
                            type: "work"
                            isPrimary: true
                        address: 
                          line1: 100 Blue Dr
                          line2: Suite 100
                          city: Scranton
                          state: Pennsylvania
                          postalCode: "281332"
                          country: USA
                        openCount: 0
                        clickCount: 3
                        replyCount: 1
                        bouncedCount: 1
                        createdTime: "2019-08-24T14:15:22Z"
                        modifiedTime: "2019-08-24T14:15:22Z"
                        associations:
                          accountId: 0dcb45e051315a6ea63b0f16e73689d9
                          actionIds:
                            - 006b4db16b6b50c981a174b02753c390
                          taskIds:
                            - 2322707bbc41577d9806400e2daa25de
                          ownerUserId: 56f653659ea9524b9e0fb0ba67e6f8a0
                        customFields: {}
                        additional: {}
                    nextPageCursor: string
      operationId: get-all-engagement-contacts
      parameters:
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/allFields'
      description: Retrieve all Contacts
    parameters: []
  /engagement/contact:
    get:
      summary: Get Contact
      tags: 
        - engContacts
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  contact:
                    $ref: "#/components/schemas/EngContact"
              examples:
                example-1:
                  value:
                    contact:
                      id: 34f5b4b0b6b650c981a174b02753c390
                      firstName: Tom
                      lastName: Smith
                      jobTitle: Director of Operations
                      phones: 
                        - number: "8192223333"
                          type: "work"
                          isPrimary: true
                      emails: 
                        - address: "tom@dunder.com"
                          type: "work"
                          isPrimary: true
                      address: 
                        line1: 100 Blue Dr
                        line2: Suite 100
                        city: Scranton
                        state: Pennsylvania
                        postalCode: "281332"
                        country: USA
                      openCount: 0
                      clickCount: 3
                      replyCount: 1
                      bouncedCount: 1
                      createdTime: "2019-08-24T14:15:22Z"
                      modifiedTime: "2019-08-24T14:15:22Z"
                      associations:
                        accountId: 0dcb45e051315a6ea63b0f16e73689d9
                        actionIds:
                          - 006b4db16b6b50c981a174b02753c390
                        taskIds:
                          - 2322707bbc41577d9806400e2daa25de
                        ownerUserId: 56f653659ea9524b9e0fb0ba67e6f8a0
                      customFields: {}
                      additional: {}
      operationId: get-one-engagement-contact
      parameters:
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/allFields'
      description: "Retrieve a Contact by Id."
    post:
      summary: Create Contact
      tags: 
        - engContacts
      operationId: post-engagement-contact
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  id:
                    type: string
              examples:
                example-1:
                  value:
                    id: "0"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessToken:
                  type: string
                contact:
                  $ref: "#/components/schemas/EngContactCreate"
              required:
                - accessToken
                - contact
            examples:
              example-1:
                value:
                  accessToken: string
                  contact:
                    firstName: Tom
                    lastName: Smith
                    jobTitle: Director of Operations
                    address: 
                      line1: 100 Blue Dr
                      line2: Suite 100
                      city: Scranton
                      state: Pennsylvania
                      postalCode: "281332"
                      country: USA
                    customFields: {}
                    additional: {}
      description: Create a new contact.
    patch:
      summary: Update Contact
      tags: 
        - engContacts
      operationId: put-engagement-contact
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                description: ""
                type: object
                x-examples:
                  example-1:
                    id: "0"
                properties:
                  id:
                    type: string
                required:
                  - id
              examples:
                example-1:
                  value:
                    id: "0"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessToken:
                  type: string
                id:
                  type: string
                contact:
                  $ref: "#/components/schemas/EngContactUpdate"
              required:
                - accessToken
                - id
                - contact
            examples:
              example-1:
                value:
                  accessToken: string
                  id: string
                  contact:
                    firstName: Tom
                    lastName: Smith
                    jobTitle: Director of Operations
                    address: 
                      line1: 100 Blue Dr
                      line2: Suite 100
                      city: Scranton
                      state: Pennsylvania
                      postalCode: "281332"
                      country: USA
                    customFields: {}
                    additional: {}
          application/xml:
            schema:
              type: object
              properties: {}
        description: ""
      description: Update an existing Contact.
    parameters: []
  /engagement/contacts/search:
    post:
      summary: Search Contacts
      tags: 
        - engContacts
      operationId: search-engagement-contact
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  contacts:
                    type: array
                    items:
                      $ref: "#/components/schemas/EngContact"
                  nextPageCursor:
                    type: string
              examples:
                example-1:
                  value:
                    contacts:
                      - id: 34f5b4b0b6b650c981a174b02753c390
                        firstName: Tom
                        lastName: Smith
                        jobTitle: Director of Operations
                        phones: 
                          - number: "8192223333"
                            type: "work"
                            isPrimary: true
                        emails: 
                          - address: "tom@dunder.com"
                            type: "work"
                            isPrimary: true
                        address: 
                          line1: 100 Blue Dr
                          line2: Suite 100
                          city: Scranton
                          state: Pennsylvania
                          postalCode: "281332"
                          country: USA
                        openCount: 0
                        clickCount: 3
                        replyCount: 1
                        bouncedCount: 1
                        createdTime: "2019-08-24T14:15:22Z"
                        modifiedTime: "2019-08-24T14:15:22Z"
                        associations:
                          accountId: 0dcb45e051315a6ea63b0f16e73689d9
                          actionIds:
                            - 006b4db16b6b50c981a174b02753c390
                          taskIds:
                            - 2322707bbc41577d9806400e2daa25de
                          ownerUserId: 56f653659ea9524b9e0fb0ba67e6f8a0
                        customFields: {}
                        additional: {}
                    nextPageCursor: d9806400e2daa25de2322707bbc41577
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessToken:
                  type: string
                filters:
                  type: object
                  properties: 
                    emails:
                      type: object
                      properties:
                        address:
                          type: object
                          properties:
                            equals:
                              type: string
                          required: equals
                      required: address
                  required: emails
              required:
                - accessToken
                - filters
            examples:
              example-1:
                value:
                  accessToken: string
                  filters:
                    emails:
                      address:
                        equals: fake@email.com
      description: Search contacts.
  /engagement/contact/custom-fields:
    get:
      summary: Get All Custom Fields
      tags: 
        - engCustomFields
      operationId: get-all-engagement-customFields
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  customFields:
                    type: array
                    items:
                      $ref: "#/components/schemas/EngContactCustomField"
                  nextPageCursor:
                    type: string
              examples:
                example-1:
                  value:
                    customFields:
                      - key: customField1
                        name: Custom Field
                        type: string
                        additional: {}
                    nextPageCursor: d9806400e2daa25de2322707bbc41577
      description: Get all contact custom fields
  /engagement/contact/custom-field:
    post:
      summary: Create Custom Field
      tags: 
        - engCustomFields
      operationId: post-engagement-customFields
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  key:
                    type: string
              examples:
                example-1:
                  value:
                    key: "customField1"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessToken:
                  type: string
                customField:
                  $ref: "#/components/schemas/EngContactCustomFieldCreate"
              required:
                - accessToken
                - customField
            examples:
              example-1:
                value:
                  accessToken: string
                  customField:
                    key: "customField1"
      description: Create a contact custom field
  /engagement/tasks:
    get:
      summary: Get All Tasks
      tags: 
        - engTasks
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  tasks:
                    type: array
                    items:
                      $ref: "#/components/schemas/EngTask"
                  nextPageCursor:
                    type: string
              examples:
                example-1:
                  value:
                    tasks:
                      - id: 2322707bbc41577d9806400e2daa25de
                        type: call
                        body: Call Dunder Mifflin to get a paper refill
                        dueDate: "2019-09-24T14:15:22Z"
                        status: complete
                        completedTime: "2019-08-24T14:15:22Z"
                        modifiedTime: "2019-08-24T14:15:22Z"
                        createdTime: "2019-08-24T14:15:22Z"
                        associations:
                          contactId: e5f32d4fd2115220bd20a2ccf81210ec
                          callId: 0dcb45e051315a6ea63b0f16e73689d9
                          emailId: d08f345ace24509e911a0ea8e3d2203c
                          ownerUserId: 56f653659ea9524b9e0fb0ba67e6f8a0
                        additional: {}
                    nextPageCursor: string
      operationId: get-all-engagement-tasks
      parameters:
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/allFields'
      description: Retrieve all Tasks
    parameters: []
  /engagement/task:
    get:
      summary: Get Task
      tags: 
        - engTasks
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  task:
                    $ref: "#/components/schemas/EngTask"
              examples:
                example-1:
                  value:
                    task:
                      id: 2322707bbc41577d9806400e2daa25de
                      type: call
                      body: Call Dunder Mifflin to get a paper refill
                      dueDate: "2019-09-24T14:15:22Z"
                      status: complete
                      completedTime: "2019-08-24T14:15:22Z"
                      modifiedTime: "2019-08-24T14:15:22Z"
                      createdTime: "2019-08-24T14:15:22Z"
                      associations:
                        contactId: e5f32d4fd2115220bd20a2ccf81210ec
                        callId: 0dcb45e051315a6ea63b0f16e73689d9
                        emailId: d08f345ace24509e911a0ea8e3d2203c
                        ownerUserId: 56f653659ea9524b9e0fb0ba67e6f8a0
                      additional: {}
      operationId: get-one-engagement-task
      parameters:
        - $ref: '#/components/parameters/accessToken'
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/allFields'
      description: "Retrieve a Task by Id."
    post:
      summary: Create Task
      tags: 
        - engTasks
      operationId: post-engagement-task
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                type: object
                properties:
                  id:
                    type: string
 

# --- truncated at 32 KB (167 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vessel/refs/heads/main/openapi/vessel-engagement-v1-openapi.yml