Fabulous CRM public API

Server-to-server access to contacts, companies, deals, activities, lists and properties.

Version 1.0 · generated from docs/openapi.yaml.

Every request carries an API key created in Paramètres → Clés d'API:

Authorization: Bearer wap_<keyId>_<secret>

A key sees and writes every record of the organisation (scopes limit resources, not perimeter; the roles matrix does not apply). A write scope implies the read scope of the same resource. No CORS headers are sent: keys must never live in a browser.

Collections paginate with limit (default 50, max 100) and cursor; a page may be shorter than limit (soft-deleted rows are filtered out), so iterate until nextCursor is null. Deletes are soft. Consent fields and computed values are read-only. POST requests may carry an Idempotency-Key header: for 24 hours the same key with the same body replays the stored response (Idempotent-Replayed: true), the same key with a different body is refused with 422.

Rate limits per key: 600 requests and 300 writes per minute; per IP: 10 failed authentications per minute. Overruns answer 429 with Retry-After in seconds.

Servers:

https://<deployment>.convex.site/api/v1 — The Convex deployment of the organisation (replaced by the actual origin when served).

Status	Description	Body
`200`	The key.	Me
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

Contacts

Leads. Email is the matching key of POST /contacts/upsert.

GET `/contacts`

List contacts

Scopes: contacts:read

Parameter	In	Type	Required	Description
`limit`	query	integer (min 1, max 100, default 50)	no	Page size, 1 to 100.
`cursor`	query	string	no	The `nextCursor` of the previous page.
`email`	query	string	no	Exact match on the normalized (lowercased) email.

Status	Description	Body
`200`	A page of contacts, newest first.	ContactPage
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

POST `/contacts`

Create a contact

Strict create: a live contact with the same email answers 409 duplicate_email with the existing id in details.existingId. Use POST /contacts/upsert to merge instead.

Scopes: contacts:write

Parameter	In	Type	Required	Description
`Idempotency-Key`	header	string (min length 1, max length 255)	no	Unique per API key, 1 to 255 characters. For 24 hours a retry with the same key and body replays the stored response instead of writing again.

Request body (required): ContactCreate

Status	Description	Body
`201`	The created contact. Headers: `Idempotent-Replayed`	Contact
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`409`	State conflict: `duplicate_email` (with `details.existingId`), `company_registration_exists`, `company_vat_exists`, `company_domain_exists`, `lifecycle_regression_blocked`, `deal_transition_forbidden`, `stage_tag_required`, `idempotency_in_progress`.	Error
`422`	The `Idempotency-Key` was already used with a different request (`idempotency_key_reused`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

POST `/contacts/upsert`

Create or merge a contact by email

firstName, lastName and email are required, as for POST /contacts. A live contact with that email is merged with the CSV-import rules: only the provided fields overwrite, customProperties merge key by key, a soft-deleted match is revived, and lifecycleStage is ignored on an existing contact. When several contacts share the email, the oldest live one wins. Without a match the contact is created like POST /contacts.

Scopes: contacts:write

Parameter	In	Type	Required	Description
`Idempotency-Key`	header	string (min length 1, max length 255)	no	Unique per API key, 1 to 255 characters. For 24 hours a retry with the same key and body replays the stored response instead of writing again.

Request body (required): ContactCreate

Status	Description	Body
`200`	An existing contact was merged. Headers: `Idempotent-Replayed`	ContactUpsertResult
`201`	A contact was created. Headers: `Idempotent-Replayed`	ContactUpsertResult
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`422`	The `Idempotency-Key` was already used with a different request (`idempotency_key_reused`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

GET `/contacts/{id}`

Get a contact

Scopes: contacts:read

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).

Status	Description	Body
`200`	The contact.	Contact
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

PATCH `/contacts/{id}`

Update a contact

Partial: only the provided fields change, null clears an optional field. customProperties merges key by key (null removes a key). Changing the email to one another live contact holds answers 409 duplicate_email; a blocked lifecycle regression answers 409 lifecycle_regression_blocked.

Scopes: contacts:write

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).

Request body (required): ContactPatch

