Twenty CRM

Open-source modern CRM platform. Manage people, companies, opportunities, notes, and tasks via REST or GraphQL API.

Official docs: https://docs.twenty.com/developers/api-and-webhooks/api

When to Use

Use this skill when you need to:

• Manage contacts (people) and companies
• Track opportunities and deals
• Create notes and tasks
• Sync CRM data with other systems
• Query CRM metadata and custom fields
• Set up webhooks for CRM events

Prerequisites

1. Create an account at https://app.twenty.com/
2. Go to Settings → APIs & Webhooks to generate an API key

Set environment variables:

# For Twenty Cloud
export TWENTY_TOKEN="your-api-key"
export TWENTY_API_URL="https://api.twenty.com"

# For self-hosted instances
export TWENTY_API_URL="https://your-domain.com"

How to Use

1. List Companies

curl -s -X GET "$(printenv TWENTY_API_URL)/rest/companies" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" | jq '.data.companies[:3]'

With pagination:

curl -s -X GET "$(printenv TWENTY_API_URL)/rest/companies?limit=10&offset=0" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" | jq '.data.companies'

2. Create a Company

Write to /tmp/twenty_request.json:

{
  "name": "Acme Corp",
  "domainName": "acme.com",
  "address": "123 Main St, San Francisco, CA"
}

Then run:

curl -s -X POST "$(printenv TWENTY_API_URL)/rest/companies" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" --header "Content-Type: application/json" -d @/tmp/twenty_request.json

3. List People (Contacts)

curl -s -X GET "$(printenv TWENTY_API_URL)/rest/people" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" | jq '.data.people[:3]'

4. Create a Person

Write to /tmp/twenty_request.json:

{
  "name": {
    "firstName": "John",
    "lastName": "Doe"
  },
  "email": "john@example.com",
  "phone": "+1234567890"
}

Then run:

curl -s -X POST "$(printenv TWENTY_API_URL)/rest/people" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" --header "Content-Type: application/json" -d @/tmp/twenty_request.json

5. Get a Specific Record

Note: Replace {companyId} and {personId} with actual IDs obtained from the "List Companies" or "List People" endpoints above (look for the id field in the response).

# Get company by ID
curl -s -X GET "$(printenv TWENTY_API_URL)/rest/companies/{companyId}" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)"

# Get person by ID
curl -s -X GET "$(printenv TWENTY_API_URL)/rest/people/{personId}" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)"

6. Update a Record

Note: Replace {companyId} with an actual company ID from the "List Companies" endpoint above.

Write to /tmp/twenty_request.json:

{
  "name": "Acme Corporation",
  "employees": 500
}

Then run:

curl -s -X PATCH "$(printenv TWENTY_API_URL)/rest/companies/{companyId}" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" --header "Content-Type: application/json" -d @/tmp/twenty_request.json

7. Delete a Record

Note: Replace {companyId} with an actual company ID from the "List Companies" endpoint above.

curl -s -X DELETE "$(printenv TWENTY_API_URL)/rest/companies/{companyId}" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)"

8. List Notes

curl -s -X GET "$(printenv TWENTY_API_URL)/rest/notes" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" | jq '.data.notes[:3]'

9. Create a Note

Write to /tmp/twenty_request.json:

{
  "title": "Meeting Notes",
  "body": "Discussed Q1 roadmap and budget allocation."
}

Then run:

curl -s -X POST "$(printenv TWENTY_API_URL)/rest/notes" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" --header "Content-Type: application/json" -d @/tmp/twenty_request.json

10. List Tasks

curl -s -X GET "$(printenv TWENTY_API_URL)/rest/tasks" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" | jq '.data.tasks[:3]'

11. Create a Task

Write to /tmp/twenty_request.json:

{
  "title": "Follow up with client",
  "dueAt": "2025-01-15T10:00:00Z",
  "status": "TODO"
}

Then run:

curl -s -X POST "$(printenv TWENTY_API_URL)/rest/tasks" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" --header "Content-Type: application/json" -d @/tmp/twenty_request.json

12. Get Metadata (Object Schema)

List all object types and their fields:

curl -s -X GET "$(printenv TWENTY_API_URL)/rest/metadata/objects" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" | jq '.data.objects[] | {name: .nameSingular, fields: [.fields[].name]}'

Get metadata for a specific object:

curl -s -X GET "$(printenv TWENTY_API_URL)/rest/metadata/objects/companies" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)"

13. GraphQL Query

Write to /tmp/twenty_request.json:

{
  "query": "query { companies(first: 5) { edges { node { id name domainName } } } }"
}

Then run:

curl -s -X POST "$(printenv TWENTY_API_URL)/graphql" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" --header "Content-Type: application/json" -d @/tmp/twenty_request.json | jq '.data.companies.edges'

API Endpoints

Query Parameters

Example with filters:

curl -s -X GET "$(printenv TWENTY_API_URL)/rest/companies?filter={\"name\":{\"like\":\"%Acme%\"}}" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" | jq '.data.companies'

Response Format

{
  "data": {
  "companies": [
  {
  "id": "uuid",
  "name": "Company Name",
  "domainName": "example.com",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z"
  }
  ]
  },
  "pageInfo": {
  "hasNextPage": true,
  "endCursor": "cursor-string"
  }
}

Guidelines

1. API Playground: Test API calls at Settings → APIs & Webhooks in the Twenty app
2. Rate Limits: Cloud has rate limits; self-hosted has no limits
3. GraphQL: Use GraphQL for complex queries with relationships
4. REST: Use REST for simple CRUD operations
5. Custom Objects: Twenty supports custom objects; use metadata API to discover schema
6. Webhooks: Set up webhooks at Settings → APIs & Webhooks for real-time events

Resources

• API Docs: https://docs.twenty.com/developers/api-and-webhooks/api
• Webhooks: https://docs.twenty.com/developers/api-and-webhooks/webhooks
• GitHub: https://github.com/twentyhq/twenty
• Discord: https://discord.gg/cx5n4Jzs57