Back to Details

twenty

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Twenty CRM

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
开源现代化CRM平台。可通过REST或GraphQL API管理联系人、公司、销售机会、笔记和任务。
官方文档：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
当你需要以下操作时，可使用该技能：
  • 管理联系人与公司
  • 跟踪销售机会与交易
  • 创建笔记与任务
  • 与其他系统同步CRM数据
  • 查询CRM元数据与自定义字段
  • 为CRM事件设置webhooks

Prerequisites

前置条件

  1. Create an account at https://app.twenty.com/
  2. Go to Settings → APIs & Webhooks to generate an API key
Set environment variables:
bash
undefined
  1. 在https://app.twenty.com/ 创建账户
  2. 进入设置 → APIs & Webhooks生成API密钥
设置环境变量：
bash
undefined

For Twenty Cloud

For Twenty Cloud

export TWENTY_API_KEY="your-api-key" export TWENTY_API_URL="https://api.twenty.com"
export TWENTY_API_KEY="your-api-key" export TWENTY_API_URL="https://api.twenty.com"

For self-hosted instances

For self-hosted instances

export TWENTY_API_URL="https://your-domain.com"

---


> **Important:** When using `$VAR` in a command that pipes to another command, wrap the command containing `$VAR` in `bash -c '...'`. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
> ```bash
> bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
> ```
export TWENTY_API_URL="https://your-domain.com"

---


> **重要提示：** 当在带有管道的命令中使用`$VAR`时，请将包含`$VAR`的命令用`bash -c '...'`包裹。由于Claude Code的一个bug，直接使用管道时环境变量会被静默清除。
> ```bash
> bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
> ```

How to Use

使用方法

1. List Companies

1. 列出公司列表

bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/companies" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.companies[:3]'
With pagination:
bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/companies?limit=10&offset=0" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.companies'
bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/companies" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.companies[:3]'
分页查询：
bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/companies?limit=10&offset=0" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.companies'

2. Create a Company

2. 创建公司

Write to 
/tmp/twenty_request.json
:
json
{
  "name": "Acme Corp",
  "domainName": "acme.com",
  "address": "123 Main St, San Francisco, CA"
}
Then run:
bash
bash -c 'curl -s -X POST "${TWENTY_API_URL}/rest/companies" --header "Authorization: Bearer ${TWENTY_API_KEY}" --header "Content-Type: application/json" -d @/tmp/twenty_request.json'
写入内容到
/tmp/twenty_request.json
：
json
{
  "name": "Acme Corp",
  "domainName": "acme.com",
  "address": "123 Main St, San Francisco, CA"
}
然后执行：
bash
bash -c 'curl -s -X POST "${TWENTY_API_URL}/rest/companies" --header "Authorization: Bearer ${TWENTY_API_KEY}" --header "Content-Type: application/json" -d @/tmp/twenty_request.json'

3. List People (Contacts)

3. 列出联系人列表

bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/people" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.people[:3]'
bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/people" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.people[:3]'

4. Create a Person

4. 创建联系人

Write to 
/tmp/twenty_request.json
:
json
{
  "name": {
    "firstName": "John",
    "lastName": "Doe"
  },
  "email": "john@example.com",
  "phone": "+1234567890"
}
Then run:
bash
bash -c 'curl -s -X POST "${TWENTY_API_URL}/rest/people" --header "Authorization: Bearer ${TWENTY_API_KEY}" --header "Content-Type: application/json" -d @/tmp/twenty_request.json'
写入内容到
/tmp/twenty_request.json
：
json
{
  "name": {
    "firstName": "John",
    "lastName": "Doe"
  },
  "email": "john@example.com",
  "phone": "+1234567890"
}
然后执行：
bash
bash -c 'curl -s -X POST "${TWENTY_API_URL}/rest/people" --header "Authorization: Bearer ${TWENTY_API_KEY}" --header "Content-Type: application/json" -d @/tmp/twenty_request.json'

5. Get a Specific Record

