نظرة عامة
Twenty provides both GraphQL and REST APIs for programmatic data import. Use the API when CSV import isn’t practical for your data volume or when you need automated, recurring imports.When to Use API Import
| Scenario | Recommended Method |
|---|---|
| Under 10,000 records | CSV Import |
| 10,000 - 50,000 records | CSV Import (split into files) |
| 50,000+ records | API Import |
| One-time migration | Either (based on volume) |
| Recurring imports | API Import |
| Real-time sync | API Import |
| Integration with other systems | API Import |
For datasets in the hundreds of thousands, the API is significantly faster and more reliable than multiple CSV imports.
API Rate Limits
Twenty enforces rate limits to ensure system stability:| Limit | القيمة |
|---|---|
| Requests per minute | 100 |
| Records per batch call | 60 |
| Maximum throughput | ~6,000 records/minute |
البدء
Step 1: Get Your API Key
- Go to Settings → Developers
- Click + Create API key
- Give your key a descriptive name
- Copy the API key immediately (it won’t be shown again)
- Store it securely
Step 2: Choose Your API
Twenty supports two API types:
Both APIs support:
- Creating, reading, updating, and deleting records
- Batch operations — create or update up to 60 records per call
Step 3: Plan Your Import Order
Just like CSV imports, order matters for relations:- Companies first (no dependencies)
- People second (can link to Companies)
- Opportunities third (can link to Companies and People)
- Tasks/Notes (can link to any of the above)
- Custom objects (following their dependencies)
أفضل الممارسات
Batch Your Requests
- Don’t send records one at a time
- Group up to 60 records per API call
- This maximizes throughput within rate limits
Handle Rate Limits
- Implement delays between requests (600ms minimum for sustained imports)
- Use exponential backoff when you hit limits
- Monitor for 429 (Too Many Requests) responses
Validate Data First
- Clean and validate your data before importing
- Check required fields are populated
- Verify formats match Twenty’s requirements (see Field Mapping)
Log Everything
- Log every record imported (including IDs)
- Log errors with full context
- This helps debug issues and verify completion
Test First
- Test with a small batch (10-20 records)
- Verify data appears correctly in Twenty
- Then run the full import
Upsert to Avoid Duplicates
The GraphQL API supports batch upsert — update if the record exists, create if not. This prevents duplicates when re-running imports.Finding Object and Field Names
To see available objects and fields:- Go to Settings → API and Webhooks
- Browse the Metadata API
- View all standard and custom objects with their fields
Professional Services
For complex API migrations, our partners can help:| Service | What’s Included |
|---|---|
| Data Model Design | design your optimal data structure |
| Migration Scripts | write and run the import scripts |
| Data Transformation | handle complex mapping and cleanup |
| Validation & QA | verify the migration is complete |
- Migrations of 100,000+ records
- Complex data transformations
- Tight timelines
- Teams without developer resources
FAQ
What's the difference between GraphQL and REST?
What's the difference between GraphQL and REST?
GraphQL lets you request exactly the data you need in a single query and is better for complex operations. REST uses standard HTTP methods (GET, POST, PUT, DELETE) and may be more familiar if you’ve worked with traditional APIs.
Can I update existing records via API?
Can I update existing records via API?
نعم! Use update mutations (GraphQL) or PUT/PATCH requests (REST) with the record’s
id.How do I handle duplicates?
How do I handle duplicates?
Query for existing records first using unique identifiers (email, domain). Update if exists, create if not.
Can I delete records via API?
Can I delete records via API?
Yes, use delete mutations (GraphQL) or DELETE requests (REST).
Is there a Python or Node.js SDK?
Is there a Python or Node.js SDK?
Not currently, but both APIs work with any HTTP client in any language.