Twenty Integration Setup

Connect Parsley to Twenty CRM for automatic lead and conversation sync. This guide walks you through setup and verification.

Quick Setup

1. Have a Twenty account with API access
2. Navigate to Hub > Integrations in Parsley
3. Click Connect on the Twenty card
4. Enter your Twenty API key (and instance URL if self-hosted)
5. Verify the connection shows "Connected" status

That's it. Leads and conversations now sync automatically.

Prerequisites

• A Twenty account - Both Twenty Cloud and self-hosted instances are supported. Sign up at twenty.com or self-host with Docker.
• A Parsley Business account - CRM integrations require a Business plan. Upgrade here if you're on Free.
• Your Twenty API key - Found in Settings -> Developers -> API Keys in Twenty.

Step 1: Get Your API Key

1. Log in to your Twenty workspace
2. Go to Settings (gear icon)
3. Click Developers
4. Click API Keys
5. Create a new API key
6. Copy the key and store it securely

Twenty API keys have configurable expiration dates. Choose an expiration that fits your security policy - you can always generate a new key if one expires.

Step 2: Connect to Twenty

From your Parsley dashboard:

1. Go to Hub in the left sidebar
2. Click Integrations
3. Find the Twenty card
4. Click Connect
5. Paste your API key
6. If self-hosted: Toggle on "Self-hosted instance" and enter your instance URL (e.g., https://twenty.mycompany.com)
7. Click Save

Parsley validates your API key by making a test request to the Twenty API. If everything checks out, the card shows "Connected" status.

Step 3: Contact Sync

Contact sync is enabled by default. Here's what happens when you capture a lead:

How it works:

• Parsley searches for existing People by email address
• If found, Parsley updates the record
• If not, Parsley creates a new Person
• Companies are created as separate records and linked to the Person via Twenty's relation model

Sync triggers:

• Lead capture via contact exchange form
• Lead capture via chatbot conversation
• Contact form submissions on your profile

Step 4: Conversation Sync

When a prospect has a meaningful chatbot conversation on your Parsley profile, the context syncs to Twenty as a Note attached to their Person record.

What syncs to Twenty:

• Conversation summary - Key points and topics discussed
• Lead quality score - Hot, Warm, or Cold based on signals
• Intent signal - High intent, Evaluation, Research, or Support
• MEDDIC signals - Metrics, Economic Buyer, Decision Criteria, Decision Process, Identify Pain, Champion indicators
• Engagement metrics - Message count, session duration
• Knowledge gaps - Topics the prospect asked about that weren't covered

Notes are formatted in CommonMark markdown, which Twenty renders natively in its interface.

Why Notes instead of custom fields? Twenty's Metadata API supports custom field creation, but for the initial integration we use Notes to keep setup simple - no schema changes needed in your workspace. Custom attribute provisioning may be added in a future update.

Step 5: Verify the Connection

1. Check the integration status - The Twenty card should show "Connected"
2. Capture a test lead - Use your own email to fill out your profile's contact form
3. Check Twenty - Within a few seconds, you should see a new Person record
4. Have a chatbot conversation - Ask a few questions on your profile's chatbot
5. Check the Person's notes - The conversation note should appear

Self-Hosted Instances

Twenty supports self-hosting via Docker. Parsley works with self-hosted instances with one requirement: your instance must be accessible over HTTPS from the public internet (Parsley's sync runs from cloud infrastructure).

To connect a self-hosted instance:

1. Ensure your Twenty instance has a valid SSL certificate and public domain
2. Follow the connection steps above, toggling on "Self-hosted instance"
3. Enter your full instance URL (e.g., https://twenty.mycompany.com)
4. Parsley will validate the connection against your instance's API

This is a key advantage of the Twenty integration - teams that want full data ownership can self-host Twenty and still get automatic lead sync from Parsley.

Troubleshooting

"Invalid API Key" Error

• Make sure you copied the complete API key
• Check that the API key hasn't expired (Twenty keys have configurable expiration)
• Try generating a new API key in Twenty Settings -> Developers -> API Keys

"Connection Failed" for Self-Hosted

• Verify your instance URL is correct and includes the protocol (e.g., https://)
• Ensure the instance is accessible over the public internet
• Check that your SSL certificate is valid and not expired
• Confirm the Twenty API is running (try accessing {your-url}/rest/people in a browser)

Leads Not Syncing

• Verify the integration shows "Connected" status
• Check that you're on a Parsley Business plan
• Ensure the lead has a valid email address

Conversations Not Appearing

• Conversation sync requires a visitor email to attach the note to a Person record
• Notes appear attached to the Person record, not the Company

Rate Limits

Twenty allows 100 requests per minute. Parsley handles rate limiting automatically with retry logic. If you're seeing sync delays during high-volume periods, this is normal - syncs will complete once the rate limit resets.

What's Next

• Use Twenty's filter views to organize your synced Parsley leads
• Set up Twenty's built-in automations to act on new leads
• Learn more about Twenty

---

Questions? Contact us or email peter@parsley.id.