Field mapping
The API is an additive facade, so for some resources the field name you write in a create or update body differs from the field name you read back in the response. This is deliberate — the public names are stable even as internal names change — but it means you can't always assume the key you sent is the key you'll get back.
This page lists, per resource, every write field whose read-back name differs, plus fields that are
read-only (returned but not settable) or write-only (accepted but not echoed). Fields not listed here
use the same name on input and output (e.g. name, email, city, tags, priority,
related_to).
When in doubt, the API Reference shows the exact request and response schema for every endpoint, with examples. This guide is the quick cross-reference.
Contacts
Write (POST/PATCH /contacts) | Read (response) | Notes |
|---|---|---|
job_title | contact_designation | Job title. |
address_line1 | address1 | Street address line 1. |
owner_id | assigned_to_id | The assigned CRM user. |
account_id | b_company_id | The linked company/account. |
country_code (string) | country (object) | You send an ISO 3166-1 alpha-2 code; you read back { code, name, currency }. |
lead_score | score | Lead score. |
lifecycle_stage_id (string) | stage (object) | You send an id; you read back { id, name }. |
lead_status_id (string) | status (object) | You send an id; you read back { id, name }. |
custom_fields (object) | custom_fields (array) | Write an OBJECT keyed by field name or id; read back an ARRAY of the POPULATED entries only ([{ id, name, type, value }] on a single record). Never echo the read array back on write. |
Companies
Write (POST/PATCH /companies) | Read (response) | Notes |
|---|---|---|
type | account_type | Account type. |
address_line1 | address | Read exposes a single address string. |
postal_code | zip | Postal / ZIP code. |
country_code (string) | country (object) | Code in, { code, name, currency } out. |
owner_id | assigned_to_id | Assigned CRM user. |
lifecycle_stage_id (string) | stage (object) | Id in, { id, name } out. |
lead_status_id (string) | status (object) | Id in, { id, name } out. |
lead_score | score | |
custom_fields (object) | custom_fields (array) | Object in, array of POPULATED entries out. |
dnd is a boolean on companies (unlike contacts, where it's a per-channel object).
Deals
Write (POST/PATCH /deals) | Read (response) | Notes |
|---|---|---|
value | monetary_value | Deal amount. |
type | deal_type | new_business or existing_business. |
expected_close_date (date) | expected_closing_date (date-time) | |
tags | tags_v2 | |
lead_score | score | |
custom_fields (object) | custom_fields (array) | Object in, array of POPULATED entries out. |
name, pipeline_id, stage_id, sales_person_id, account_id, primary_contact_id, and
contact_ids keep the same name. deal_status is read-only — move a deal with
POST /deals/{id}/stage, not by writing the field.
Tasks
Write (POST/PATCH /tasks) | Read (response) | Notes |
|---|---|---|
title | name | Task title. |
assignee_id | assign_to_id | Assigned user. |
status_id (string) | status (object) | Id in, { id, name } out. |
type_id (string) | type (object) | Id in, { id, name } out. |
tags | tagsv2 | |
custom_fields (object) | custom_fields (array) | Object in, array of POPULATED entries out. |
assign_by_id is read-only (the user who created/assigned the task).
Notes
Write (POST/PATCH /notes) | Read (response) | Notes |
|---|---|---|
body | description | The note text. |
contact_id / contact_ids | contact_ids | Read returns the full linked list (including the related_to contact). |
company_id / company_ids | company_ids | Full linked list on read. |
deal_id / deal_ids | deal_ids | Full linked list on read. |
is_pinned is read-only — set it with POST /notes/{id}/pin.
Activities
Write (POST /activities) | Read (response) | Notes |
|---|---|---|
type | operand_type | Activity type (call, email, meeting, …). |
description | description / updated_desc | The read model also exposes a derived updated_desc. |
operand_id | — | Write-only linkage; not echoed back. |
operation and related_to keep the same name. activity_title, user_id, occurred_at, and
createdAt are read-only.