Contacts

Contacts are essential for managing the end-users and customers who engage with your AI agents across various channels. Each contact represents a unique individual and stores their identifying information, preferences, and interaction history. The contact system enables you to provide personalized experiences, track conversations over time, and maintain a comprehensive customer relationship management (CRM) capability within your applications.

Contacts can be either verified or unverified. Verified contacts are created with a trusted fingerprint and have their identity confirmed, while unverified contacts are automatically generated based on user interactions and may be verified later. This dual approach allows you to capture all user interactions while maintaining security and preventing duplicate entries.

Creating Contacts

Creating a contact is the first step in establishing a relationship with an end-user. You can create contacts explicitly when users sign up, register, or start a conversation, providing their identifying information such as email, phone number, or a custom identifier.

When creating a contact, you can specify various attributes including name, description, email, phone, nickname, and custom preferences. You can also provide a unique fingerprint to ensure the contact can be reliably identified across different sessions and channels. The fingerprint serves as a stable identifier that prevents duplicate contact creation.

POST /api/v1/contact/create
Content-Type: application/json

{
  "name": "John Doe",
  "description": "Premium customer",
  "fingerprint": "unique-fingerprint-123",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "nick": "johnd",
  "preferences": "language=en;timezone=UTC"
}

http

The API will return the newly created contact ID, which you can use to reference this contact in subsequent operations such as starting conversations, updating preferences, or retrieving interaction history.

Important: The fingerprint parameter is crucial for preventing duplicate contacts. If you create a contact with the same fingerprint multiple times, the system will return the existing contact rather than creating a duplicate. This ensures data consistency and prevents fragmented customer records.

Listing Contact Conversations

Retrieve all conversations associated with a specific contact to track their interaction history, analyze engagement patterns, and maintain conversation context across multiple sessions. This endpoint provides a complete view of all conversations a contact has participated in, including metadata and associated resources like bots and datasets.

This is particularly useful for customer support scenarios where you need to understand the full conversation history with a customer, or for analytics purposes to track engagement and satisfaction across multiple interactions.

GET /api/v1/contact/{contactId}/conversation/list

http

The endpoint supports pagination through cursor-based navigation, allowing you to efficiently retrieve large conversation histories. Use the cursor parameter from previous responses to fetch the next page of results.

Query Parameters:

  • cursor: Pagination cursor from previous response for retrieving next page
  • order: Sort order for conversations ("asc" or "desc", default: "desc")
  • take: Number of conversations to retrieve per page (default: 25)
  • meta: Filter conversations by metadata key-value pairs

Each conversation in the response includes complete configuration details including the bot, dataset, and skillset associations, enabling you to understand the full context of each conversation and how it was configured.

Practical Example:

GET /api/v1/contact/contact-abc123/conversation/list?take=50&order=desc

http

This retrieves the 50 most recent conversations for the specified contact, ordered from newest to oldest, making it easy to see their recent interaction history and engagement patterns.

Deleting Contacts

The delete contact operation permanently removes a contact from your database, including all associated data and relationships. This operation is irreversible and should be used carefully, typically in response to explicit user requests for data deletion or as part of data retention policy enforcement for compliance with privacy regulations.

When you delete a contact, the system removes all stored information about that individual including their identifying attributes, preferences, metadata, and interaction history. Any conversations, messages, or other resources linked to this contact may also be affected depending on your database configuration and cascade rules. This ensures complete data removal to comply with data protection regulations like GDPR's "right to be forgotten" or CCPA's deletion requirements.

Before deleting a contact, you should consider whether archiving or marking the contact as inactive might be more appropriate for your use case. Deletion is permanent and cannot be undone, so if there's any possibility you might need the contact data in the future for analytics, legal compliance, or business continuity, consider alternative approaches such as soft deletion through metadata flags.

POST /api/v1/contact/{contactId}/delete
Content-Type: application/json

{}

http

The delete operation requires an empty JSON object in the request body for consistency with other API endpoints, even though no parameters are needed. This design pattern ensures uniform request handling across all POST operations in the API.

The response confirms the deletion by returning the ID of the deleted contact. After receiving this response, the contact ID becomes invalid and any subsequent operations using that ID will return a "not found" error. Make sure to update any stored references in your application after successful deletion.

Data Retention Compliance: When implementing contact deletion for regulatory compliance, ensure you also handle any related data that might exist in external systems, logs, or backups. The API deletion only affects the primary database; you may need additional procedures to ensure complete data removal across your entire infrastructure.

