Documentation
Documentation
https://docs.twenty.com/developers/extend/api
APIReference
https://docs.twenty.com/api-reference/openapi.json
OpenAPI Specification
openapi: 3.0.1
info:
title: Twenty CRM Companies People API
description: 'REST specification for Twenty, the open-source CRM. Twenty auto-generates a REST API (and a parallel GraphQL API) from your workspace data model. This document covers the Core API (CRUD over records such as People, Companies, Opportunities, Notes, and Tasks) and the Metadata API (schema management for objects and fields). Endpoints are served from a per-workspace base URL: https://api.twenty.com on Twenty Cloud, or https://{your-domain} when self-hosted. The Core API lives under /rest and the Metadata API under /rest/metadata. All requests are authenticated with a Bearer API key created in Settings -> API & Webhooks.'
termsOfService: https://twenty.com/legal/tos
contact:
name: Twenty
url: https://twenty.com/
license:
name: AGPL-3.0
url: https://github.com/twentyhq/twenty/blob/main/LICENSE
version: '0.40'
servers:
- url: https://api.twenty.com
description: Twenty Cloud
- url: https://{domain}
description: Self-hosted workspace
variables:
domain:
default: your-domain.com
description: Your self-hosted Twenty instance host.
security:
- bearerAuth: []
tags:
- name: People
description: Core API CRUD over person records.
paths:
/rest/people:
get:
operationId: listPeople
tags:
- People
summary: List people
description: Returns a page of person records. Supports filter, orderBy, limit, and cursor-based pagination.
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/OrderBy'
- $ref: '#/components/parameters/Filter'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/EndingBefore'
- $ref: '#/components/parameters/Depth'
responses:
'200':
description: A page of people.
content:
application/json:
schema:
$ref: '#/components/schemas/PeopleListResponse'
post:
operationId: createPerson
tags:
- People
summary: Create a person
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PersonInput'
responses:
'201':
description: The created person.
content:
application/json:
schema:
$ref: '#/components/schemas/PersonResponse'
/rest/people/{id}:
parameters:
- $ref: '#/components/parameters/RecordId'
get:
operationId: getPerson
tags:
- People
summary: Get a person
parameters:
- $ref: '#/components/parameters/Depth'
responses:
'200':
description: The requested person.
content:
application/json:
schema:
$ref: '#/components/schemas/PersonResponse'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updatePerson
tags:
- People
summary: Update a person
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PersonInput'
responses:
'200':
description: The updated person.
content:
application/json:
schema:
$ref: '#/components/schemas/PersonResponse'
delete:
operationId: deletePerson
tags:
- People
summary: Delete a person
responses:
'200':
$ref: '#/components/responses/Deleted'
/rest/batch/people:
post:
operationId: createPeopleBatch
tags:
- People
summary: Batch create people
description: Create up to 60 person records in a single request.
requestBody:
required: true
content:
application/json:
schema:
type: array
maxItems: 60
items:
$ref: '#/components/schemas/PersonInput'
responses:
'201':
description: The created people.
content:
application/json:
schema:
$ref: '#/components/schemas/PeopleListResponse'
components:
parameters:
OrderBy:
name: order_by
in: query
description: Field and direction to sort by, e.g. `createdAt[DescNullsLast]`.
schema:
type: string
Depth:
name: depth
in: query
description: Relation traversal depth (0, 1, or 2) to embed related records.
schema:
type: integer
enum:
- 0
- 1
- 2
default: 1
StartingAfter:
name: starting_after
in: query
description: Cursor for forward pagination.
schema:
type: string
Filter:
name: filter
in: query
description: Filter expression, e.g. `name[eq]:Acme`.
schema:
type: string
RecordId:
name: id
in: path
required: true
description: The UUID of the record.
schema:
type: string
format: uuid
EndingBefore:
name: ending_before
in: query
description: Cursor for backward pagination.
schema:
type: string
Limit:
name: limit
in: query
description: Maximum number of records to return per page.
schema:
type: integer
default: 60
maximum: 60
schemas:
Emails:
type: object
properties:
primaryEmail:
type: string
format: email
additionalEmails:
type: array
items:
type: string
PageInfo:
type: object
properties:
hasNextPage:
type: boolean
startCursor:
type: string
endCursor:
type: string
PersonInput:
type: object
properties:
name:
$ref: '#/components/schemas/FullName'
emails:
$ref: '#/components/schemas/Emails'
phones:
$ref: '#/components/schemas/Phones'
jobTitle:
type: string
city:
type: string
companyId:
type: string
format: uuid
PersonResponse:
type: object
properties:
data:
type: object
properties:
person:
$ref: '#/components/schemas/Person'
Error:
type: object
properties:
statusCode:
type: integer
messages:
type: array
items:
type: string
error:
type: string
FullName:
type: object
properties:
firstName:
type: string
lastName:
type: string
PeopleListResponse:
type: object
properties:
data:
type: object
properties:
people:
type: array
items:
$ref: '#/components/schemas/Person'
pageInfo:
$ref: '#/components/schemas/PageInfo'
totalCount:
type: integer
Phones:
type: object
properties:
primaryPhoneNumber:
type: string
primaryPhoneCallingCode:
type: string
primaryPhoneCountryCode:
type: string
Links:
type: object
properties:
primaryLinkUrl:
type: string
primaryLinkLabel:
type: string
secondaryLinks:
type: array
items:
type: object
Person:
type: object
properties:
id:
type: string
format: uuid
name:
$ref: '#/components/schemas/FullName'
emails:
$ref: '#/components/schemas/Emails'
phones:
$ref: '#/components/schemas/Phones'
jobTitle:
type: string
city:
type: string
linkedinLink:
$ref: '#/components/schemas/Links'
companyId:
type: string
format: uuid
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
responses:
NotFound:
description: The record was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Deleted:
description: The record was deleted.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
deletePerson:
type: object
properties:
id:
type: string
format: uuid
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: 'API key created in Settings -> API & Webhooks, sent as `Authorization: Bearer <API_KEY>`.'