Status	Description	Body
`200`	The updated contact.	Contact
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`409`	State conflict: `duplicate_email` (with `details.existingId`), `company_registration_exists`, `company_vat_exists`, `company_domain_exists`, `lifecycle_regression_blocked`, `deal_transition_forbidden`, `stage_tag_required`, `idempotency_in_progress`.	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

DELETE `/contacts/{id}`

Delete a contact (soft)

Scopes: contacts:write

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).

Status	Description	Body
`204`	Deleted.
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

Companies

GET `/companies`

List companies

Scopes: companies:read

Parameter	In	Type	Required	Description
`limit`	query	integer (min 1, max 100, default 50)	no	Page size, 1 to 100.
`cursor`	query	string	no	The `nextCursor` of the previous page.
`domain`	query	string	no	Exact match on the normalized domain (lowercase, no protocol or www).

Status	Description	Body
`200`	A page of companies, newest first.	CompanyPage
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

POST `/companies`

Create a company

Registration number, VAT number and domain are normalized by the company's country and must be unique among live companies (409 company_registration_exists, company_vat_exists, company_domain_exists).

Scopes: companies:write

Parameter	In	Type	Required	Description
`Idempotency-Key`	header	string (min length 1, max length 255)	no	Unique per API key, 1 to 255 characters. For 24 hours a retry with the same key and body replays the stored response instead of writing again.

Request body (required): CompanyCreate

Status	Description	Body
`201`	The created company. Headers: `Idempotent-Replayed`	Company
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`409`	State conflict: `duplicate_email` (with `details.existingId`), `company_registration_exists`, `company_vat_exists`, `company_domain_exists`, `lifecycle_regression_blocked`, `deal_transition_forbidden`, `stage_tag_required`, `idempotency_in_progress`.	Error
`422`	The `Idempotency-Key` was already used with a different request (`idempotency_key_reused`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

GET `/companies/{id}`

Get a company

Scopes: companies:read

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).

Status	Description	Body
`200`	The company.	Company
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

PATCH `/companies/{id}`

Update a company

Partial; null clears an optional field; customProperties merges key by key.

Scopes: companies:write

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).

Request body (required): CompanyPatch

Status	Description	Body
`200`	The updated company.	Company
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`409`	State conflict: `duplicate_email` (with `details.existingId`), `company_registration_exists`, `company_vat_exists`, `company_domain_exists`, `lifecycle_regression_blocked`, `deal_transition_forbidden`, `stage_tag_required`, `idempotency_in_progress`.	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

DELETE `/companies/{id}`

Delete a company (soft)

Its contacts stay and are detached from the company in the background.

Scopes: companies:write

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).

Status	Description	Body
`204`	Deleted.
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

Deals

Stage moves go through the pipeline's transition graph.

GET `/deals`

List deals

Scopes: deals:read

Parameter	In	Type	Required	Description
`limit`	query	integer (min 1, max 100, default 50)	no	Page size, 1 to 100.
`cursor`	query	string	no	The `nextCursor` of the previous page.
`leadId`	query	string	no	Only the deals of this contact.

Status	Description	Body
`200`	A page of deals, newest first.	DealPage
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

POST `/deals`

Create a deal

Without pipelineId the default pipeline is used; without stageKey its first open stage. A stage with required tags needs stageTags (409 stage_tag_required).

Scopes: deals:write

Parameter	In	Type	Required	Description
`Idempotency-Key`	header	string (min length 1, max length 255)	no	Unique per API key, 1 to 255 characters. For 24 hours a retry with the same key and body replays the stored response instead of writing again.

Request body (required): DealCreate

Status	Description	Body
`201`	The created deal. Headers: `Idempotent-Replayed`	Deal
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`409`	State conflict: `duplicate_email` (with `details.existingId`), `company_registration_exists`, `company_vat_exists`, `company_domain_exists`, `lifecycle_regression_blocked`, `deal_transition_forbidden`, `stage_tag_required`, `idempotency_in_progress`.	Error
`422`	The `Idempotency-Key` was already used with a different request (`idempotency_key_reused`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

GET `/deals/{id}`

Get a deal

Scopes: deals:read

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).

Status	Description	Body
`200`	The deal.	Deal
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

PATCH `/deals/{id}`

Update a deal, optionally moving its stage