Best Practice: Before performing a deletion, consider implementing a confirmation workflow in your user interface to prevent accidental data loss. Additionally, you might want to export contact data before deletion to maintain audit trails or comply with record retention requirements in certain jurisdictions.

Rate Limiting: Bulk deletion operations should be implemented carefully with appropriate rate limiting and error handling. If you need to delete many contacts, implement batching with delays between requests to avoid overwhelming the system or triggering rate limit protections.

Fetching Individual Contacts

The fetch contact operation retrieves complete information about a specific contact using their unique identifier. This endpoint is essential for displaying contact details in user interfaces, retrieving contact information before starting conversations, or accessing contact data for integration with other systems and workflows.

When you fetch a contact, you receive all stored information including identifying attributes (fingerprint, email, phone, nickname), basic information (name and description), custom preferences, verification status, metadata, and timestamps. This comprehensive data enables you to build rich user experiences and make informed decisions in your application logic.

The contact ID used in this operation can be obtained from various sources: contact creation responses, list operations, conversation metadata, or your own application database where you might store contact IDs for quick reference. The ID serves as a stable, permanent identifier that remains unchanged throughout the contact's lifecycle.

GET /api/v1/contact/{contactId}/fetch

http

For example, to fetch a specific contact:

GET /api/v1/contact/cont_abc123xyz/fetch

http

The response includes all contact fields with their current values. The verifiedAt field indicates verification status: if non-null, the contact has been verified with a trusted fingerprint; if null, the contact is unverified and was created through automatic fingerprinting.

This endpoint implements robust authorization checks to ensure users can only access contacts within their own account. Attempting to fetch a contact from another user's account will result in a not authorized error, even if you somehow obtained their contact ID. This strict access control maintains data privacy and prevents unauthorized information disclosure.

Use Cases: Common scenarios for fetching individual contacts include: displaying contact details in a CRM interface, loading contact information before initiating a support conversation, verifying contact existence and status in middleware, populating contact fields in forms for updates, and retrieving contact preferences to personalize conversation experiences.

Performance: Fetch operations are fast and efficient, typically completing in milliseconds. However, for workflows that need to access multiple contacts, consider using the list endpoint with appropriate filters rather than making many individual fetch requests, as this reduces API calls and improves overall performance.

Listing Contact Memories

Retrieve all memories associated with a specific contact to access their personalization data, understand conversation context, and review what information has been retained about them across interactions. Memories enable personalized, contextual conversations by storing key facts and preferences about individual contacts.

This endpoint is essential for building chatbots that remember user preferences, track conversation history, and provide personalized responses based on past interactions. Each memory represents a discrete piece of information that AI agents can recall and utilize in future conversations.

GET /api/v1/contact/{contactId}/memory/list

http

Query Parameters:

  • cursor: Pagination cursor for retrieving additional results
  • order: Sort order ("asc" or "desc", default: "desc")
  • take: Number of memories to retrieve (default: 25)
  • meta: Filter memories by metadata key-value pairs

Each memory entry includes the memory text content, associated bot ID, timestamps, and optional metadata, providing complete visibility into what information is being retained and utilized for personalization.

Practical Example:

GET /api/v1/contact/contact-abc123/memory/list?take=100

http

This retrieves up to 100 memories for the specified contact, enabling you to audit personalization data, understand what information has been captured, and ensure memories are being appropriately utilized to enhance conversation quality and user experience.

Use Cases:

  • Personalization Auditing: Review what information is stored about contacts
  • Data Management: Identify outdated memories for cleanup or updates
  • Compliance: Verify data retention meets privacy requirements
  • Analytics: Analyze common memory patterns across contact base
  • Quality Assurance: Ensure memories are accurately capturing key information

Searching Contact Memories

Memory search enables semantic search across all memories associated with a specific contact, allowing you to find relevant historical information using natural language queries rather than exact text matching.

POST /api/v1/contact/{contactId}/memory/search
Content-Type: application/json

{
  "text": "favorite food preferences"
}

http

Unlike simple listing, memory search uses vector similarity to find semantically related memories even when the exact words don't match, making it ideal for conversational AI that needs to recall relevant context from past interactions.

How Semantic Search Works