5. 获取指定记录

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).
bash
undefined
注意： 替换
{companyId}
和
{personId}
为上述“列出公司列表”或“列出联系人列表”接口返回的实际ID（在响应中查找
id
字段）。
bash
undefined

Get company by ID

根据ID获取公司信息

bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/companies/{companyId}" --header "Authorization: Bearer ${TWENTY_API_KEY}"'
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/companies/{companyId}" --header "Authorization: Bearer ${TWENTY_API_KEY}"'

Get person by ID

根据ID获取联系人信息

bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/people/{personId}" --header "Authorization: Bearer ${TWENTY_API_KEY}"'
undefined
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/people/{personId}" --header "Authorization: Bearer ${TWENTY_API_KEY}"'
undefined

6. Update a Record

6. 更新记录

Note: Replace 
{companyId}
with an actual company ID from the "List Companies" endpoint above.
Write to 
/tmp/twenty_request.json
:
json
{
  "name": "Acme Corporation",
  "employees": 500
}
Then run:
bash
bash -c 'curl -s -X PATCH "${TWENTY_API_URL}/rest/companies/{companyId}" --header "Authorization: Bearer ${TWENTY_API_KEY}" --header "Content-Type: application/json" -d @/tmp/twenty_request.json'
注意： 替换
{companyId}
为上述“列出公司列表”接口返回的实际公司ID。
写入内容到
/tmp/twenty_request.json
：
json
{
  "name": "Acme Corporation",
  "employees": 500
}
然后执行：
bash
bash -c 'curl -s -X PATCH "${TWENTY_API_URL}/rest/companies/{companyId}" --header "Authorization: Bearer ${TWENTY_API_KEY}" --header "Content-Type: application/json" -d @/tmp/twenty_request.json'

7. Delete a Record

7. 删除记录

Note: Replace 
{companyId}
with an actual company ID from the "List Companies" endpoint above.
bash
curl -s -X DELETE "${TWENTY_API_URL}/rest/companies/{companyId}" --header "Authorization: Bearer ${TWENTY_API_KEY}"
注意： 替换
{companyId}
为上述“列出公司列表”接口返回的实际公司ID。
bash
curl -s -X DELETE "${TWENTY_API_URL}/rest/companies/{companyId}" --header "Authorization: Bearer ${TWENTY_API_KEY}"

8. List Notes

8. 列出笔记列表

bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/notes" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.notes[:3]'
bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/notes" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.notes[:3]'

9. Create a Note

9. 创建笔记

Write to 
/tmp/twenty_request.json
:
json
{
  "title": "Meeting Notes",
  "body": "Discussed Q1 roadmap and budget allocation."
}
Then run:
bash
bash -c 'curl -s -X POST "${TWENTY_API_URL}/rest/notes" --header "Authorization: Bearer ${TWENTY_API_KEY}" --header "Content-Type: application/json" -d @/tmp/twenty_request.json'
写入内容到
/tmp/twenty_request.json
：
json
{
  "title": "Meeting Notes",
  "body": "Discussed Q1 roadmap and budget allocation."
}
然后执行：
bash
bash -c 'curl -s -X POST "${TWENTY_API_URL}/rest/notes" --header "Authorization: Bearer ${TWENTY_API_KEY}" --header "Content-Type: application/json" -d @/tmp/twenty_request.json'

10. List Tasks

10. 列出任务列表

bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/tasks" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.tasks[:3]'
bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/tasks" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.tasks[:3]'

11. Create a Task

11. 创建任务

Write to 
/tmp/twenty_request.json
:
json
{
  "title": "Follow up with client",
  "dueAt": "2025-01-15T10:00:00Z",
  "status": "TODO"
}
Then run:
bash
bash -c 'curl -s -X POST "${TWENTY_API_URL}/rest/tasks" --header "Authorization: Bearer ${TWENTY_API_KEY}" --header "Content-Type: application/json" -d @/tmp/twenty_request.json'
写入内容到
/tmp/twenty_request.json
：
json
{
  "title": "Follow up with client",
  "dueAt": "2025-01-15T10:00:00Z",
  "status": "TODO"
}
然后执行：
bash
bash -c 'curl -s -X POST "${TWENTY_API_URL}/rest/tasks" --header "Authorization: Bearer ${TWENTY_API_KEY}" --header "Content-Type: application/json" -d @/tmp/twenty_request.json'

