How to install twenty?

Run: claude skill add --url github.com/openclaw/skills/tree/main/skills/byungkyu/twenty

Twenty CRM

Name: twenty
Rating: 5 (4304 reviews)
Author: byungkyu

Access the Twenty CRM API with managed authentication. Manage companies, people, opportunities, notes, tasks, and workflows.

Quick Start

bash

# List companies
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/twenty/rest/companies?limit=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

code

https://gateway.maton.ai/twenty/rest/{resource}

Replace {resource} with the Twenty API resource (e.g., companies, people, opportunities). The gateway proxies requests to api.twenty.com/rest/ and automatically injects your API token.

Authentication

All requests require the Maton API key in the Authorization header:

code

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

bash

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

Sign in or create an account at maton.ai
Go to maton.ai/settings
Copy your API key

Connection Management

Manage your Twenty connections at https://ctrl.maton.ai.

List Connections

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=twenty&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

bash

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'twenty'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

json

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "twenty",
    "metadata": {}
  }
}

Open the returned url in a browser to complete authorization.

Delete Connection

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Twenty connections, specify which one to use with the Maton-Connection header:

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/twenty/rest/companies?limit=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Companies

List Companies

bash

GET /twenty/rest/companies?limit=20

Response:

json

{
  "data": {
    "companies": [
      {
        "id": "06290608-8bf0-4806-99ae-a715a6a93fad",
        "name": "Acme Corp",
        "domainName": {
          "primaryLinkUrl": "https://acme.com"
        },
        "employees": 100,
        "address": {
          "addressCity": "San Francisco",
          "addressState": "CA",
          "addressCountry": "United States"
        },
        "createdAt": "2026-03-20T23:59:52.906Z",
        "updatedAt": "2026-03-20T23:59:52.906Z"
      }
    ]
  },
  "pageInfo": {
    "hasNextPage": true,
    "startCursor": "06290608-8bf0-4806-99ae-a715a6a93fad",
    "endCursor": "1f70157c-4ea5-4d81-bc49-e1401abfbb94"
  },
  "totalCount": 50
}

Get Company

bash

GET /twenty/rest/companies/{id}

Create Company

bash

POST /twenty/rest/companies
Content-Type: application/json

{
  "name": "New Company",
  "domainName": {
    "primaryLinkUrl": "https://newcompany.com"
  },
  "employees": 50
}

Update Company

bash

PATCH /twenty/rest/companies/{id}
Content-Type: application/json

{
  "name": "Updated Company Name",
  "employees": 100
}

Delete Company

bash

DELETE /twenty/rest/companies/{id}

People

List People

bash

GET /twenty/rest/people?limit=20

Response:

json

{
  "data": {
    "people": [
      {
        "id": "7a93d1e5-3f74-4945-8a65-d7f996083f72",
        "name": {
          "firstName": "John",
          "lastName": "Doe"
        },
        "emails": {
          "primaryEmail": "john@company.com"
        },
        "phones": {
          "primaryPhoneNumber": "5551234567",
          "primaryPhoneCallingCode": "+1"
        },
        "jobTitle": "CEO",
        "city": "San Francisco",
        "companyId": "06290608-8bf0-4806-99ae-a715a6a93fad"
      }
    ]
  },
  "pageInfo": {...},
  "totalCount": 100
}

Get Person

bash

GET /twenty/rest/people/{id}

Create Person

bash

POST /twenty/rest/people
Content-Type: application/json

