Manage Contact Lists with Smart Lists

What Are Smart Lists?

Smart Lists are organized contact databases that live inside your Parallel AI workspace. They serve as the central place to store, manage, and segment the leads your agents capture and the audiences your sequences target. You can use Smart Lists to:

Store agent-captured leads automatically when aiContactCaptureEnabled is enabled on an agent
Segment your audience into targeted groups (e.g., trial users, enterprise prospects, churned customers)
Drive outreach sequences by linking a list to an automated email or SMS campaign
Import and manage contacts via the API for any custom workflow

Smart Lists are the connective tissue between your agents and your outreach. An agent captures a lead → it lands in a Smart List → a sequence picks it up and starts nurturing it.

Core Operations

Smart Lists support the full set of CRUD operations through the API.

Operation	Method	Endpoint
List all Smart Lists	`GET`	`/api/v0/smart-lists`
Create a Smart List	`POST`	`/api/v0/smart-lists`
Get a Smart List	`GET`	`/api/v0/smart-lists/{id}`
Update a Smart List	`PUT`	`/api/v0/smart-lists/{id}`
Delete a Smart List	`DELETE`	`/api/v0/smart-lists/{id}`

Creating a Smart List

Choose a name

Give your list a descriptive name that reflects its purpose (e.g., “Trial Signups Q1” or “Enterprise Prospects”).

Create via API

Send a POST /api/v0/smart-lists request with your list details.

Link to an agent or sequence

Copy the returned id and set it as contactListId on an agent or reference it in a sequence for targeted delivery.

curl -X POST "https://api.parallellabs.app/api/v0/smart-lists" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trial Signups Q1",
    "description": "Leads captured from the trial signup agent"
  }'

import requests

response = requests.post(
    "https://api.parallellabs.app/api/v0/smart-lists",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "name": "Trial Signups Q1",
        "description": "Leads captured from the trial signup agent"
    }
)
print(response.json())

The response includes an id field — keep this handy to link the list to agents and sequences.

Linking a Smart List to an Agent

Once you have a Smart List, attach it to any agent by setting the contactListId field. When aiContactCaptureEnabled is also true on that agent, contact information extracted from conversations will be automatically saved to your list.

curl -X PUT "https://api.parallellabs.app/api/v0/agents/{agentId}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactListId": "YOUR_SMART_LIST_ID",
    "aiContactCaptureEnabled": true
  }'

You can link the same Smart List to multiple agents. All captured contacts will be consolidated into one list, making it easy to run a single sequence across all your lead sources.

Listing Smart Lists with Pagination

Use the page and pageSize query parameters to paginate through large collections.

curl "https://api.parallellabs.app/api/v0/smart-lists?page=1&pageSize=20" \
  -H "X-API-Key: YOUR_API_KEY"

Parameter	Type	Description
`page`	integer	Page number, starting from `1`
`pageSize`	integer	Number of results per page

Managing Contacts in a List

You can add, update, and remove individual contacts within a Smart List via the Contacts sub-resource:

Operation	Method	Endpoint
List contacts	`GET`	`/api/v0/smart-lists/{id}/contacts`
Add a contact	`POST`	`/api/v0/smart-lists/{id}/contacts`
Update a contact	`PUT`	`/api/v0/smart-lists/{id}/contacts/{contactId}`
Remove a contact	`DELETE`	`/api/v0/smart-lists/{id}/contacts/{contactId}`

Next Steps

Smart Lists API Reference

Full reference for list, create, update, and delete endpoints.

AI Agents

Configure agents to capture leads directly into your Smart Lists.

Sequences

Target your Smart Lists with automated email and SMS outreach.

Get Started

Core Features

Integrations

Platform

Manage Contact Lists with Smart Lists

What Are Smart Lists?

Core Operations

Creating a Smart List

Linking a Smart List to an Agent

Managing Contacts in a List

Next Steps

Smart Lists API Reference

AI Agents

Sequences

​What Are Smart Lists?

​Core Operations

​Creating a Smart List

​Linking a Smart List to an Agent

​Listing Smart Lists with Pagination

​Managing Contacts in a List

​Next Steps

Smart Lists API Reference

AI Agents

Sequences

What Are Smart Lists?

Core Operations

Creating a Smart List

Linking a Smart List to an Agent

Listing Smart Lists with Pagination

Managing Contacts in a List

Next Steps