Memory search converts your query into a vector embedding and compares it against the embeddings of all stored memories, returning the most semantically similar results. This means:

  • Conceptual matching: Find memories about "pizza preferences" even when the stored memory uses words like "Italian food choices"
  • Context awareness: Results understand meaning, not just keywords
  • Ranked relevance: Memories are ordered by semantic similarity to your query
  • Flexible queries: Use natural language questions or statements as search terms

Search Request Parameters

The search endpoint accepts several parameters to control how results are retrieved:

POST /api/v1/contact/{contactId}/memory/search
Content-Type: application/json

{
  "text": "user's dietary restrictions",
  "take": 5
}

http

Available parameters:

  • text (required): The search query in natural language
  • take: Maximum number of results to return (controls result count)

Understanding Search Results

Search results include the memory content and metadata showing how well each memory matches your query:

{
  "items": [
    {
      "id": "memory_abc123",
      "text": "User prefers vegetarian options and avoids dairy",
      "score": 0.89,
      "createdAt": "2025-11-15T10:00:00Z",
      "updatedAt": "2025-11-15T10:00:00Z"
    },
    {
      "id": "memory_def456",
      "text": "Mentioned interest in Italian cuisine",
      "score": 0.76,
      "createdAt": "2025-11-10T14:30:00Z",
      "updatedAt": "2025-11-10T14:30:00Z"
    }
  ]
}

json

The score value indicates semantic similarity, with higher scores representing better matches to your search query.

Memory search enables powerful conversational AI capabilities:

Contextual Conversations: When a user asks a question, search their memories to find relevant past information that provides context for generating personalized responses.

Preference Recall: Find user preferences and settings stored in memories without needing to know exact keywords or tags.

Follow-up Understanding: When a user refers to something from a past conversation, search memories to understand what they're referencing.

Personalization: Retrieve relevant biographical details or preferences to personalize interactions without asking repetitive questions.

Search Performance Considerations

Memory search uses vector embeddings and similarity calculations, which have different performance characteristics than simple list queries:

  • Semantic accuracy: Results based on meaning, not just text matching
  • Ranked relevance: Most relevant memories appear first
  • Bounded results: Use take parameter to control result count
  • Contact-scoped: Search only within the specific contact's memories

Best Practices

To get the best results from memory search:

  • Clear queries: Use specific, well-formed search questions
  • Natural language: Write queries as you would ask a person
  • Appropriate scope: Use take parameter to get enough results without overwhelming
  • Score interpretation: Higher scores indicate better semantic matches
  • Context integration: Combine search results thoughtfully in your responses

Important: Memory search requires that contact memories have been properly stored and indexed. Newly created memories may take a moment to become available for search as embeddings are generated. Search operates only within the specified contact's memory space and cannot access memories from other contacts.

Listing Contact Ratings

Contact ratings capture user feedback on chatbot interactions, enabling you to monitor conversation quality, identify areas for improvement, and track user satisfaction with AI-generated responses.

GET /api/v1/contact/{contactId}/rating/list
Content-Type: application/json

http

Each rating records a user's evaluation of a specific chatbot message or conversation, including the rating value and any explanatory feedback they provided about why they rated the interaction that way.

Understanding Rating Data

The rating list endpoint returns comprehensive information about each rating submitted by the contact:

{
  "items": [
    {
      "id": "rating_xyz789",
      "name": "Message Rating",
      "description": "User feedback on response quality",
      "contactId": "contact_abc123",
      "botId": "bot_def456",
      "conversationId": "conv_ghi789",
      "messageId": "msg_jkl012",
      "value": 5,
      "reason": "Very helpful and accurate response",
      "createdAt": "2025-11-22T18:30:00Z",
      "updatedAt": "2025-11-22T18:30:00Z"
    }
  ]
}

json

Each rating includes:

  • Rating value: Numerical score indicating satisfaction level
  • Reason: Optional text explaining the rating decision
  • Context: Links to the specific bot, conversation, and message rated
  • Timestamps: When the rating was created and last updated

Analyzing User Feedback

Contact ratings provide valuable insights for improving chatbot performance:

Quality Monitoring: Track how users perceive response quality across different conversations and identify patterns in positive and negative ratings.

Bot Improvement: Use rating reasons to understand what users find helpful or problematic, informing adjustments to bot configuration, training data, or response generation strategies.

User Satisfaction Trends: Monitor rating patterns over time to measure improvements and catch declining satisfaction early.

