openapi: 3.1.0
info:
  title: Visible API
  description: |
    The Visible API enables you to integrate [Visible](https://visible.vc) with your tools and workflows.

    ## Schema
    All API access is over HTTPS and accessed from `https://api.visible.vc`.
    All data is sent and received as JSON.

    All timestamps and dates are returned in ISO 8601 format:
    - Date format: `YYYY-MM-DD`
    - DateTime format: `YYYY-MM-DDTHH:MM:SSZ`

    ## Rate Limiting
    You can make up to 500 API requests in a 5 minute window, this limit might change in the future.
    If the limit is exceeded the API will return a `429 Too Many Requests` HTTP status code.

    ## Finding Your Company ID

    If you don't know your company ID, you can find it in the URL when you're logged into the app.
    Navigate to any company page and look at the URL: `https://app.visible.vc/companies/{company_id}`.
  version: '1'
  contact:
    email: dev@visible.vc
    name: Visible API Support
servers:
  - url: 'https://api.visible.vc'
    description: Production server
paths:
  /metrics:
    get:
      operationId: getMetrics
      summary: List Metrics
      description: Returns a paginated collection of metrics.
      parameters:
        - name: company_id
          in: query
          description: ID of your company or fund
          required: true
          schema:
            type: string
            format: uuid
          example: cad09a10-73e8-4205-ae67-4e6156f37be8
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: filter
          in: query
          description: Filter by portfolio company profile ID (Investor product only)
          required: false
          schema:
            type: object
            properties:
              portfolio_company_profile_id:
                description: Portfolio company profile ID (`filter[portfolio_company_profile_id]={id}`)
                type: string
                format: uuid
          explode: true
          style: deepObject
      responses:
        '200':
          description: Successfully retrieved metrics
          content:
            application/json:
              schema:
                type: object
                properties:
                  metrics:
                    type: array
                    items:
                      $ref: '#/components/schemas/Metric'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                metrics:
                  - id: ec5252fe-9abc-4096-85e9-1374e70a3182
                    name: Revenue
                    frequency: monthly
                    unit: USD
                    portfolio_company_profile_id: ec5252fe-9abc-4096-85e9-1374e70a3182
                    company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                  - id: 56a1bed4-9ac4-4bd1-8533-077f3ae465c3
                    name: Headcount
                    frequency: monthly
                    unit: number
                    portfolio_company_profile_id: ec5252fe-9abc-4096-85e9-1374e70a3182
                    company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                meta:
                  total: 2
                  total_pages: 1
                  page: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Metrics
    post:
      operationId: createMetric
      summary: Create a Metric
      description: Create a new metric for a company.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metric:
                  $ref: '#/components/schemas/MetricInput'
            example:
              metric:
                name: Revenue
                frequency: monthly
                unit: USD
                company_id: c85cb869-40c0-4b8f-829a-30cdeb673ce0
      responses:
        '201':
          description: Metric successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  metric:
                    $ref: '#/components/schemas/Metric'
              example:
                metric:
                  id: 3c5728ed-a09e-4245-bb33-459b67600be3
                  name: Revenue
                  frequency: monthly
                  unit: USD
                  created_at: '2018-08-05T08:40:51.620Z'
                  company_id: c85cb869-40c0-4b8f-829a-30cdeb673ce0
                  portfolio_company_profile_id: ec5252fe-9abc-4096-85e9-1374e70a3182
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Metrics
  /data_points:
    get:
      operationId: getDataPoints
      summary: List Data Points
      description: |
        Returns a paginated collection of data points for a metric.
        Data points store the actual value of a metric for each time period.
      parameters:
        - name: metric_id
          in: query
          description: ID of a metric or an array of metric IDs
          required: true
          schema:
            oneOf:
              - type: string
                format: uuid
              - type: array
                items:
                  type: string
                  format: uuid
          example: cad09a10-73e8-4205-ae67-4e6156f37be8
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: page_size
          in: query
          description: Number of data points per page (between 1 and 100)
          required: false
          schema:
            type: integer
            default: 25
            maximum: 100
            minimum: 1
        - name: start_date
          in: query
          description: Beginning of date range (ISO 8601 date)
          required: false
          schema:
            type: string
            format: date
          example: '2025-01-01'
        - name: end_date
          in: query
          description: End of date range (ISO 8601 date)
          required: false
          schema:
            type: string
            format: date
          example: '2025-08-01'
        - name: exclude_blank
          in: query
          description: When set to 'true', excludes data points without a value
          required: false
          schema:
            type: string
            enum: ['true', 'false']
            default: 'false'
          example: 'true'
      responses:
        '200':
          description: Successfully retrieved data points
          content:
            application/json:
              schema:
                type: object
                properties:
                  data_points:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataPoint'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data_points:
                  - id: ec5252fe-9abc-4096-85e9-1374e70a3182
                    date: '2021-02-01'
                    value: '100.99'
                    metric_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                  - id: 56a1bed4-9ac4-4bd1-8533-077f3ae465c3
                    date: '2021-01-01'
                    value: '100000.00'
                    metric_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                meta:
                  total: 2
                  total_pages: 1
                  page: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Data Points
  '/metrics/{metric_id}/data_points':
    put:
      operationId: upsertDataPoints
      summary: Upsert Data Points
      description: |
        Create or update multiple data points for a metric (limited to up to 50 data points per request).

        If you don't know the metric's ID you can get it from the metric's URL in the app:
        `https://app.visible.vc/companies/{company_id}/data/metrics/{metric_id}`.
      parameters:
        - name: metric_id
          in: path
          description: ID of the metric
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data_points:
                  type: array
                  items:
                    $ref: '#/components/schemas/DataPointInput'
                  maxItems: 50
            example:
              data_points:
                - date: '2019-01-01'
                  value: '10.99'
                - date: '2019-02-01'
                  value: '20.99'
      responses:
        '200':
          description: Data points successfully upserted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data_points:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataPoint'
              example:
                data_points:
                  - id: e68ab11c-a41b-4725-976f-62542883a392
                    date: '2019-01-01'
                    value: '10.99'
                    metric_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                  - id: af692eaf-c8de-4a09-883b-1c12dbdf13ff
                    date: '2019-02-01'
                    value: '20.99'
                    metric_id: cad09a10-73e8-4205-ae67-4e6156f37be8
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Data Points
  /contacts:
    post:
      operationId: createContact
      summary: Create a Contact
      description: Create contacts in your Visible account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contact:
                  $ref: '#/components/schemas/ContactInput'
            example:
              contact:
                email: test@example.com
                company_id: c85cb869-40c0-4b8f-829a-30cdeb673ce0
                first_name: Jane
                last_name: Doe
                title: CEO
                contact_list_ids: []
      responses:
        '201':
          description: Contact successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    $ref: '#/components/schemas/Contact'
              example:
                contact:
                  id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
                  email: test@example.com
                  company_id: c85cb869-40c0-4b8f-829a-30cdeb673ce0
                  first_name: Jane
                  last_name: Doe
                  title: CEO
                  contact_list_ids: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Contacts
  /contact_lists:
    get:
      operationId: getContactLists
      summary: List Contact Lists
      description: Returns a paginated collection of contact lists.
      parameters:
        - name: company_id
          in: query
          description: ID of your company or fund
          required: true
          schema:
            type: string
            format: uuid
          example: cad09a10-73e8-4205-ae67-4e6156f37be8
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
      responses:
        '200':
          description: Successfully retrieved contact lists
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact_lists:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactList'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                contact_lists:
                  - id: ec5252fe-9abc-4096-85e9-1374e70a3182
                    name: Investors
                    company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                  - id: 56a1bed4-9ac4-4bd1-8533-077f3ae465c3
                    name: Team
                    company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                meta:
                  total: 2
                  total_pages: 1
                  page: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Contact Lists
  /portfolio_company_profiles:
    get:
      operationId: getPortfolioCompanyProfiles
      summary: List Portfolio Company Profiles
      description: Returns a paginated collection of portfolio company profiles.
      parameters:
        - name: company_id
          in: query
          description: ID of your company or fund
          required: true
          schema:
            type: string
            format: uuid
          example: cad09a10-73e8-4205-ae67-4e6156f37be8
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
      responses:
        '200':
          description: Successfully retrieved portfolio company profiles
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio_company_profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/PortfolioCompanyProfile'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                portfolio_company_profiles:
                  - id: ec5252fe-9abc-4096-85e9-1374e70a3182
                    name: Portfolio company 1
                    website_url: https://www.example.com
                    currency: USD
                    primary_contact_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
                    created_at: '2023-02-01T22:08:21.175Z'
                    company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                  - id: 56a1bed4-9ac4-4bd1-8533-077f3ae465c3
                    name: Portfolio company 2
                    created_at: '2022-02-01T22:08:21.175Z'
                    company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                    primary_contact_id: null
                    currency: null
                    website_url: null
                meta:
                  total: 2
                  total_pages: 1
                  page: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Portfolio Company Profiles
    post:
      operationId: createPortfolioCompanyProfile
      summary: Create a Portfolio Company Profile
      description: Create a new portfolio company profile in your account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                portfolio_company_profile:
                  $ref: '#/components/schemas/PortfolioCompanyProfileInput'
            example:
              portfolio_company_profile:
                name: Portfolio company 1
                website_url: https://www.example.com
                currency: USD
                primary_contact_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
                company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
      responses:
        '201':
          description: Portfolio company profile successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio_company_profile:
                    $ref: '#/components/schemas/PortfolioCompanyProfile'
              example:
                portfolio_company_profile:
                  id: ec5252fe-9abc-4096-85e9-1374e70a3182
                  name: Portfolio company 1
                  website_url: https://www.example.com
                  currency: USD
                  primary_contact_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
                  created_at: '2023-02-01T22:08:21.175Z'
                  company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Portfolio Company Profiles
  '/portfolio_company_profiles/{id}':
    put:
      operationId: updatePortfolioCompanyProfile
      summary: Update a Portfolio Company Profile
      description: Update an existing portfolio company profile.
      parameters:
        - name: id
          in: path
          description: ID of the portfolio company profile to update
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                portfolio_company_profile:
                  $ref: '#/components/schemas/PortfolioCompanyProfileInput'
            example:
              portfolio_company_profile:
                name: Updated portfolio company name
                website_url: https://updated.example.com
                currency: EUR
                company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                primary_contact_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
      responses:
        '200':
          description: Portfolio company profile successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio_company_profile:
                    $ref: '#/components/schemas/PortfolioCompanyProfile'
              example:
                portfolio_company_profile:
                  id: ec5252fe-9abc-4096-85e9-1374e70a3182
                  name: Updated portfolio company name
                  website_url: https://updated.example.com
                  currency: EUR
                  primary_contact_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
                  created_at: '2023-02-01T22:08:21.175Z'
                  company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Portfolio Company Profiles
  /portfolio_notes:
    get:
      operationId: getPortfolioNotes
      summary: List Portfolio Notes
      description: |
        Returns a paginated collection of portfolio notes for a portfolio company profile.
      parameters:
        - name: portfolio_company_profile_id
          in: query
          description: ID of the portfolio company profile to filter by
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
      responses:
        '200':
          description: Successfully retrieved portfolio notes
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio_notes:
                    type: array
                    items:
                      $ref: '#/components/schemas/PortfolioNote'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                portfolio_notes:
                  - name: A note
                    portfolio_company_profile_id: ec5252fe-9abc-4096-85e9-1374e70a3182
                    plaintext_content: This is a note
                    created_at: '2025-02-01T22:08:21.175Z'
                meta:
                  total: 1
                  total_pages: 1
                  page: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Portfolio Notes
  '/portfolio_notes/{id}':
    get:
      operationId: getPortfolioNote
      summary: Get Portfolio Note
      description: |
        Returns a single portfolio note by ID.
      parameters:
        - name: id
          in: path
          description: ID of the portfolio note
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved portfolio note
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio_note:
                    $ref: '#/components/schemas/PortfolioNote'
              example:
                portfolio_note:
                  name: A note
                  portfolio_company_profile_id: ec5252fe-9abc-4096-85e9-1374e70a3182
                  plaintext_content: This is a note
                  created_at: '2025-02-01T22:08:21.175Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Portfolio Notes
  /portfolio_properties:
    get:
      operationId: getPortfolioProperties
      summary: List Portfolio Properties
      description: |
        Returns a paginated collection of portfolio properties for a company.

        Portfolio properties define the custom fields that can be used to store data about portfolio companies. This endpoint also returns auto-calculated investment properties.
      parameters:
        - name: company_id
          in: query
          description: ID of your company or fund
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
      responses:
        '200':
          description: Successfully retrieved portfolio properties
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio_properties:
                    type: array
                    items:
                      $ref: '#/components/schemas/PortfolioProperty'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                portfolio_properties:
                  - id: ec5252fe-9abc-4096-85e9-1374e70a3182
                    name: 'Industry'
                    data_type: 'select'
                    company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                  - id: f1d234a8-2bcd-4567-89ef-3c45d6789012
                    name: 'Employee Count'
                    data_type: 'number'
                    company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                  - id: 12345678-9abc-def0-1234-56789abcdef0
                    name: 'Total Invested'
                    data_type: 'number'
                    company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                meta:
                  total: 3
                  total_pages: 1
                  page: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Portfolio Properties
  /portfolio_property_values:
    get:
      operationId: getPortfolioPropertyValues
      summary: List Portfolio Property Values
      description: |
        Returns a paginated collection of portfolio property values for a portfolio company profile.

        Portfolio property values contain the actual data for custom properties defined for portfolio companies.
        This endpoint also returns values for auto-calculated investment properties.
      parameters:
        - name: portfolio_company_profile_id
          in: query
          description: ID of the portfolio company profile to filter by
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
      responses:
        '200':
          description: Successfully retrieved portfolio property values
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio_property_values:
                    type: array
                    items:
                      $ref: '#/components/schemas/PortfolioPropertyValue'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                portfolio_property_values:
                  - id: ec5252fe-9abc-4096-85e9-1374e70a3182
                    value: 'Sample text value'
                    portfolio_property_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                    portfolio_company_profile_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
                  - id: f1d234a8-2bcd-4567-89ef-3c45d6789012
                    value: '123.45'
                    portfolio_property_id: e2f345b9-3cde-5678-90ab-4d56e789f123
                    portfolio_company_profile_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
                meta:
                  total: 2
                  total_pages: 1
                  page: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Portfolio Property Values
    put:
      operationId: upsertPortfolioPropertyValue
      summary: Upsert a Portfolio Property Value
      description: |
        Create or update a single portfolio property value for a portfolio company profile.

        Pass the portfolio property and portfolio company profile identifiers along with the value, and the API will either create a new record
        or update the existing one if it already exists for that `(portfolio_property_id, portfolio_company_profile_id)` pair.

        For properties with `data_type` of `select` or `multiselect`, you must send option IDs instead of option labels:
        - For `select` properties, use `portfolio_property_option_id` with the UUID of a single option.
        - For `multiselect` properties, use `portfolio_property_option_ids` with an array of option UUIDs.
        For all other data types (string, text, url, number, date, rich_text) use the generic `value` field.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                portfolio_property_value:
                  allOf:
                    - type: object
                      required:
                        - portfolio_property_id
                        - portfolio_company_profile_id
                      properties:
                        portfolio_property_id:
                          description: ID of the portfolio property this value belongs to
                          type: string
                          format: uuid
                        portfolio_company_profile_id:
                          description: ID of the portfolio company profile this value belongs to
                          type: string
                          format: uuid
                    - oneOf:
                        - type: object
                          title: Text/Number/Date
                          required:
                            - value
                          properties:
                            value:
                              description: Raw value to set for the property. Parsed into the appropriate typed column based on the property's data type.
                              type: string
                        - type: object
                          title: Select
                          required:
                            - portfolio_property_option_id
                          properties:
                            portfolio_property_option_id:
                              description: ID of the selected option for `select` properties. Mutually exclusive with `value`.
                              type: string
                              format: uuid
                        - type: object
                          title: Multiselect
                          required:
                            - portfolio_property_option_ids
                          properties:
                            portfolio_property_option_ids:
                              description: IDs of the selected options for `multiselect` properties. Mutually exclusive with `value`.
                              type: array
                              items:
                                type: string
                                format: uuid
            examples:
              text_value:
                summary: Text/number/date property using `value`
                value:
                  portfolio_property_value:
                    value: 'Some text value'
                    portfolio_property_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                    portfolio_company_profile_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
              select_value:
                summary: Select property using `portfolio_property_option_id`
                value:
                  portfolio_property_value:
                    portfolio_property_option_id: 9d243039-85e2-4396-881f-7e971a3200c4
                    portfolio_property_id: e2f345b9-3cde-5678-90ab-4d56e789f123
                    portfolio_company_profile_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
              multiselect_value:
                summary: Multiselect property using `portfolio_property_option_ids`
                value:
                  portfolio_property_value:
                    portfolio_property_option_ids:
                      - 9d243039-85e2-4396-881f-7e971a3200c4
                      - a1395c0e-30dc-428b-883b-42455c84e6c2
                    portfolio_property_id: c4e567f8-9abc-0123-4567-89def0123456
                    portfolio_company_profile_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
      responses:
        '201':
          description: Portfolio property value successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio_property_value:
                    $ref: '#/components/schemas/PortfolioPropertyValue'
        '200':
          description: Portfolio property value successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio_property_value:
                    $ref: '#/components/schemas/PortfolioPropertyValue'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Portfolio Property Values
  /portfolio_property_options:
    get:
      operationId: getPortfolioPropertyOptions
      summary: List Portfolio Property Options
      description: |
        Returns the list of options for a given portfolio property.

        Options are used by `select` and `multiselect` portfolio properties to define the allowed values.
      parameters:
        - name: portfolio_property_id
          in: query
          description: ID of the portfolio property whose options you want to list
          required: true
          schema:
            type: string
            format: uuid
        - name: label
          in: query
          description: Optional label to filter options by (case-insensitive match)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved portfolio property options
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio_property_options:
                    type: array
                    items:
                      $ref: '#/components/schemas/PortfolioPropertyOption'
              example:
                portfolio_property_options:
                  - id: ec5252fe-9abc-4096-85e9-1374e70a3182
                    label: 'Option A'
                    portfolio_property_id: cad09a10-73e8-4205-ae67-4e6156f37be8
                  - id: f1d234a8-2bcd-4567-89ef-3c45d6789012
                    label: 'Option B'
                    portfolio_property_id: cad09a10-73e8-4205-ae67-4e6156f37be8
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Portfolio Property Options
components:
  schemas:
    Metric:
      type: object
      properties:
        id:
          description: Unique identifier for the metric
          type: string
          format: uuid
        name:
          description: Name of the metric
          type: string
        frequency:
          description: Frequency of the metric reporting
          type: string
          enum:
            - daily
            - weekly
            - monthly
            - quarterly
        unit:
          description: 'Unit of measurement (number, percent, or ISO4217 currency code)'
          type: string
        portfolio_company_profile_id:
          description: ID of the associated portfolio company profile
          type:
            - string
            - 'null'
          format: uuid
        company_id:
          description: ID of the company or fund
          type: string
          format: uuid
        created_at:
          description: When the metric was created
          type: string
          format: date-time
      examples:
        - id: ec5252fe-9abc-4096-85e9-1374e70a3182
          name: Revenue
          frequency: monthly
          unit: USD
          portfolio_company_profile_id: ec5252fe-9abc-4096-85e9-1374e70a3182
          company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
      required:
        - id
        - name
        - frequency
        - unit
        - company_id
    MetricInput:
      type: object
      properties:
        name:
          description: Name of the metric
          type: string
        frequency:
          description: Frequency of the metric reporting
          type: string
          enum:
            - daily
            - weekly
            - monthly
            - quarterly
        unit:
          description: 'Unit of measurement (number, percent, or ISO4217 currency code)'
          type: string
        company_id:
          description: ID of the company or fund
          type: string
          format: uuid
      examples:
        - name: Revenue
          frequency: monthly
          unit: USD
          company_id: c85cb869-40c0-4b8f-829a-30cdeb673ce0
      required:
        - name
        - frequency
        - unit
        - company_id
    DataPoint:
      type: object
      properties:
        id:
          description: Unique identifier for the data point
          type: string
          format: uuid
        date:
          description: Date for this data point (ISO 8601 format)
          type: string
          format: date
        value:
          description: Value of the metric for this date (stored as string for precision)
          type: string
        metric_id:
          description: ID of the associated metric
          type: string
          format: uuid
      examples:
        - id: ec5252fe-9abc-4096-85e9-1374e70a3182
          date: '2021-02-01'
          value: '100.99'
          metric_id: cad09a10-73e8-4205-ae67-4e6156f37be8
      required:
        - id
        - date
        - value
        - metric_id
    DataPointInput:
      type: object
      properties:
        date:
          description: Date for this data point (ISO 8601 format)
          type: string
          format: date
        value:
          description: Value of the metric for this date
          type: string
      examples:
        - date: '2019-01-01'
          value: '10.99'
      required:
        - date
        - value
    Contact:
      type: object
      properties:
        id:
          description: Unique identifier for the contact
          type: string
          format: uuid
        email:
          description: Email address of the contact
          type: string
          format: email
        company_id:
          description: ID of the company or fund
          type: string
          format: uuid
        first_name:
          description: First name of the contact
          type:
            - string
            - 'null'
        last_name:
          description: Last name of the contact
          type:
            - string
            - 'null'
        title:
          description: Job title of the contact
          type:
            - string
            - 'null'
        contact_list_ids:
          description: Array of contact list IDs this contact belongs to
          type: array
          items:
            type: string
            format: uuid
      examples:
        - id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
          email: test@example.com
          company_id: c85cb869-40c0-4b8f-829a-30cdeb673ce0
          first_name: Jane
          last_name: Doe
          title: CEO
          contact_list_ids: []
      required:
        - id
        - email
        - company_id
        - contact_list_ids
    ContactInput:
      type: object
      properties:
        email:
          description: Email address of the contact
          type: string
          format: email
        company_id:
          description: ID of the company or fund
          type: string
          format: uuid
        first_name:
          description: First name of the contact
          type: string
        last_name:
          description: Last name of the contact
          type: string
        title:
          description: Job title of the contact
          type: string
        contact_list_ids:
          description: Array of contact list IDs this contact should belong to
          type: array
          items:
            type: string
            format: uuid
          default: []
      examples:
        - email: test@example.com
          company_id: c85cb869-40c0-4b8f-829a-30cdeb673ce0
          first_name: Jane
          last_name: Doe
          title: CEO
          contact_list_ids: []
      required:
        - email
        - company_id
    ContactList:
      type: object
      properties:
        id:
          description: Unique identifier for the contact list
          type: string
          format: uuid
        name:
          description: Name of the contact list
          type: string
        company_id:
          description: ID of the company or fund
          type: string
          format: uuid
      examples:
        - id: ec5252fe-9abc-4096-85e9-1374e70a3182
          name: Investors
          company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
      required:
        - id
        - name
        - company_id
    PortfolioCompanyProfileInput:
      type: object
      properties:
        name:
          description: Unique name of the portfolio company profile
          type: string
        website_url:
          description: Website URL of the portfolio company profile
          type:
            - string
            - 'null'
          format: uri
        currency:
          description: Currency code (ISO 4217) for the portfolio company profile
          type:
            - string
            - 'null'
        company_id:
          description: ID of the company or fund
          type: string
          format: uuid
        primary_contact_id:
          description: ID of the primary contact for the portfolio company profile
          type:
            - string
            - 'null'
          format: uuid
      examples:
        name: Portfolio company 1
        website_url: https://www.example.com
        currency: USD
        company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
        primary_contact_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
      required:
        - name
        - company_id
    PortfolioCompanyProfile:
      type: object
      properties:
        id:
          description: Unique identifier for the portfolio company profile
          type: string
          format: uuid
        name:
          description: Unique name of the portfolio company profile
          type: string
        website_url:
          description: Website URL of the portfolio company profile
          type:
            - string
            - 'null'
          format: uri
        currency:
          description: Currency code (ISO 4217) for the portfolio company profile
          type:
            - string
            - 'null'
        created_at:
          description: When the portfolio company profile was created
          type: string
          format: date-time
        company_id:
          description: ID of the company or fund
          type: string
          format: uuid
        primary_contact_id:
          description: ID of the primary contact for the portfolio company profile
          type:
            - string
            - 'null'
          format: uuid
      examples:
        - id: ec5252fe-9abc-4096-85e9-1374e70a3182
          name: Portfolio company 1
          website_url: https://www.example.com
          currency: USD
          created_at: '2023-02-01T22:08:21.175Z'
          company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
          primary_contact_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
      required:
        - id
        - name
        - company_id
        - website_url
        - currency
        - created_at
        - primary_contact_id
    PaginationMeta:
      type: object
      properties:
        total:
          description: Total number of items across all pages
          type: integer
        total_pages:
          description: Total number of pages
          type: integer
        page:
          description: Current page number
          type: integer
      examples:
        - total: 2
          total_pages: 1
          page: 1
      required:
        - total
        - total_pages
        - page
    PortfolioNote:
      type: object
      properties:
        name:
          description: Name/title of the portfolio note
          type: string
        portfolio_company_profile_id:
          description: ID of the associated portfolio company profile
          type: string
          format: uuid
        plaintext_content:
          description: Plaintext content of the note
          type: string
        created_at:
          description: When the portfolio note was created
          type: string
          format: date-time
      examples:
        - name: A note
          portfolio_company_profile_id: ec5252fe-9abc-4096-85e9-1374e70a3182
          plaintext_content: This is a note
      required:
        - name
        - portfolio_company_profile_id
        - plaintext_content
    PortfolioProperty:
      type: object
      properties:
        id:
          description: Unique identifier for the portfolio property
          type: string
          format: uuid
        name:
          description: Name of the portfolio property
          type: string
        data_type:
          description: Data type of the property
          type: string
          enum:
            - number
            - date
            - boolean
            - select
            - multiselect
            - string
            - text
            - url
        company_id:
          description: ID of the company or fund
          type: string
          format: uuid
      examples:
        - id: ec5252fe-9abc-4096-85e9-1374e70a3182
          name: 'Industry'
          data_type: 'select'
          company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
        - id: f1d234a8-2bcd-4567-89ef-3c45d6789012
          name: 'Employee Count'
          data_type: 'number'
          company_id: cad09a10-73e8-4205-ae67-4e6156f37be8
      required:
        - id
        - name
        - data_type
        - company_id
    PortfolioPropertyValue:
      type: object
      properties:
        id:
          description: Unique identifier for the portfolio property value
          type: string
          format: uuid
        value:
          description: The formatted value based on the property type
          type:
            - string
            - number
            - boolean
            - array
            - 'null'
        portfolio_property_id:
          description: ID of the associated portfolio property
          type: string
          format: uuid
        portfolio_company_profile_id:
          description: ID of the associated portfolio company profile
          type: string
          format: uuid
        portfolio_property_option_id:
          description: ID of the selected option when the associated property has `data_type` of `select`.
          type:
            - string
            - 'null'
          format: uuid
        portfolio_property_option_ids:
          description: IDs of the selected options when the associated property has `data_type` of `multiselect`.
          type: array
          items:
            type: string
            format: uuid
      examples:
        - id: ec5252fe-9abc-4096-85e9-1374e70a3182
          value: 'Sample text value'
          portfolio_property_id: cad09a10-73e8-4205-ae67-4e6156f37be8
          portfolio_company_profile_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
        - id: f1d234a8-2bcd-4567-89ef-3c45d6789012
          value: '123.45'
          portfolio_property_id: e2f345b9-3cde-5678-90ab-4d56e789f123
          portfolio_company_profile_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
        - id: bc5252fe-9abc-4096-85e9-1374e70a3182
          value: ['Option 1', 'Option 2']
          portfolio_property_id: c4e567f8-9abc-0123-4567-89def0123456
          portfolio_company_profile_id: b9bd9bb5-9b12-48bb-ae93-cdd2eba9af98
          portfolio_property_option_ids: ['9d243039-85e2-4396-881f-7e971a3200c4', 'a1395c0e-30dc-428b-883b-42455c84e6c2']
      required:
        - id
        - portfolio_property_id
        - portfolio_company_profile_id
    PortfolioPropertyOption:
      type: object
      properties:
        id:
          description: Unique identifier for the portfolio property option
          type: string
          format: uuid
        label:
          description: Human-readable label for the option
          type: string
        portfolio_property_id:
          description: ID of the portfolio property this option belongs to
          type: string
          format: uuid
      examples:
        - id: ec5252fe-9abc-4096-85e9-1374e70a3182
          label: 'Option A'
          portfolio_property_id: cad09a10-73e8-4205-ae67-4e6156f37be8
        - id: f1d234a8-2bcd-4567-89ef-3c45d6789012
          label: 'Option B'
          portfolio_property_id: cad09a10-73e8-4205-ae67-4e6156f37be8
      required:
        - id
        - label
        - portfolio_property_id
    Error:
      type: object
      description: Error response envelope wrapping an array of error items
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
      required:
        - errors
    ErrorItem:
      type: object
      description: Single error item. Different error types can include different fields.
      properties:
        type:
          description: Machine-readable error type
          type: string
          example: parameter_invalid
        field:
          description: The related field, if applicable
          type: string
        message:
          description: Human-readable error message
          type: string
  responses:
    BadRequest:
      description: Bad Request - The request is invalid or malformed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - type: parameter_invalid
                field: filter
                message: must be an object
    Unauthorized:
      description: Unauthorized - Invalid or missing authentication token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - type: unauthorized
    NotFound:
      description: Not Found - The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - type: record_missing
    UnprocessableEntity:
      description: Unprocessable Entity - The request is valid but contains semantic errors
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - type: attribute_invalid
                field: value
                message: required
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - type: rate_limit_exceeded
    Forbidden:
      description: Forbidden - The authenticated user does not have access to the requested resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - type: forbidden
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Each API request must include an access token in the `Authorization` HTTP header using Bearer authentication, use the format `Bearer <your-token>`.

        A token is issued to a specific Visible user and will have access to the same companies the user does.

        To obtain an access token contact us at [dev@visible.vc](mailto:dev@visible.vc?Subject=API%20access%20token%20request).
tags:
  - name: Metrics
    description: Operations related to metrics management
  - name: Data Points
    description: Operations related to metric data points
  - name: Contacts
    description: Operations related to contact management
  - name: Contact Lists
    description: Operations related to contact list management
  - name: Portfolio Company Profiles
    description: |
      **Investor product only**. Operations related to portfolio company profiles. A portfolio company profile represents a single company in your Portfolio section.
  - name: Portfolio Notes
    description: |
      **Investor product only**. Operations related to portfolio company notes.
  - name: Portfolio Properties
    description: |
      **Investor product only.**
      Portfolio properties define the custom fields that can be used to store data about portfolio companies.
      This endpoint also returns auto-calculated investment properties.
  - name: Portfolio Property Values
    description: |
      **Investor product only.**
      Portfolio property values contain the actual data for custom properties defined for portfolio companies.
      This endpoint also returns auto-calculated investment properties.
security:
  - bearerAuth: []