Contacts

Contacts are essential for managing the end-users and customers who engage with your chatbots 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.

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.

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.

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.

For example, to fetch a specific contact:

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.

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.

To update multiple fields at once:

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.

For unverified contacts, simply omit the fingerprint parameter:

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.

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

For streaming large datasets efficiently using JSONL format:

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:

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.

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

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:

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.