Twenty CRM 开源现代化客户关系管理平台 API 使用指南

twenty by vm0-ai/vm0-skills

75 周安装量

51 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/vm0-ai/vm0-skills --skill twenty

CRM 开源项目 API

🇨🇳中文介绍

Twenty CRM

开源现代化 CRM 平台。通过 REST 或 GraphQL API 管理人员、公司、商机、笔记和任务。

官方文档：https://docs.twenty.com/developers/api-and-webhooks/api

何时使用

在需要以下操作时使用此技能：

管理联系人（人员）和公司
跟踪商机和交易
创建笔记和任务
将 CRM 数据与其他系统同步
查询 CRM 元数据和自定义字段
为 CRM 事件设置 Webhook

先决条件

在 https://app.twenty.com/ 创建账户
前往 设置 → API 与 Webhook 以生成 API 密钥

设置环境变量：

export TWENTY_TOKEN="your-api-key"

使用方法

1. 列出公司

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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

3. 列出人员（联系人）

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

写入 /tmp/twenty_request.json：

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

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

5. 获取特定记录

注意： 将 {companyId} 和 {personId} 替换为从上述“列出公司”或“列出人员”端点获取的实际 ID（在响应中查找 id 字段）。

# 通过 ID 获取公司
curl -s -X GET "https://api.twenty.com/rest/companies/{companyId}" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)"

# 通过 ID 获取人员
curl -s -X GET "https://api.twenty.com/rest/people/{personId}" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)"

注意： 将 {companyId} 替换为从上述“列出公司”端点获取的实际公司 ID。

写入 /tmp/twenty_request.json：

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

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

注意： 将 {companyId} 替换为从上述“列出公司”端点获取的实际公司 ID。

curl -s -X DELETE "https://api.twenty.com/rest/companies/{companyId}" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)"

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

写入 /tmp/twenty_request.json：

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

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

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

写入 /tmp/twenty_request.json：

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

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

12. 获取元数据（对象模式）

列出所有对象类型及其字段：

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

获取特定对象的元数据：

curl -s -X GET "https://api.twenty.com/rest/metadata/objects/companies" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)"

写入 /tmp/twenty_request.json：

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

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

类别	端点	描述
核心对象	`/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 端点

参数	描述
`limit`	要返回的记录数（默认：20）
`offset`	要跳过的记录数
`filter`	过滤条件（JSON）
`orderBy`	排序顺序

带过滤器的示例：

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

{
  "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"
  }
}

API 演练场：在 Twenty 应用的设置 → API 与 Webhook 中测试 API 调用
速率限制：云端版本有速率限制；自托管版本无限制
GraphQL：对于涉及关系的复杂查询，使用 GraphQL
REST：对于简单的 CRUD 操作，使用 REST
自定义对象：Twenty 支持自定义对象；使用元数据 API 来发现模式
Webhook：在设置 → API 与 Webhook 中设置 Webhook 以获取实时事件

🇺🇸English

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

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

Set environment variables:

export TWENTY_TOKEN="your-api-key"

How to Use

1. List Companies

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

With pagination:

curl -s -X GET "https://api.twenty.com/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 "https://api.twenty.com/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 "https://api.twenty.com/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 "https://api.twenty.com/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 "https://api.twenty.com/rest/companies/{companyId}" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)"

# Get person by ID
curl -s -X GET "https://api.twenty.com/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 "https://api.twenty.com/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 "https://api.twenty.com/rest/companies/{companyId}" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)"

8. List Notes

curl -s -X GET "https://api.twenty.com/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 "https://api.twenty.com/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 "https://api.twenty.com/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 "https://api.twenty.com/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 "https://api.twenty.com/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 "https://api.twenty.com/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 "https://api.twenty.com/graphql" --header "Authorization: Bearer $(printenv TWENTY_TOKEN)" --header "Content-Type: application/json" -d @/tmp/twenty_request.json | jq '.data.companies.edges'

API Endpoints

Category	Endpoint	Description
Core Objects	`/rest/companies`	Manage companies
`/rest/people`	Manage contacts
`/rest/opportunities`	Manage deals/opportunities
`/rest/notes`	Manage notes
`/rest/tasks`	Manage tasks

Query Parameters

Parameter	Description
`limit`	Number of records to return (default: 20)
`offset`	Number of records to skip
`filter`	Filter conditions (JSON)
`orderBy`	Sort order

Example with filters:

curl -s -X GET "https://api.twenty.com/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

API Playground : Test API calls at Settings → APIs & Webhooks in the Twenty app
Rate Limits : Cloud has rate limits; self-hosted has no limits
GraphQL : Use GraphQL for complex queries with relationships
REST : Use REST for simple CRUD operations
Custom Objects : Twenty supports custom objects; use metadata API to discover schema
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

Weekly Installs

Repository

vm0-ai/vm0-skills

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

gemini-cli65

opencode63

codex63

github-copilot61

amp60

kimi-cli59

lark-cli 共享规则：飞书资源操作指南与权限配置详解

39,000 周安装

Twenty CRM 开源现代化客户关系管理平台 API 使用指南

🇨🇳中文介绍

Twenty CRM

何时使用

先决条件

使用方法

1. 列出公司

相关 Skills

2. 创建公司

3. 列出人员（联系人）

4. 创建人员

5. 获取特定记录

6. 更新记录

7. 删除记录

8. 列出笔记

9. 创建笔记

10. 列出任务

11. 创建任务

12. 获取元数据（对象模式）

13. GraphQL 查询

API 端点

查询参数

响应格式

指南

资源

🇺🇸English

Twenty CRM

When to Use

Prerequisites

How to Use

1. List Companies

2. Create a Company

3. List People (Contacts)

4. Create a Person

5. Get a Specific Record

6. Update a Record

7. Delete a Record

8. List Notes

9. Create a Note

10. List Tasks

11. Create a Task

12. Get Metadata (Object Schema)

13. GraphQL Query

API Endpoints

Query Parameters

Response Format

Guidelines

Resources

最新 Skills