Field edits apply first, then the stage move when stageKey is given: the move must be an arrow of the pipeline's transition graph (409 deal_transition_forbidden), 400 unknown_stage otherwise. status, closedAt and pipelineId are read-only; a won stage promotes the linked contact to customer as in the UI.

Scopes: deals:write

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).

Request body (required): DealPatch

Status	Description	Body
`200`	The updated deal.	Deal
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`409`	State conflict: `duplicate_email` (with `details.existingId`), `company_registration_exists`, `company_vat_exists`, `company_domain_exists`, `lifecycle_regression_blocked`, `deal_transition_forbidden`, `stage_tag_required`, `idempotency_in_progress`.	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

DELETE `/deals/{id}`

Delete a deal (soft)

Scopes: deals:write

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).

Status	Description	Body
`204`	Deleted.
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

Activities

GET `/activities`

List activities

Scopes: activities:read

Parameter	In	Type	Required	Description
`limit`	query	integer (min 1, max 100, default 50)	no	Page size, 1 to 100.
`cursor`	query	string	no	The `nextCursor` of the previous page.
`leadId`	query	string	no	Only the activities of this contact.

Status	Description	Body
`200`	A page of activities, newest first.	ActivityPage
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

POST `/activities`

Create an activity

A done activity (a logged call, a note) gets completedAt stamped now.

Scopes: activities:write

Parameter	In	Type	Required	Description
`Idempotency-Key`	header	string (min length 1, max length 255)	no	Unique per API key, 1 to 255 characters. For 24 hours a retry with the same key and body replays the stored response instead of writing again.

Request body (required): ActivityCreate

Status	Description	Body
`201`	The created activity. Headers: `Idempotent-Replayed`	Activity
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`422`	The `Idempotency-Key` was already used with a different request (`idempotency_key_reused`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

GET `/activities/{id}`

Get an activity

Scopes: activities:read

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).

Status	Description	Body
`200`	The activity.	Activity
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

PATCH `/activities/{id}`

Update an activity

Partial; null clears an optional field. status: done stamps completedAt, status: open clears it, cancelled leaves it.

Scopes: activities:write

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).

Request body (required): ActivityPatch

Status	Description	Body
`200`	The updated activity.	Activity
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

DELETE `/activities/{id}`

Delete an activity (soft)

Scopes: activities:write

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).

Status	Description	Body
`204`	Deleted.
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

Lists

GET `/lists`

List the contact lists

Scopes: lists:read

Parameter	In	Type	Required	Description
`limit`	query	integer (min 1, max 100, default 50)	no	Page size, 1 to 100.
`cursor`	query	string	no	The `nextCursor` of the previous page.

Status	Description	Body
`200`	A page of lists.	ListPage
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

GET `/lists/{id}/members`

List the members of a list

Members are full contacts, hence the contacts:read scope on top of lists:read.

Scopes: lists:read, contacts:read

Parameter	In	Type	Required	Description
`id`	path	string	yes	The record id (`id` of the DTO).
`limit`	query	integer (min 1, max 100, default 50)	no	Page size, 1 to 100.
`cursor`	query	string	no	The `nextCursor` of the previous page.

