Twenty CRM REST API

Manage CRM data via Twenty's REST API.

Authentication

All requests use Bearer token auth. The TWENTY_API_KEY env var must be set.

curl -s "$TWENTY_URL/rest/<endpoint>" \
  -H "Authorization: Bearer $TWENTY_API_KEY"

Core Endpoints (Base: $TWENTY_URL/rest)

People (Contacts)

# List all people
curl -s "$TWENTY_URL/rest/people" \
  -H "Authorization: Bearer $TWENTY_API_KEY"

# Get a person by ID
curl -s "$TWENTY_URL/rest/people/{id}" \
  -H "Authorization: Bearer $TWENTY_API_KEY"

# Create a person
curl -s -X POST "$TWENTY_URL/rest/people" \
  -H "Authorization: Bearer $TWENTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": {"firstName": "Jane", "lastName": "Doe"},
    "emails": {"primaryEmail": "jane@example.com"},
    "phones": {"primaryPhoneNumber": "+1234567890"}
  }'

# Update a person
curl -s -X PATCH "$TWENTY_URL/rest/people/{id}" \
  -H "Authorization: Bearer $TWENTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": {"firstName": "Updated"}}'

# Delete a person
curl -s -X DELETE "$TWENTY_URL/rest/people/{id}" \
  -H "Authorization: Bearer $TWENTY_API_KEY"

Companies

# List companies
curl -s "$TWENTY_URL/rest/companies" \
  -H "Authorization: Bearer $TWENTY_API_KEY"

# Create a company
curl -s -X POST "$TWENTY_URL/rest/companies" \
  -H "Authorization: Bearer $TWENTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "domainName": {"primaryLinkUrl": "https://acme.com"}
  }'

Opportunities (Deals)

# List opportunities
curl -s "$TWENTY_URL/rest/opportunities" \
  -H "Authorization: Bearer $TWENTY_API_KEY"

# Create an opportunity
curl -s -X POST "$TWENTY_URL/rest/opportunities" \
  -H "Authorization: Bearer $TWENTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deal Name",
    "stage": "MEETING",
    "amount": {"amountMicros": 50000000000, "currencyCode": "USD"},
    "companyId": "COMPANY_ID"
  }'

Tasks

# List tasks
curl -s "$TWENTY_URL/rest/tasks" \
  -H "Authorization: Bearer $TWENTY_API_KEY"

# Create a task
curl -s -X POST "$TWENTY_URL/rest/tasks" \
  -H "Authorization: Bearer $TWENTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Follow up with client",
    "status": "TODO",
    "dueAt": "2026-03-15T00:00:00Z"
  }'

Notes

# List notes
curl -s "$TWENTY_URL/rest/notes" \
  -H "Authorization: Bearer $TWENTY_API_KEY"

# Create a note
curl -s -X POST "$TWENTY_URL/rest/notes" \
  -H "Authorization: Bearer $TWENTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meeting Notes",
    "body": "Discussion about Q2 goals..."
  }'

Search / Filter

# Filter by field (e.g., find people by email)
curl -s "$TWENTY_URL/rest/people?filter=emails.primaryEmail[eq]=jane@example.com" \
  -H "Authorization: Bearer $TWENTY_API_KEY"

# Sort and limit
curl -s "$TWENTY_URL/rest/companies?order_by=createdAt[AscNullsLast]&limit=10" \
  -H "Authorization: Bearer $TWENTY_API_KEY"

Notes

• REST API uses standard HTTP methods (GET/POST/PATCH/DELETE)
• Set TWENTY_URL to your instance (e.g., http://127.0.0.1:3001 or your Tailscale URL)
• GraphQL also available at /graphql and /metadata for advanced queries
• All responses return {"data": {...}} format