{
  "name": {
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "emails": {
    "primaryEmail": "jane@company.com"
  },
  "jobTitle": "CTO",
  "companyId": "06290608-8bf0-4806-99ae-a715a6a93fad"
}

Update Person

bash

PATCH /twenty/rest/people/{id}
Content-Type: application/json

{
  "jobTitle": "VP of Engineering"
}

Delete Person

bash

DELETE /twenty/rest/people/{id}

Opportunities

List Opportunities

bash

GET /twenty/rest/opportunities?limit=20

Response:

json

{
  "data": {
    "opportunities": [
      {
        "id": "2beb07b0-340c-41d7-be33-5aa91757f329",
        "name": "Enterprise Deal",
        "amount": {
          "amountMicros": 75000000000,
          "currencyCode": "USD"
        },
        "closeDate": "2026-01-25T16:26:00.000Z",
        "stage": "SCREENING",
        "companyId": "1f70157c-4ea5-4d81-bc49-e1401abfbb94",
        "pointOfContactId": "edf6d445-13a7-4373-9a47-8f89e8c0a877"
      }
    ]
  },
  "pageInfo": {...},
  "totalCount": 25
}

Note: Amount is stored in micros (divide by 1,000,000 for actual value).

Get Opportunity

bash

GET /twenty/rest/opportunities/{id}

Create Opportunity

bash

POST /twenty/rest/opportunities
Content-Type: application/json

{
  "name": "New Deal",
  "amount": {
    "amountMicros": 50000000000,
    "currencyCode": "USD"
  },
  "stage": "SCREENING",
  "closeDate": "2026-06-01T00:00:00.000Z",
  "companyId": "06290608-8bf0-4806-99ae-a715a6a93fad"
}

Update Opportunity

bash

PATCH /twenty/rest/opportunities/{id}
Content-Type: application/json

{
  "stage": "MEETING",
  "amount": {
    "amountMicros": 60000000000,
    "currencyCode": "USD"
  }
}

Delete Opportunity

bash

DELETE /twenty/rest/opportunities/{id}

Notes

List Notes

bash

GET /twenty/rest/notes?limit=20

Get Note

bash

GET /twenty/rest/notes/{id}

Create Note

bash

POST /twenty/rest/notes
Content-Type: application/json

{
  "title": "Meeting Notes",
  "body": "Discussed Q2 roadmap and partnership opportunities."
}

Update Note

bash

PATCH /twenty/rest/notes/{id}
Content-Type: application/json

{
  "body": "Updated meeting notes with action items."
}

Delete Note

bash

DELETE /twenty/rest/notes/{id}

Tasks

List Tasks

bash

GET /twenty/rest/tasks?limit=20

Get Task

bash

GET /twenty/rest/tasks/{id}

Create Task

bash

POST /twenty/rest/tasks
Content-Type: application/json

{
  "title": "Follow up with client",
  "body": "Send proposal and schedule demo",
  "dueAt": "2026-04-01T00:00:00.000Z",
  "status": "TODO"
}

Update Task

bash

PATCH /twenty/rest/tasks/{id}
Content-Type: application/json

{
  "status": "DONE"
}

Delete Task

bash

DELETE /twenty/rest/tasks/{id}

Workspace Members

List Workspace Members

bash

GET /twenty/rest/workspaceMembers?limit=20

Filtering

Use the filter query parameter to narrow results:

bash

GET /twenty/rest/companies?filter=employees[gte]:100
GET /twenty/rest/opportunities?filter=stage[eq]:"MEETING"
GET /twenty/rest/people?filter=name.firstName[ilike]:"%john%"

Comparators:

eq, neq - Equal, not equal
gt, gte, lt, lte - Greater/less than
in - In array: id[in]:["id-1","id-2"]
is - Null check: deletedAt[is]:NULL
like, ilike - Pattern match (case-sensitive/insensitive)
startsWith - Prefix match
contain, notContain - Contains value

Advanced filtering:

bash

filter=or(stage[eq]:"MEETING",stage[eq]:"SCREENING")
filter=and(employees[gte]:100,idealCustomerProfile[eq]:true)

Pagination

Twenty uses cursor-based pagination:

bash

GET /twenty/rest/companies?limit=20&starting_after={endCursor}

Parameters:

limit - Results per page (default: 60, max: 60)
starting_after - Cursor for next page (use endCursor from response)
ending_before - Cursor for previous page (use startCursor from response)

Response includes:

json

{
  "pageInfo": {
    "hasNextPage": true,
    "hasPreviousPage": false,
    "startCursor": "uuid-1",
    "endCursor": "uuid-2"
  },
  "totalCount": 150
}

Ordering

Use order_by to sort results:

bash

GET /twenty/rest/companies?order_by=createdAt[DescNullsLast]
GET /twenty/rest/opportunities?order_by=closeDate,amount[DescNullsFirst]

Directions: AscNullsFirst, AscNullsLast, DescNullsFirst, DescNullsLast

Code Examples

JavaScript

javascript

const response = await fetch(
  'https://gateway.maton.ai/twenty/rest/companies?limit=10',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/twenty/rest/companies',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'limit': 10}
)
data = response.json()

Create Company

python

import os
import requests

response = requests.post(
    'https://gateway.maton.ai/twenty/rest/companies',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'New Company',
        'domainName': {'primaryLinkUrl': 'https://newcompany.com'},
        'employees': 50
    }
)

Notes

All IDs are UUIDs
Timestamps are in ISO 8601 format
Amount fields use micros (multiply by 1,000,000)
Opportunity stages: SCREENING, MEETING, PROPOSAL, NEGOTIATION, WON, LOST
Task statuses: TODO, IN_PROGRESS, DONE
IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
IMPORTANT: When piping curl output to jq, environment variables may not expand correctly in some shells

Error Handling

Status	Meaning
400	Missing Twenty connection or invalid request
401	Invalid or missing Maton API key
404	Resource not found
429	Rate limited
4xx/5xx	Passthrough error from Twenty API

twenty

安装

文档

Twenty CRM

Quick Start

Base URL

Authentication

Getting Your API Key

Connection Management

List Connections

Create Connection

Get Connection

Delete Connection

Specifying Connection

API Reference

Companies

List Companies

Get Company

Create Company

Update Company

Delete Company

People

List People

Get Person

Create Person

Update Person

Delete Person

Opportunities

List Opportunities

Get Opportunity

Create Opportunity

Update Opportunity

Delete Opportunity

Notes

List Notes

Get Note

Create Note

Update Note

Delete Note

Tasks

List Tasks

Get Task

Create Task

Update Task

Delete Task

Workspace Members

List Workspace Members

Filtering

Pagination

Ordering

Code Examples

JavaScript

Python

Create Company

Notes

Error Handling

Resources