Home/CRM/Data Structures

CRM Data Structures

Field definitions for key objects returned by CRM APIs.

Common Fields

Core objects share common fields: `object`, `external_id`, `source_system`, `metadata`, `livemode`, `version`, `system_updated_at`, `created_by`, `updated_by`, and `deleted_at`.

Deal object

Core object representing a sales deal.

Fields

Name	Type	Required	Description
id	string	Required	Deal ID
object	string	Required	Object type (`crm.deal`)
organization_id	string	Required	Organization ID
external_id	string \| null	Optional	External ID
source_system	"salesforce" \| "import" \| "api" \| "manual"	Required	Source system
owner_id	string	Required	Owner ID
record_type	string	Required	Record type
name	string	Required	Deal name
stage	"lead" \| "qualified" \| "proposal" \| "negotiation" \| "won" \| "lost"	Required	Current stage (lead, qualified, proposal, negotiation, won, lost)
amount	number \| null	Optional	Amount
company_id	string \| null	Optional	Related company ID
contact_id	string \| null	Optional	Related contact ID
assigned_member_id	string \| null	Optional	Assigned member ID
expected_close_date	string \| null	Optional	Expected close date
metadata	object \| null	Optional	Additional metadata
livemode	boolean	Required	Live mode flag
version	number	Required	Revision number
created_by	string \| null	Optional	Creator ID
updated_by	string \| null	Optional	Updater ID
deleted_at	string \| null	Optional	Deleted at (ISO 8601)
created_at	string	Required	Created at (ISO 8601)
system_updated_at	string	Required	System updated at (ISO 8601)
updated_at	string	Required	Updated at (ISO 8601)

{
  "id": "deal_11111111111111111111111111111111",
  "object": "crm.deal",
  "organization_id": "org_77777777777777777777777777777777",
  "external_id": "ext_org_77777777",
  "source_system": "api",
  "owner_id": "usr_99999999999999999999999999999999",
  "record_type": "default",
  "name": "Enterprise Plan - Acme Corp",
  "stage": "proposal",
  "amount": 1200000,
  "company_id": "comp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "contact_id": "cont_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "assigned_member_id": "mem_99999999999999999999999999999999",
  "expected_close_date": "2026-03-31",
  "metadata": {
    "source": "website",
    "campaign": "spring-2026"
  },
  "livemode": false,
  "version": 12,
  "created_by": "usr_99999999999999999999999999999999",
  "updated_by": "usr_88888888888888888888888888888888",
  "deleted_at": null,
  "created_at": "2026-01-15T09:00:00Z",
  "system_updated_at": "2026-02-20T14:30:00Z",
  "updated_at": "2026-02-20T14:30:00Z"
}

Company object

Object representing a company record.

Fields

Name	Type	Required	Description
id	string	Required	Company ID
object	string	Required	Object type (`crm.company`)
organization_id	string	Required	Organization ID
external_id	string \| null	Optional	External ID
source_system	"salesforce" \| "import" \| "api" \| "manual"	Required	Source system
owner_id	string	Required	Owner ID
record_type	string	Required	Record type
name	string	Required	Company name
industry	string \| null	Optional	Industry
website_url	string \| null	Optional	Website URL
email	string \| null	Optional	Primary email address
phone	string \| null	Optional	Phone number
address	string \| null	Optional	Address
metadata	object \| null	Optional	Additional metadata
livemode	boolean	Required	Live mode flag
version	number	Required	Revision number
created_by	string \| null	Optional	Creator ID
updated_by	string \| null	Optional	Updater ID
deleted_at	string \| null	Optional	Deleted at (ISO 8601)
created_at	string	Required	Created at (ISO 8601)
system_updated_at	string	Required	System updated at (ISO 8601)
updated_at	string	Required	Updated at (ISO 8601)

{
  "id": "comp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "object": "crm.company",
  "organization_id": "org_77777777777777777777777777777777",
  "external_id": "ext_org_77777777",
  "source_system": "api",
  "owner_id": "usr_99999999999999999999999999999999",
  "record_type": "default",
  "name": "Acme Corporation",
  "industry": "IT Services",
  "website_url": "https://acme.example.com",
  "email": "info@acme.example.com",
  "phone": "03-1234-5678",
  "address": "Tokyo, Minato-ku 1-2-3",
  "metadata": {
    "segment": "enterprise"
  },
  "livemode": false,
  "version": 7,
  "created_by": "usr_99999999999999999999999999999999",
  "updated_by": "usr_99999999999999999999999999999999",
  "deleted_at": null,
  "created_at": "2026-01-10T09:00:00Z",
  "system_updated_at": "2026-02-18T11:00:00Z",
  "updated_at": "2026-02-18T11:00:00Z"
}

