> ## Documentation Index > Fetch the complete documentation index at: https://api.tryspecter.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a new company list > **What it does** Creates a new list of companies that is shared with the API and returns the new list’s id. **Why you'd use it** Programmatically build and maintain sourcing/diligence shortlists (e.g., thesis- or region-based cohorts such as “European B2B DeepTech”) **Key behaviors** - Add companies at creation by passing their company IDs, or add them later via the PATCH endpoint for that list id. - The list owner will be the first team admin added to the account. - You cannot create two lists with the same name. List names must be unique; if a name already exists, rename the existing list or choose a new name. ## OpenAPI ````yaml /api-ref/bundle_api.yaml post /lists/companies openapi: 3.0.0 info: title: Specter API termsOfService: https://tryspecter.com/terms/ contact: name: API support email: api-support@tryspecter.com version: 1.0.0 servers: - description: Production url: https://app.tryspecter.com/api/v1 security: - ApiKeyAuth: [] tags: - name: Enrichment description: > Endpoints which can be used to query for data and, if the data is not found request that it be retrieved by Specter systems. - name: Companies description: > Endpoints that provide the most up to date information about all the companies in our data set. Giving the ability to query by a specific company id, or using a keyword such as the domain. This also allows us to enrich the data about a company if we either do not have it or it is older than expected, which means you always have the most up-to-date information possible. - name: People description: > Endpoints that expose Specter people records — profile data and contact details — for a known person ID. - name: Investors description: > Endpoints that expose Specter investor records — profile, activity, targeting, funds, portfolio companies, and the funding rounds they have participated in — for a known investor ID. - name: Talent and Interest Signals description: > Endpoints for retrieving Specter Talent Signals and Investor Interest Signals by ID. - name: News Signals description: > Company-level news signals generated from articles monitored by Specter. Each signal represents a single classified company mention within an article and includes a summary of the newsworthy update (such as funding, deals, revenue, profitability, or traction) along with an assigned importance score. - name: Revenue Signals description: > Revenue and profitability observations for companies, derived from news coverage and public filings. Each signal captures one data point — the revenue or profitability metric, the year it refers to, the source, and the company it is attributed to. - name: Transactions description: > Endpoints that expose transaction detail — funding rounds, acquisitions, and IPOs — by ID. - name: Company Lists description: > Create, query and maintain lists of companies that are of particular interest. The endpoints here allow you to interrogate and maintain those lists using a programmatic interface. - name: People Lists description: > Create, query and maintain lists of people that are of particular interest. The endpoints here allow you to interrogate and maintain those lists using a programmatic interface. - name: Investor Lists description: > Create, query and maintain lists of investors that are of particular interest. The endpoints here allow you to interrogate and maintain those lists using a programmatic interface. - name: Network description: > Endpoints for accessing your team's LinkedIn network - the people and companies your teammates are connected to. - name: Saved Searches description: > Manage searches that have been saved via `tryspecter.com`. These endpoints are useful to programmatically list and delete saved searches. To update a search the UI should be used at `tryspecter.com`. - name: Company Saved Searches description: > Query and get results for company searches that have been saved via `tryspecter.com`. These endpoints are useful to programmatically get results and information for a search. To update a search the UI should be used at `tryspecter.com`. - name: People Saved Searches description: > Query and get results for people searches that have been saved via `tryspecter.com` or via the API. These endpoints are useful to programmatically get results and information for a search. To update a search the UI should be used at `tryspecter.com`. - name: Investor Saved Searches description: > Query and inspect saved investor searches — metadata (name, match counts) and paginated results — from searches saved via `tryspecter.com` or shared with the API. - name: Talent Signals Saved Searches description: > Query and get results for Talent Signals searches that have been saved via `tryspecter.com`. - name: Investor Interest Saved Searches description: > Query and get results for Investor Interest Signals searches that have been saved via `tryspecter.com`. - name: Organization description: > Endpoints for accessing your organization's members and org-level resources. - name: Customer Data description: > Retrieve a log of API calls made by your organization. Useful for auditing usage, debugging integrations, and monitoring activity. paths: /lists/companies: post: tags: - Company Lists summary: Create a new company list description: > **What it does** Creates a new list of companies that is shared with the API and returns the new list’s id. **Why you'd use it** Programmatically build and maintain sourcing/diligence shortlists (e.g., thesis- or region-based cohorts such as “European B2B DeepTech”) **Key behaviors** - Add companies at creation by passing their company IDs, or add them later via the PATCH endpoint for that list id. - The list owner will be the first team admin added to the account. - You cannot create two lists with the same name. List names must be unique; if a name already exists, rename the existing list or choose a new name. operationId: create-new-companies-list requestBody: required: true content: application/json: schema: description: Name and list of companies to add to the new list type: object required: - name properties: name: type: string description: Name of the list to create example: My list company_ids: type: array items: type: string description: ID of company being added example: 5e3a7f2b0aa7a3270a55f2a7 is_public: type: boolean description: Whether the list is shared with other users in the team example: true responses: '201': description: The ID of the list that was created content: application/json: schema: type: string description: ID of the list example: a1d2434c-e089-480a-8a27-9909d2f558b4 format: uuid '400': $ref: '#/components/responses/NoAdmin' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimits' components: responses: NoAdmin: description: Operation can't be done with no team admin content: application/json: schema: type: object properties: errorCode: type: string description: The type of error. message: type: string examples: no-team-admin: summary: No admin for the team value: errorCode: NO_TEAM_ADMIN message: > Cannot process request without a team admin, please request a team admin is added to your account. Unauthorized: description: Unauthorized content: application/json: schema: oneOf: - $ref: '#/components/schemas/ApiKeyMissing' - $ref: '#/components/schemas/ApiKeyNotValid' Forbidden: description: Forbidden - There is no permissions to use the endpoint content: application/json: schema: type: object properties: errorCode: description: NOT_PERMITTED type: string example: NOT_PERMITTED message: type: string description: You do not have permission to access this resource. example: You do not have permission to access this resource. required: - errorCode - message RateLimits: description: Too Many Requests - API Rate limit exceeded content: application/json: schema: type: object required: - errorCode - message properties: errorCode: type: string description: RATE_LIMITED message: type: string description: You have been rate-limited headers: X-RateLimit-Limit: schema: type: integer description: The total rate limit allowed for this endpoint X-RateLimit-Remaining: schema: type: integer description: The number of requests remaining X-RateLimit-Reset: schema: type: number format: float description: The number of seconds until the rate limit resets schemas: ApiKeyMissing: properties: errorCode: description: API_KEY_MISSING example: API_KEY_MISSING type: string message: description: No API Key was presented on the header X-API-KEY example: No API Key was presented on the header X-API-KEY type: string ApiKeyNotValid: properties: errorCode: description: API_KEY_NOT_VALID example: API_KEY_NOT_VALID type: string message: description: API key present, but not valid example: API key present, but not valid type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key ````