Status	Description	Body
`200`	A page of contacts.	ContactPage
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`404`	Unknown route, malformed id, or no live record with this id (`not_found`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

Properties

Custom property definitions; their ids key customProperties.

GET `/properties`

List the custom property definitions of an entity type

Scopes: properties:read

Parameter	In	Type	Required	Description
`entityType`	query	PropertyEntityType	yes
`limit`	query	integer (min 1, max 100, default 50)	no	Page size, 1 to 100.
`cursor`	query	string	no	The `nextCursor` of the previous page.

Status	Description	Body
`200`	A page of definitions.	PropertyDefinitionPage
`400`	Invalid request. `code` is `invalid_json`, `invalid_body`, `field_required` (with `details.field`), `invalid_fields` (with `details.path`), `read_only_field`, `unknown_property`, `invalid_limit`, `invalid_cursor`, `invalid_idempotency_key`, or a backend validation code such as `invalid_owner`, `invalid_address`, `unknown_lifecycle_stage`, `unknown_stage`, `invalid_deal`.	Error
`401`	Missing, malformed, unknown, revoked or expired key — always the same body.	Error
`403`	The key lacks a required scope (`missing_scope`).	Error
`429`	A per-key or per-IP budget is exhausted (`rate_limited`). Headers: `Retry-After`	Error

Schemas

Error

Property	Type	Required	Description
`error`	object	yes
`error.code`	string	yes	Stable machine code.
`error.message`	string	yes
`error.details`	any	no	Code-specific data (`path`, `existingId`, `reason`…).

Me

Property	Type	Required	Description
`name`	string	yes
`keyId`	string	yes	The public identifier of the key (8 hex characters).
`scopes`	array of Scope	yes
`expiresAt`	number \| null	yes	Unix milliseconds, or null when the key never expires.

Scope

Timestamp

Unix milliseconds.

Type: number

Address

Country-driven postal address; validated against the country's format.

Property	Type	Required	Description
`country`	string	yes	ISO 3166-1 alpha-2, uppercase.
`streetNumber`	string	yes
`street`	string	yes
`line2`	string	no
`postalCode`	string	yes
`city`	string	yes
`region`	string	no
`placeId`	string	no
`coordinates`	object	no
`coordinates.lat`	number	yes
`coordinates.lng`	number	yes

PropertyValue

A custom property value; the shape depends on the definition's type.

Type: string | number | boolean | array of string

CustomProperties

Values keyed by property definition id (see GET /properties).

Type: map of PropertyValue

CustomPropertiesPatch

Merged key by key into the stored values; null removes a key.

Type: map of PropertyValue | null

IdList

Type: array of string

ConsentChannel

Type: "email" | "sms" | "telephone_canvassing" | "postal"

ConsentSource

Type: "crm" | "public_link" | "import" | "sms_stop"

Contact

Property	Type	Required	Description
`id`	string	yes
`createdAt`	Timestamp	yes
`updatedAt`	Timestamp	yes
`firstName`	string	yes
`lastName`	string	yes
`email`	string \| null	yes	Normalized (lowercased).
`phone`	string \| null	yes
`address`	Address \| null	yes
`comment`	string \| null	yes
`companyId`	string \| null	yes
`ownerIds`	IdList	yes
`isRedFlagged`	boolean	yes
`lifecycleStage`	string \| null	yes	A stage key of the lifecycle settings.
`leadScore`	number \| null	yes
`marketingConsent`	array of ConsentChannel	yes
`consentSource`	ConsentSource \| null	yes
`consentUpdatedAt`	number \| null	yes
`lastActivityAt`	number \| null	yes
`emailOpenCount`	integer	yes
`emailClickCount`	integer	yes
`formSubmissionCount`	integer	yes
`customProperties`	CustomProperties	yes

CompanyHint

Matches an existing company by registration number, VAT number or domain (else the email's domain); creates one when nothing matches and name is given.

Property	Type	Required
`name`	string	no
`country`	string	no
`registrationNumber`	string	no
`vatNumber`	string	no
`domain`	string	no

ContactCreate

Property	Type	Required	Description
`firstName`	string	yes
`lastName`	string	yes
`email`	string	yes	Stored lower-cased. Blank identity fields are refused (`field_required`).
`phone`	string	no
`address`	Address	no
`comment`	string	no
`ownerIds`	IdList	no
`isRedFlagged`	boolean	no
`lifecycleStage`	string	no	A stage key; the default stage when absent.
`companyId`	string	no
`company`	CompanyHint	no
`customProperties`	CustomProperties	no

ContactPatch

Property	Type	Required	Description
`firstName`	string	no
`lastName`	string	no
`email`	string	no	Identity fields (`firstName`, `lastName`, `email`) can change but never be cleared.
`phone`	string \| null	no
`address`	Address \| null	no
`comment`	string \| null	no
`ownerIds`	IdList	no
`isRedFlagged`	boolean	no
`lifecycleStage`	string	no
`companyId`	string \| null	no	An explicit pick; `null` detaches.
`customProperties`	CustomPropertiesPatch	no

ContactPage

Property	Type	Required	Description
`data`	array of Contact	yes
`nextCursor`	string \| null	yes

ContactUpsertResult

Property	Type	Required	Description
`created`	boolean	yes
`data`	Contact	yes

Company

Property	Type	Required	Description
`id`	string	yes
`createdAt`	Timestamp	yes
`updatedAt`	Timestamp	yes
`name`	string	yes
`country`	string	yes	ISO 3166-1 alpha-2, uppercase.
`registrationNumber`	string \| null	yes	Normalized by the country's scheme (digits only for a SIRET).
`vatNumber`	string \| null	yes
`domain`	string \| null	yes	Lowercase, no protocol or www.
`website`	string \| null	yes
`sector`	string \| null	yes
`headcount`	number \| null	yes
`address`	Address \| null	yes
`ownerIds`	IdList	yes
`customProperties`	CustomProperties	yes

CompanyCreate

Property	Type	Required	Description
`name`	string	yes
`country`	string	no	ISO 3166-1 alpha-2; the instance default when absent.
`registrationNumber`	string	no
`vatNumber`	string	no
`domain`	string	no
`website`	string	no
`sector`	string	no
`headcount`	number	no
`address`	Address	no
`ownerIds`	IdList	no
`customProperties`	CustomProperties	no

CompanyPatch

Property	Type	Required
`name`	string	no
`country`	string	no
`registrationNumber`	string \| null	no
`vatNumber`	string \| null	no
`domain`	string \| null	no
`website`	string \| null	no
`sector`	string \| null	no
`headcount`	number \| null	no
`address`	Address \| null	no
`ownerIds`	IdList	no
`customProperties`	CustomPropertiesPatch	no

CompanyPage

Property	Type	Required	Description
`data`	array of Company	yes
`nextCursor`	string \| null	yes

DealStatus

Type: "open" | "won" | "lost"

Deal

Property	Type	Required	Description
`id`	string	yes
`createdAt`	Timestamp	yes
`updatedAt`	Timestamp	yes
`title`	string	yes
`amount`	number \| null	yes
`currency`	string	yes	ISO 4217, uppercase.
`pipelineId`	string	yes
`stageKey`	string	yes
`status`	DealStatus	yes
`expectedCloseDate`	string \| null	yes	YYYY-MM-DD.
`closedAt`	number \| null	yes
`leadId`	string \| null	yes
`ownerIds`	IdList	yes
`sourceCampaignId`	string \| null	yes
`customProperties`	CustomProperties	yes

DealCreate

Property	Type	Required	Description
`title`	string	yes
`amount`	number (min 0)	no
`currency`	string	no	ISO 4217; EUR when absent.
`pipelineId`	string	no
`stageKey`	string	no
`stageTags`	array of string	no
`stageComment`	string	no
`expectedCloseDate`	string	no	YYYY-MM-DD.
`ownerIds`	IdList	no
`leadId`	string	no
`sourceCampaignId`	string	no
`customProperties`	CustomProperties	no

DealPatch

Property	Type	Required	Description
`title`	string	no
`amount`	number \| null	no
`currency`	string	no
`stageKey`	string	no	Moves the deal through the pipeline's transition graph.
`stageTags`	array of string	no	Tags of the target stage; only with `stageKey`.
`stageComment`	string	no	Only with `stageKey`.
`expectedCloseDate`	string \| null	no
`ownerIds`	IdList	no
`leadId`	string \| null	no
`sourceCampaignId`	string \| null	no
`customProperties`	CustomPropertiesPatch	no

DealPage

Property	Type	Required	Description
`data`	array of Deal	yes
`nextCursor`	string \| null	yes

ActivityType

Type: "call" | "meeting" | "task" | "email" | "note"

ActivityStatus

Type: "open" | "done" | "cancelled"

Activity

Property	Type	Required
`id`	string	yes
`createdAt`	Timestamp	yes
`updatedAt`	Timestamp	yes
`type`	ActivityType	yes
`title`	string	yes
`description`	string \| null	yes
`status`	ActivityStatus	yes
`dueAt`	number \| null	yes
`completedAt`	number \| null	yes
`outcome`	string \| null	yes
`ownerId`	string \| null	yes
`teamId`	string \| null	yes
`leadId`	string \| null	yes
`companyId`	string \| null	yes
`dealId`	string \| null	yes
`customProperties`	CustomProperties	yes

ActivityCreate

Property	Type	Required	Description
`type`	ActivityType	yes
`title`	string	yes
`description`	string	no
`dueAt`	Timestamp	no
`status`	`"open"` \| `"done"`	no
`ownerId`	string	no	A live employee.
`teamId`	string	no
`leadId`	string	no
`companyId`	string	no
`dealId`	string	no
`outcome`	string	no
`customProperties`	CustomProperties	no

ActivityPatch

Property	Type	Required
`type`	ActivityType	no
`title`	string	no
`description`	string \| null	no
`dueAt`	number \| null	no
`status`	ActivityStatus	no
`ownerId`	string \| null	no
`teamId`	string \| null	no
`leadId`	string \| null	no
`companyId`	string \| null	no
`dealId`	string \| null	no
`outcome`	string \| null	no
`customProperties`	CustomPropertiesPatch	no

ActivityPage

Property	Type	Required	Description
`data`	array of Activity	yes
`nextCursor`	string \| null	yes

List

Property	Type	Required
`id`	string	yes
`createdAt`	Timestamp	yes
`updatedAt`	Timestamp	yes
`name`	string	yes
`kind`	`"static"` \| `"dynamic"`	yes

ListPage

Property	Type	Required	Description
`data`	array of List	yes
`nextCursor`	string \| null	yes

PropertyEntityType

Type: "lead" | "company" | "deal" | "activity"

PropertyType

PropertyDefinition

Property	Type	Required	Description
`id`	string	yes	The key of this property in `customProperties`.
`entityType`	PropertyEntityType	yes
`label`	string	yes
`type`	PropertyType	yes
`options`	array of object \| null	yes	The choices of select / radio / checkbox properties; `value` is the stored key.
`validation`	object \| null	yes
`validation.min`	number	no
`validation.max`	number	no
`validation.minLength`	integer	no
`validation.maxLength`	integer	no
`validation.pattern`	string	no
`computed`	boolean	yes	Engine-maintained value, read-only through the API.

PropertyDefinitionPage

Property	Type	Required	Description
`data`	array of PropertyDefinition	yes
`nextCursor`	string \| null	yes

Fabulous CRM public API

Meta

GET /me

Contacts

GET /contacts

POST /contacts

POST /contacts/upsert

GET /contacts/{id}

PATCH /contacts/{id}

DELETE /contacts/{id}

Companies

GET /companies

POST /companies

GET /companies/{id}

PATCH /companies/{id}

DELETE /companies/{id}

Deals

GET /deals

POST /deals

GET /deals/{id}

PATCH /deals/{id}

DELETE /deals/{id}

Activities

GET /activities

POST /activities

GET /activities/{id}

PATCH /activities/{id}

DELETE /activities/{id}

Lists

GET /lists

GET /lists/{id}/members

Properties

GET /properties

Schemas

Error

Me

Scope

Timestamp

Address

PropertyValue

CustomProperties

CustomPropertiesPatch

IdList

ConsentChannel

ConsentSource

Contact

CompanyHint

ContactCreate

ContactPatch

ContactPage

ContactUpsertResult

Company

CompanyCreate

CompanyPatch

CompanyPage

DealStatus

Deal

DealCreate

DealPatch

DealPage

ActivityType

ActivityStatus

Activity

ActivityCreate

ActivityPatch

ActivityPage

List

ListPage

PropertyEntityType

PropertyType

PropertyDefinition

PropertyDefinitionPage

GET `/me`

GET `/contacts`

POST `/contacts`

POST `/contacts/upsert`

GET `/contacts/{id}`

PATCH `/contacts/{id}`

DELETE `/contacts/{id}`

GET `/companies`

POST `/companies`

GET `/companies/{id}`

PATCH `/companies/{id}`

DELETE `/companies/{id}`

GET `/deals`

POST `/deals`

GET `/deals/{id}`

PATCH `/deals/{id}`

DELETE `/deals/{id}`

GET `/activities`

POST `/activities`

GET `/activities/{id}`

PATCH `/activities/{id}`

DELETE `/activities/{id}`

GET `/lists`

GET `/lists/{id}/members`

GET `/properties`