Contact object

Object representing a contact person.

Fields

Name	Type	Required	Description
id	string	Required	Contact ID
object	string	Required	Object type (`crm.contact`)
organization_id	string	Required	Organization ID
external_id	string \| null	Optional	External ID
source_system	"salesforce" \| "import" \| "api" \| "manual"	Required	Source system
owner_id	string	Required	Owner ID
record_type	string	Required	Record type
company_id	string \| null	Optional	Associated company ID
name	string	Required	Name
email	string \| null	Optional	Email address
phone	string \| null	Optional	Phone number
position	string \| null	Optional	Position/title
notes	string \| null	Optional	Notes
metadata	object \| null	Optional	Additional metadata
livemode	boolean	Required	Live mode flag
version	number	Required	Revision number
created_by	string \| null	Optional	Creator ID
updated_by	string \| null	Optional	Updater ID
deleted_at	string \| null	Optional	Deleted at (ISO 8601)
created_at	string	Required	Created at (ISO 8601)
system_updated_at	string	Required	System updated at (ISO 8601)
updated_at	string	Required	Updated at (ISO 8601)

{
  "id": "cont_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "object": "crm.contact",
  "organization_id": "org_77777777777777777777777777777777",
  "external_id": "ext_org_77777777",
  "source_system": "api",
  "owner_id": "usr_99999999999999999999999999999999",
  "record_type": "default",
  "company_id": "comp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "name": "Tanaka Taro",
  "email": "tanaka@acme.example.com",
  "phone": "090-1234-5678",
  "position": "CTO",
  "notes": null,
  "metadata": {
    "source": "import"
  },
  "livemode": false,
  "version": 3,
  "created_by": "usr_99999999999999999999999999999999",
  "updated_by": "usr_88888888888888888888888888888888",
  "deleted_at": null,
  "created_at": "2026-01-12T10:00:00Z",
  "system_updated_at": "2026-02-19T16:00:00Z",
  "updated_at": "2026-02-19T16:00:00Z"
}

Activity object

Object representing deal activity history.

Fields

Name	Type	Required	Description
id	string	Required	Activity ID
object	string	Required	Object type (`crm.activity`)
organization_id	string	Required	Organization ID
external_id	string \| null	Optional	External ID
source_system	"salesforce" \| "import" \| "api" \| "manual"	Required	Source system
owner_id	string	Required	Owner ID
record_type	string	Required	Record type
deal_id	string	Required	Related deal ID
type	"call" \| "email" \| "meeting" \| "note" \| "task"	Required	Activity type (call, email, meeting, note, task)
title	string	Required	Title
content	string \| null	Optional	Detailed content
performed_at	string	Required	Performed at (ISO 8601)
created_by	string	Required	Creator user ID
metadata	object \| null	Optional	Additional metadata
livemode	boolean	Required	Live mode flag
version	number	Required	Revision number
updated_by	string \| null	Optional	Updater ID
deleted_at	string \| null	Optional	Deleted at (ISO 8601)
created_at	string	Required	Created at (ISO 8601)
system_updated_at	string	Required	System updated at (ISO 8601)
updated_at	string	Required	Updated at (ISO 8601)

{
  "id": "act_cccccccccccccccccccccccccccccccc",
  "object": "crm.activity",
  "organization_id": "org_77777777777777777777777777777777",
  "external_id": "ext_org_77777777",
  "source_system": "api",
  "owner_id": "usr_99999999999999999999999999999999",
  "record_type": "default",
  "deal_id": "deal_11111111111111111111111111111111",
  "type": "meeting",
  "title": "Product demo meeting",
  "content": "Presented new features to the client team.",
  "performed_at": "2026-02-20T13:00:00Z",
  "created_by": "usr_99999999999999999999999999999999",
  "metadata": {
    "channel": "meeting"
  },
  "livemode": false,
  "version": 2,
  "updated_by": "usr_99999999999999999999999999999999",
  "deleted_at": null,
  "created_at": "2026-02-20T14:00:00Z",
  "system_updated_at": "2026-02-20T14:00:00Z",
  "updated_at": "2026-02-20T14:00:00Z"
}