Conversation Analysis: Link ratings back to specific conversations and messages to understand context and identify which types of interactions generate the best or worst responses.

Filtering and Pagination

Like other list endpoints, rating lists support pagination and filtering:

GET /api/v1/contact/{contactId}/rating/list?take=50&order=desc
Content-Type: application/json

http

You can filter ratings by metadata using the meta query parameter to find ratings with specific attributes or analyze ratings from particular time periods or interaction contexts.

Integration with Chatbot Flows

Ratings are typically collected through chatbot interactions where users are prompted to rate responses. The rating system supports:

  • Inline feedback: Users can rate messages during conversations
  • Post-conversation surveys: Collect ratings after conversation completion
  • Selective rating: Target specific messages or conversation types for feedback
  • Multi-dimensional ratings: Use metadata to capture different rating aspects

Important: Ratings are associated with specific contacts, bots, conversations, and messages, creating a complete feedback trail that enables detailed analysis of user satisfaction and response quality across your entire chatbot ecosystem.

Listing Contact Spaces

The contact spaces listing endpoint retrieves all workspace spaces associated with a specific contact, enabling you to discover and access the shared environments where contact interactions occur. Spaces represent isolated workspaces that can contain conversations, tasks, memories, and other resources linked to particular contacts, providing organizational boundaries for multi-tenant or segmented applications.

Understanding a contact's associated spaces is crucial for applications that organize interactions by workspace, team, or organizational unit. This endpoint allows you to enumerate all spaces where a contact has activity, facilitating workspace-aware conversation routing, resource isolation, and context-specific interactions. Each space maintains its own set of resources and configurations, ensuring proper separation of concerns across different organizational contexts.

The listing operation supports standard pagination with cursor-based iteration, allowing efficient traversal of large collections of spaces. You can also filter spaces using metadata queries, enabling sophisticated space discovery based on custom attributes such as workspace type, organizational unit, or business-specific classifications.

Retrieving Contact Spaces

To list all spaces associated with a contact:

GET /api/v1/contact/{contactId}/space/list

http

Replace {contactId} with the actual contact identifier. The response includes basic space information including identifiers, names, descriptions, and timestamps.

Pagination and Ordering

The endpoint supports cursor-based pagination for efficient traversal:

GET /api/v1/contact/{contactId}/space/list?take=20&order=desc

http
  • cursor: Continuation token from the previous response for pagination
  • order: Sort order, either asc or desc (default: desc)
  • take: Number of items to retrieve per page

Cursor-based pagination ensures consistent results even as spaces are added or modified during traversal, preventing duplicate or missing items in paginated result sets.

Metadata Filtering

You can filter spaces by metadata attributes:

GET /api/v1/contact/{contactId}/space/list?meta.workspace_type=team

http

Metadata filtering allows sophisticated space discovery based on custom classification schemes. Common filtering scenarios include:

  • Finding spaces for specific organizational units
  • Identifying spaces with particular configuration flags
  • Filtering by workspace type or category
  • Selecting spaces based on business-specific attributes

Response Structure

The response contains an array of space objects:

{
  "items": [
    {
      "id": "space-abc123",
      "name": "Customer Support Team",
      "description": "Primary support workspace",
      "contactId": "contact-xyz789",
      "meta": {
        "workspace_type": "team",
        "department": "support"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:45:00Z"
    }
  ]
}

json

Each space includes its unique identifier, descriptive information, the contact association, optional metadata, and timestamp information for tracking creation and modification dates.

Authorization and Access Control

Only the contact owner can list spaces associated with their contacts. The endpoint verifies that the authenticated user owns the specified contact before returning any space information, ensuring proper data isolation and access control across different user accounts.

Use Cases for Contact Space Listing

Enumerating contact spaces supports various organizational scenarios:

  • Workspace Discovery: Identifying all workspaces where a contact has interactions
  • Context Routing: Directing conversations to appropriate workspace- specific bots or resources
  • Multi-tenant Applications: Managing contact interactions across different organizational units
  • Resource Isolation: Ensuring conversations and resources remain properly segmented by workspace
  • Workspace Analytics: Understanding contact activity distribution across different spaces
  • Organizational Reporting: Generating reports on contact engagement by workspace or team

Important Notes:

  • Only contact owners can access space listings
  • Spaces provide organizational boundaries for resources
  • Pagination cursors remain valid during active traversal
  • Metadata filtering supports standard equality operators
  • Empty result sets indicate no spaces associated with the contact

Listing Contact Tasks

The contact tasks listing endpoint retrieves all scheduled and completed tasks associated with a specific contact, providing comprehensive visibility into automated operations, scheduled interactions, and workflow executions tied to that contact. Tasks represent time-based or event-driven actions that the system performs on behalf of or in relation to a contact, such as scheduled follow-ups, recurring check-ins, automated reminders, or workflow triggers.

Understanding a contact's task history and upcoming scheduled tasks is essential for building sophisticated automation workflows, tracking engagement cadences, and ensuring appropriate follow-up actions occur at the right times. This endpoint allows you to audit task execution, monitor automation health, and understand the complete timeline of automated interactions with each contact.

The listing operation provides detailed task information including execution status, outcomes, scheduling details, and associated bot configurations. This comprehensive view enables you to troubleshoot task failures, analyze automation effectiveness, and ensure your scheduled interactions are functioning as intended. The endpoint supports pagination and metadata filtering, allowing efficient discovery of specific task types or execution states.

Retrieving Contact Tasks

To list all tasks for a specific contact:

GET /api/v1/contact/{contactId}/task/list

http

Replace {contactId} with the actual contact identifier. The response includes comprehensive task information including scheduling details, execution status, outcomes, and associated bot references.

Task Information Structure

Each task in the response includes:

  • id: Unique task identifier
  • name: Task name or label
  • description: Detailed task description
  • contactId: Associated contact identifier
  • botId: Bot executing the task
  • schedule: CRON-style schedule specification
  • status: Current task status (pending, running, completed, failed)
  • outcome: Task execution outcome (success, failure, details)
  • meta: Custom metadata including execution history
  • createdAt: Task creation timestamp
  • updatedAt: Last modification timestamp

Pagination and Ordering

The endpoint supports standard cursor-based pagination:

GET /api/v1/contact/{contactId}/task/list?take=50&order=desc

http
  • cursor: Pagination continuation token
  • order: Sort order (asc or desc, default: desc)
  • take: Number of items per page

Descending order (default) shows the most recently modified tasks first, making it easy to find recent executions or newly scheduled tasks.

Filtering by Status and Metadata

You can filter tasks by status or custom metadata:

GET /api/v1/contact/{contactId}/task/list?meta.status=pending

http

Common filtering scenarios include:

  • Pending tasks: Tasks scheduled but not yet executed
  • Failed tasks: Tasks that encountered errors during execution
  • Recurring tasks: Tasks with CRON schedules for repeated execution
  • Task type: Custom metadata for categorizing task purposes
  • Execution date: Finding tasks within specific time windows

Response Structure

The response contains an array of task objects:

{
  "items": [
    {
      "id": "task-abc123",
      "name": "Weekly Check-in",
      "description": "Automated weekly customer check-in",
      "contactId": "contact-xyz789",
      "botId": "bot-def456",
      "schedule": "0 9 * * 1",
      "status": "completed",
      "outcome": "success",
      "meta": {
        "last_execution": "2024-01-22T09:00:00Z",
        "execution_count": 12
      },
      "createdAt": "2024-01-01T10:00:00Z",
      "updatedAt": "2024-01-22T09:05:00Z"
    }
  ]
}

json

Understanding Task Schedules

Task schedules use standard CRON format (5 fields):

* * * * * │ │ │ │ │ │ │ │ │ └─── Day of week (0-6, Sunday=0) │ │ │ └───── Month (1-12) │ │ └─────── Day of month (1-31) │ └───────── Hour (0-23) └─────────── Minute (0-59)

Common schedule examples:

  • 0 9 * * 1: Every Monday at 9:00 AM
  • 30 14 1 * *: First day of month at 2:30 PM
  • 0 0 * * 0: Every Sunday at midnight

Task Status Values

Tasks progress through various status states:

  • pending: Scheduled but not yet executed
  • running: Currently executing
  • completed: Successfully finished execution
  • failed: Encountered an error during execution
  • cancelled: Manually cancelled before execution

Task Outcome Information

Task outcomes provide execution results:

  • success: Task completed successfully
  • failure: Task encountered an error
  • timeout: Task exceeded maximum execution time
  • skipped: Task was skipped based on conditions

The outcome field typically includes additional details about the execution result in the task's metadata.

Authorization and Access Control

Only the contact owner can list tasks associated with their contacts. The endpoint verifies contact ownership before returning any task information, ensuring proper data isolation and preventing unauthorized access to automation details.

Use Cases for Contact Task Listing

Enumerating contact tasks supports various automation scenarios:

  • Automation Monitoring: Tracking scheduled follow-ups and automated interactions
  • Task Auditing: Understanding execution history and outcomes for compliance or debugging
  • Workflow Analytics: Analyzing automation effectiveness and success rates
  • Failure Recovery: Identifying and addressing failed task executions
  • Schedule Management: Reviewing upcoming and past scheduled interactions
  • Bot Activity Tracking: Understanding which bots are engaging with specific contacts
  • Engagement Cadence: Ensuring appropriate frequency of automated outreach

Performance Considerations:

For contacts with extensive task histories (hundreds or thousands of tasks), use pagination to retrieve results in manageable chunks. Consider filtering by date ranges or status to narrow result sets for better performance and more focused analysis.

Important Notes:

  • Only contact owners can access task listings
  • Task schedules are stored in UTC timezone
  • Status and outcome fields provide complementary information
  • Metadata can include execution logs and error details
  • Completed tasks remain in history for audit purposes
  • Recurring tasks create new task instances for each execution

Updating Contacts

The update contact operation enables you to modify existing contact information, allowing you to keep contact records current as users update their details, change preferences, or as you gather additional information through ongoing interactions. This endpoint supports partial updates, meaning you only need to provide the fields you want to change.

Contact updates are essential for maintaining accurate customer data over time. As users interact with your system, you might collect additional information, learn new preferences, or need to correct previously entered data. The update operation provides a flexible mechanism for keeping contact records synchronized with the current state of your customer relationships.

When updating a contact, you can modify any of the editable fields including name, description, email, phone number, nickname, and preferences. You can also update the fingerprint, though this should be done carefully as it affects contact identification and deduplication. Metadata updates support partial modification, allowing you to add or modify specific metadata fields without affecting other metadata properties.

POST /api/v1/contact/{contactId}/update
Content-Type: application/json

{
  "email": "newemail@example.com",
  "preferences": "language=es;timezone=America/Mexico_City"
}

http

To update multiple fields at once:

POST /api/v1/contact/{contactId}/update
Content-Type: application/json

{
  "name": "Jane Smith-Johnson",
  "email": "jane.smithjohnson@example.com",
  "phone": "+1234567890",
  "meta": {
    "segment": "premium",
    "lifetime_value": 15000
  }
}

http

The verification status (verifiedAt) can also be updated, which is useful when converting an unverified contact to a verified one after identity confirmation. Pass the current timestamp in milliseconds to mark a contact as verified, or null to mark it as unverified.

Authorization: Update operations verify ownership before allowing modifications. Only the account that created a contact can update it, ensuring data security and preventing unauthorized modifications. Cross- account contact updates are strictly prohibited.

Metadata Handling: The metadata update mechanism intelligently merges new metadata with existing metadata rather than replacing it entirely. This means you can update specific metadata fields without losing other metadata properties, making incremental data enrichment workflows efficient and safe.

Best Practice: When updating contact information based on user input, always validate and sanitize the data before sending it to the API. This prevents malformed data from entering your contact database and ensures data quality remains high throughout your system.

Ensuring Contact Existence

The ensure contact operation provides an idempotent way to create or retrieve contacts, making it ideal for scenarios where you're not sure whether a contact already exists. This is particularly useful in conversational interfaces where users may return for multiple sessions without explicit account creation.

When you call the ensure endpoint, the system intelligently handles two distinct scenarios based on whether you provide a trusted fingerprint. If you provide a fingerprint (a verified identifier from a trusted source), the system creates or retrieves a verified contact. If no fingerprint is provided, the system generates a fingerprint based on the contact's attributes and creates or retrieves an unverified contact.

This dual-mode operation enables flexible contact management strategies. For authenticated users with verified identities (like those who signed in via OAuth), you can pass a trusted fingerprint to create verified contacts. For anonymous or guest users, you can omit the fingerprint and let the system automatically generate one based on their provided information.

POST /api/v1/contact/ensure
Content-Type: application/json

{
  "fingerprint": "verified-user-fingerprint-abc123",
  "email": "jane.smith@example.com",
  "name": "Jane Smith"
}

http

For unverified contacts, simply omit the fingerprint parameter:

POST /api/v1/contact/ensure
Content-Type: application/json

{
  "email": "guest@example.com",
  "name": "Guest User"
}

http

The endpoint returns the contact ID regardless of whether a new contact was created or an existing one was found. This idempotent behavior ensures your application logic remains simple and doesn't need to handle "contact already exists" errors.

Best Practice: Use this endpoint in chat initialization flows where you want to ensure a contact exists before starting a conversation, but you're not certain whether this is a new or returning user. This pattern simplifies your code and prevents duplicate contact creation.

Important: Trusted and untrusted contacts are kept separate. A trusted contact (created with a fingerprint) cannot become untrusted, and vice versa. If you later want to verify an untrusted contact, you'll need to create a new verified contact and migrate the conversation history.

Exporting Contacts

The export contacts operation provides specialized functionality for retrieving contact data in formats optimized for data migration, backup, analysis, or integration with external systems. Unlike the standard list endpoint, the export endpoint supports multiple response formats including JSON, JSONL (JSON Lines for streaming), and CSV, making it ideal for bulk data operations and system integrations.

This endpoint is particularly useful when you need to synchronize your contact database with external CRM systems, perform data analysis in spreadsheet applications, create backups of your contact data, or migrate contacts between different environments. The flexible format support ensures compatibility with a wide range of downstream tools and processes.

The export operation supports the same pagination and filtering capabilities as the list endpoint, but with enhanced metadata serialization. When exporting to CSV format, complex metadata objects are automatically converted to YAML strings, ensuring all data is preserved in a human- readable format suitable for spreadsheet applications.

GET /api/v1/contact/export
Accept: application/json

http

For CSV export (ideal for Excel or Google Sheets):

GET /api/v1/contact/export
Accept: text/csv

http

For streaming large datasets efficiently using JSONL format:

GET /api/v1/contact/export
Accept: application/jsonl

http

The JSONL format is particularly efficient for large datasets as it streams one contact per line, allowing you to process records incrementally without loading the entire dataset into memory. This approach is ideal for ETL (Extract, Transform, Load) pipelines and data synchronization processes.

You can combine export with metadata filters to export specific segments of your contact database:

GET /api/v1/contact/export?meta.verified=true
Accept: text/csv

http

Rate Limiting: Export operations may be subject to rate limiting to ensure system stability. For very large contact databases (millions of records), consider using pagination with cursor-based iteration and implement exponential backoff if you encounter rate limit responses.

Data Privacy: Exported contact data contains personally identifiable information (PII). Ensure you handle exported files securely and comply with relevant data protection regulations such as GDPR, CCPA, or other applicable privacy laws in your jurisdiction.

Listing Contacts

The list contacts operation retrieves all contacts associated with your account, enabling you to build contact management interfaces, perform bulk operations, or analyze your user base. The endpoint supports cursor-based pagination for efficiently handling large contact databases and includes comprehensive filtering options through metadata queries.

When listing contacts, you receive complete contact information including all identifying attributes, preferences, verification status, and metadata. The response is paginated to ensure optimal performance even with thousands or millions of contacts, and you can control the page size and ordering to suit your specific use case.

The endpoint supports both ascending and descending order, allowing you to retrieve contacts in chronological order (oldest first) or reverse chronological order (newest first). This flexibility is particularly useful when building user interfaces that need to display recently added contacts or when performing sequential processing operations.

GET /api/v1/contact/list?order=desc&take=50

http

For paginated results, use the cursor from the previous response:

GET /api/v1/contact/list?cursor=contact_abc123&order=desc&take=50

http

You can also filter contacts using metadata queries, which is useful for segmenting your contact database by custom attributes or tags. For example, you might filter for premium customers, users from specific regions, or contacts with certain preferences:

GET /api/v1/contact/list?meta.segment=premium&take=100

http

The response includes complete contact records with all fields populated, including the verifiedAt timestamp which indicates whether the contact is verified (non-null) or unverified (null). This allows you to implement different UI treatments or business logic based on verification status.

Performance Note: For large contact databases with millions of records, always use cursor-based pagination rather than attempting to retrieve all contacts at once. The cursor approach ensures consistent performance and prevents memory issues or timeouts.

Security: All list operations are scoped to the authenticated user's account, ensuring proper data isolation. You can never retrieve contacts belonging to other users, maintaining strict privacy boundaries.

Go to cbk.ai