Authentication

Each public endpoint requires API key authentication.

Include your API key in the request headers:

x-api-key: YOUR_API_KEY

Get Pipelines and Stages

Returns the list of pipelines and their associated stages available to the authenticated account. This endpoint is typically used to retrieve pipeline and stage IDs required for other API requests, along with their human-friendly names as displayed in the UI.

HTTP Request

GET https://api.listalpha.com/v1/deals/pipelines-stages

Response

Success — 200 OK

The response contains an array of pipelines. Each pipeline includes its stages.

{
  "pipelines": [
    {
      "id": "string",
      "name": "string",
      "stages": [
        {
          "id": "string",
          "name": "string"
        }
      ]
    }
  ]
}

Response Fields

Field Type Description
pipelines array List of pipelines available to the account
pipelines[].id string Unique identifier of the pipeline (used in other API requests)
pipelines[].name string Human-friendly pipeline name as shown in the UI
pipelines[].stages array List of stages belonging to the pipeline
pipelines[].stages[].id string Unique identifier of the stage (used in other API requests)
pipelines[].stages[].name string Human-friendly stage name as shown in the UI

Error Responses

HTTP Status Description
401 Unauthorized API key is missing or invalid
403 Forbidden API key does not have sufficient permissions

Get Deal Custom Fields

Returns the list of custom fields available for deals. This endpoint is used to discover which custom fields can be read or written via the public API, along with their human-friendly labels and supported data types.

Each field includes a stable fieldId that should be used when referencing custom fields in other API requests. The label matches the name shown in the ListAlpha UI.

HTTP Request

GET https://api.listalpha.com/v1/deals/custom-fields

Response

Success — 200 OK

{
  "fields": [
    {
      "fieldId": "string",
      "label": "string"
    }
  ]
}

Response Fields

Field Type Description
fields array List of deal custom fields available via the API
fields[].fieldId string Unique identifier of the custom field (used in other API requests)
fields[].label string Human-friendly field name as shown in the UI

Error Responses

HTTP Status Description
401 Unauthorized API key is missing or invalid
403 Forbidden API key does not have sufficient permissions

List Deals

Returns a paginated list of deals visible to the authenticated account. Supports full-text search and filtering by pipeline/stage (use GET /v1/deals/pipelines-stages).

Deals include core metadata (pipeline/stage, timestamps, tags, comments, company info) plus a fields object containing custom field values, keyed by fieldId. To discover available custom fields and their labels/types, use GET /v1/deals/custom-fields.

HTTP Request

GET https://api.listalpha.com/v1/deals

Query Parameters

Parameter Type Required Description
search string No Full-text search query
stages string[] No Filter deals by stage IDs (repeatable query param)
pipelines string[] No Filter deals by pipeline IDs (repeatable query param)
limit number No Page size. max 100
offset number No Pagination offset. Default 0, max 1,000,000

Array query format: Array filters are provided as repeated query parameters:
stages=due-diligence&stages=execution
pipelines=pl_123&pipelines=pl_456

Response

Success — 200 OK

{
  "deals": [
    {
      "id": "string",
      "company": {
        "name": "string",
        "url": "string"
      },
      "comments": "string",
      "tags": ["string"],
      "creatorId": "string",
      "pipelineId": "string",
      "stageId": "string",
      "addedAt": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "fields": {
        "fieldId_1": "any",
        "fieldId_2": "any"
      }
    }
  ]
}

Response Fields

Root Object

Field Type Description
deals DealEntity[] List of deals matching the query

DealEntity

Field Type Description
id string Unique identifier of the deal
company object Associated company information
company.name string Company name
company.url string Public company website URL (internal .listalpha URLs are not returned)
comments string Free-text comments attached to the deal
tags string[] List of tags assigned to the deal
creatorId string ID of the user who created the deal
pipelineId string ID of the pipeline the deal belongs to
stageId string ID of the current stage of the deal
addedAt string Date when the deal was added (ISO 8601 timestamp)
createdAt string Date when the deal was created (ISO 8601 timestamp)
updatedAt string Date when the deal was last updated (ISO 8601 timestamp)
fields object Custom field values keyed by custom field ID

Custom Field Value Formats

DealEntity.fields contains values with these formats (by field type):

Field Type Value Type Notes
Input string —
Text area string —
Dropdown string Must be one of configured options
Multi-select string[] Each must be one of configured options
Datepicker string (ISO date) Example: 2025-01-31
Checkbox boolean true / false
Formula string Returned as a computed string value
Attachment string[] Array of file URLs
Company string Company ID
Companies string[] Array of company IDs
Deal string Deal ID
User list string[] Array of user IDs

Error Responses

HTTP Status Description
400 Bad Request Query parameters failed validation (e.g. invalid type, out-of-range limit/offset)
401 Unauthorized API key is missing or invalid
403 Forbidden API key does not have sufficient permissions

Create Deal

Creates a new deal in the specified pipeline and stage. In addition to core deal properties, this endpoint accepts custom field values.

The deal creator (owner) is automatically set to the owner of the API key.

HTTP Request

POST https://api.listalpha.com/v1/deals

Request Body

{
  "company": {
    "name": "string",
    "url": "string"
  },
  "pipelineId": "string",
  "stageId": "string",
  "dealComment": "string",
  "fields": {
    "customFieldId_1": "any",
    "customFieldId_2": "any"
  }
}

Request Fields

Field Type Required Description
company object No Company information associated with the deal
company.name string No Company name (deal name)
company.url string No Public company website URL
pipelineId string Yes ID of the pipeline where the deal will be created
stageId string Yes ID of the stage within the pipeline
dealComment string No Comment for the deal
fields object No Custom field values keyed by custom field ID

Supported Field Types

The first version of the public API supports the following custom field types for POST and PATCH endpoints:

UI Field Type API Data Type Description
Input string Single-line text value
Text area string Multi-line text value
Dropdown string One value selected from predefined options
Multi-select string[] Multiple values selected from predefined options
Date picker string (ISO 8601 date) Date value in ISO format (e.g. 2025-01-31, 2026-01-25T10:17:19.051Z)
Checkbox boolean true or false

Update Deal

Update deal. All properties optional.

HTTP Request

PATCH https://api.listalpha.com/v1/deals

Request Body

{
  "company": {
    "name": "string",
    "url": "string"
  },
  "stageId": "string",
  "dealComment": "string",
  "fields": {
    "customFieldId_1": "any",
    "customFieldId_2": "any"
  }
}

Request Fields

Field Type Required Description
company object No Company information associated with the deal
company.name string No Company name (deal name)
company.url string No Public company website URL
stageId string No ID of the stage within the pipeline
dealComment string No Comment for the deal
fields object No Custom field values keyed by custom field ID

Supported Field Types: The field types are the same as in the POST endpoint.

Platform

Contacts / relationshipsDeal flow managementInvestor relationsDeal originationCompany research

Markets

Private EquityVenture Capital

Company

Talk to salesPricingSecurity & TrustCompare ListAlphaInsights
Terms and conditionsPrivacy PolicyAccount removal

© 2025 All rights reserved

When you visit or interact with our sites, services or tools, we or our authorised service providers may use cookies for storing information to help provide you with a better, faster and safer experience and for marketing purposes.

By using this website, you agree to the storing of cookies on your device to enhance site navigation, analyze site usage, and assist in our marketing efforts. View our Privacy Policy for more information.

DenyAccept All