12. Get Metadata (Object Schema)

12. 获取元数据（对象架构）

List all object types and their fields:
bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/metadata/objects" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.objects[] | {name: .nameSingular, fields: [.fields[].name]}'
Get metadata for a specific object:
bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/metadata/objects/companies" --header "Authorization: Bearer ${TWENTY_API_KEY}"'
列出所有对象类型及其字段：
bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/metadata/objects" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.objects[] | {name: .nameSingular, fields: [.fields[].name]}'
获取指定对象的元数据：
bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/metadata/objects/companies" --header "Authorization: Bearer ${TWENTY_API_KEY}"'

13. GraphQL Query

13. GraphQL查询

Write to 
/tmp/twenty_request.json
:
json
{
  "query": "query { companies(first: 5) { edges { node { id name domainName } } } }"
}
Then run:
bash
bash -c 'curl -s -X POST "${TWENTY_API_URL}/graphql" --header "Authorization: Bearer ${TWENTY_API_KEY}" --header "Content-Type: application/json" -d @/tmp/twenty_request.json' | jq '.data.companies.edges'
写入内容到
/tmp/twenty_request.json
：
json
{
  "query": "query { companies(first: 5) { edges { node { id name domainName } } } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "${TWENTY_API_URL}/graphql" --header "Authorization: Bearer ${TWENTY_API_KEY}" --header "Content-Type: application/json" -d @/tmp/twenty_request.json' | jq '.data.companies.edges'

API Endpoints

API端点

CategoryEndpointDescription
Core Objects
/rest/companies
Manage companies
/rest/people
Manage contacts
/rest/opportunities
Manage deals/opportunities
/rest/notes
Manage notes
/rest/tasks
Manage tasks
/rest/activities
Activity timeline
Metadata
/rest/metadata/objects
List all object schemas
/rest/metadata/objects/{name}
Get specific object schema
/rest/metadata/picklists
Get dropdown field options
GraphQL
/graphql
GraphQL endpoint
分类端点描述
核心对象
/rest/companies
管理公司
/rest/people
管理联系人
/rest/opportunities
管理交易/销售机会
/rest/notes
管理笔记
/rest/tasks
管理任务
/rest/activities
活动时间线
元数据
/rest/metadata/objects
列出所有对象架构
/rest/metadata/objects/{name}
获取指定对象架构
/rest/metadata/picklists
获取下拉字段选项
GraphQL
/graphql
GraphQL端点

Query Parameters

查询参数

ParameterDescription
limit
Number of records to return (default: 20)
offset
Number of records to skip
filter
Filter conditions (JSON)
orderBy
Sort order
Example with filters:
bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/companies?filter={\"name\":{\"like\":\"%Acme%\"}}" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.companies'
参数描述
limit
返回的记录数（默认值：20）
offset
跳过的记录数
filter
过滤条件（JSON格式）
orderBy
排序规则
过滤查询示例：
bash
bash -c 'curl -s -X GET "${TWENTY_API_URL}/rest/companies?filter={\"name\":{\"like\":\"%Acme%\"}}" --header "Authorization: Bearer ${TWENTY_API_KEY}"' | jq '.data.companies'

Response Format

响应格式

json
{
  "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"
  }
}
json
{
  "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
  1. API测试工具: 在Twenty应用的设置 → APIs & Webhooks中测试API调用
  2. 速率限制: 云版本有速率限制；自托管版本无限制
  3. GraphQL: 复杂关联查询请使用GraphQL
  4. REST: 简单CRUD操作请使用REST
  5. 自定义对象: Twenty支持自定义对象；使用元数据API查看其架构
  6. Webhooks: 在设置 → APIs & Webhooks中配置webhooks以接收实时事件

Resources

相关资源