Field Types

FULL_NAME

Person names are a nested object never send flat firstName/lastName fields at the top level.

{
  "name": {
    "firstName": "John",
    "lastName": "Smith"
  }
}

EMAILS

{
  "emails": {
    "primaryEmail": "john@example.com",
    "additionalEmails": []
  }
}

PHONES

Store calling code and number separately.

{
  "phones": {
    "primaryPhoneNumber": "5551234567",
    "primaryPhoneCountryCode": "US",
    "primaryPhoneCallingCode": "+1",
    "additionalPhones": []
  }
}

LINKS (LinkedIn, Website, X)

All link fields share the same structure. Omitting secondaryLinks causes errors.

{
  "linkedinLink": {
    "primaryLinkUrl": "https://linkedin.com/in/johnsmith",
    "primaryLinkLabel": "LinkedIn",
    "secondaryLinks": []
  }
}

CURRENCY

Currency amounts are stored in micros multiply the actual amount by 1,000,000.

{
  "annualRecurringRevenue": {
    "amountMicros": 50000000000,
    "currencyCode": "USD"
  }
}

SELECT / MULTI_SELECT

Enum values must be UPPER_SNAKE_CASE. Invalid values return a 400 error.

// ✓ Correct
"stage": "CLOSED_WON"
"workPolicy": ["HYBRID", "REMOTE_WORK"]

// ✗ Wrong will be rejected
"stage": "Closed Won"
"workPolicy": ["hybrid"]

ADDRESS

Address fields are flat not nested under an address sub-object.

{
  "addressStreet1": "123 Main Street",
  "addressStreet2": "Suite 200",
  "addressCity": "New York",
  "addressState": "New York",
  "addressPostcode": "10001",
  "addressCountry": "United States",
  "addressLat": 40.7128,
  "addressLng": -74.0060
}

NOTE / TASK BODY

Send plain body text for automatic conversion, or use bodyV2 for rich content control.

// Simple auto-converted to rich format
{ "body": "Discussed pricing. Follow up Friday." }

// Rich full control
{
  "bodyV2": {
    "markdown": "## Notes\n\nDiscussed pricing.",
    "blocknote": "..." // BlockNote JSON
  }
}