Custom Fields Guide

Custom fields allow you to extend person and company records with additional data fields tailored to your business needs. This guide covers everything you need to know about creating, managing, and using custom fields.

Overview

Custom fields provide flexibility to store data beyond the standard CRM fields. They're perfect for:

Industry-specific data (property budget, investment timeline)
Lead qualification criteria (credit score, pre-approval status)
Customer preferences (communication preferences, interests)
Business metrics (lifetime value, deal size)
Integration mappings (external system IDs)

Supported Field Types:

text - Single-line text input
number - Numeric values (integers or decimals)
date - Date values (ISO 8601 format)
dropdown - Single-select from predefined options

Creating Custom Fields

Basic Text Field

Endpoint: POST /api/partner/customFields

curl -X POST https://api.suresend.ai/api/partner/customFields \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "referral_source",
    "label": "Referral Source",
    "fieldType": "text",
    "appliesTo": "people"
  }'

Response:

{
  "id": "field-uuid",
  "name": "referral_source",
  "label": "Referral Source",
  "fieldType": "text",
  "appliesTo": "people",
  "required": false,
  "defaultValue": null,
  "description": null,
  "created": "2025-10-16T12:00:00Z",
  "updated": "2025-10-16T12:00:00Z"
}

Dropdown Field

curl -X POST https://api.suresend.ai/api/partner/customFields \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "buyer_stage",
    "label": "Buyer Stage",
    "fieldType": "dropdown",
    "appliesTo": "people",
    "choices": [
      "Pre-Qualified",
      "House Hunting",
      "Under Contract",
      "Closed"
    ],
    "description": "Current stage in the home buying process"
  }'

Number Field

curl -X POST https://api.suresend.ai/api/partner/customFields \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "property_budget",
    "label": "Property Budget",
    "fieldType": "number",
    "appliesTo": "people",
    "description": "Maximum budget for property purchase",
    "defaultValue": "0"
  }'

Date Field

curl -X POST https://api.suresend.ai/api/partner/customFields \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "move_in_date",
    "label": "Desired Move-In Date",
    "fieldType": "date",
    "appliesTo": "people",
    "description": "Target move-in date"
  }'

Required Field

curl -X POST https://api.suresend.ai/api/partner/customFields \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lead_source",
    "label": "Lead Source",
    "fieldType": "dropdown",
    "appliesTo": "people",
    "required": true,
    "choices": ["Website", "Referral", "Facebook Ad", "Google Ad", "Other"]
  }'

Field for Companies

curl -X POST https://api.suresend.ai/api/partner/customFields \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "industry_vertical",
    "label": "Industry Vertical",
    "fieldType": "dropdown",
    "appliesTo": "companies",
    "choices": ["Technology", "Healthcare", "Finance", "Retail", "Other"]
  }'

Field for Both People and Companies

curl -X POST https://api.suresend.ai/api/partner/customFields \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "account_manager",
    "label": "Account Manager",
    "fieldType": "text",
    "appliesTo": "both"
  }'

Field Naming Conventions

Best Practices:

Use lowercase with underscores: property_budget, move_in_date
Be descriptive: preferred_contact_method not pcm
Avoid conflicts: Don't use existing field names like email, phone
Use prefixes for integrations: sf_account_id, hubspot_deal_id

Examples:

✅ property_budget
✅ buyer_stage
✅ credit_score
❌ pb (too short)
❌ PropertyBudget (use lowercase)
❌ email (conflicts with standard field)

Listing Custom Fields

List All Custom Fields

Endpoint: GET /api/partner/customFields

curl https://api.suresend.ai/api/partner/customFields \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "customFields": [
    {
      "id": "field-uuid",
      "name": "property_budget",
      "label": "Property Budget",
      "fieldType": "number",
      "appliesTo": "people",
      "required": false,
      "defaultValue": "0",
      "description": "Maximum budget for property purchase",
      "created": "2025-10-16T12:00:00Z",
      "updated": "2025-10-16T12:00:00Z"
    }
  ]
}

Filter by Entity Type

# Only people fields
curl "https://api.suresend.ai/api/partner/customFields?appliesTo=people" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Only company fields
curl "https://api.suresend.ai/api/partner/customFields?appliesTo=companies" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Fields that apply to both
curl "https://api.suresend.ai/api/partner/customFields?appliesTo=both" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get Specific Custom Field

Endpoint: GET /api/partner/customFields/{id}

curl https://api.suresend.ai/api/partner/customFields/field-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Updating Custom Fields

Endpoint: PUT /api/partner/customFields/{id}

Update Label

curl -X PUT https://api.suresend.ai/api/partner/customFields/field-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Updated Label"
  }'

Update Dropdown Choices

curl -X PUT https://api.suresend.ai/api/partner/customFields/field-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "choices": ["New Option 1", "New Option 2", "New Option 3"]
  }'

Make Field Required

curl -X PUT https://api.suresend.ai/api/partner/customFields/field-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "required": true
  }'

Update Description

curl -X PUT https://api.suresend.ai/api/partner/customFields/field-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated help text for this field"
  }'

Note: Field name and fieldType cannot be changed after creation.

Deleting Custom Fields

Endpoint: DELETE /api/partner/customFields/{id}

curl -X DELETE https://api.suresend.ai/api/partner/customFields/field-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN"

⚠️ Warning: Deleting a custom field permanently deletes all associated data. This operation cannot be undone.

Best Practice: Consider archiving fields instead of deleting to preserve historical data.

Using Custom Fields

Set Custom Field Values on People

When creating or updating a person, include custom field values in the customFields object:

curl -X POST https://api.suresend.ai/api/partner/people \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "emails": [{"value": "[email protected]", "isPrimary": true}],
    "customFields": {
      "property_budget": 500000,
      "buyer_stage": "House Hunting",
      "move_in_date": "2025-06-01",
      "referral_source": "Friend"
    }
  }'

Update Custom Field Values

curl -X PUT https://api.suresend.ai/api/partner/people/person-uuid \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customFields": {
      "buyer_stage": "Under Contract",
      "property_budget": 550000
    }
  }'

Read Custom Field Values

Custom field values are returned in the customFields object:

{
  "id": "person-uuid",
  "firstName": "John",
  "lastName": "Doe",
  "customFields": {
    "property_budget": 500000,
    "buyer_stage": "House Hunting",
    "move_in_date": "2025-06-01",
    "referral_source": "Friend"
  }
}

Common Use Cases

1. Real Estate CRM

# Create fields for real estate business
curl -X POST https://api.suresend.ai/api/partner/customFields \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "property_budget",
    "label": "Property Budget",
    "fieldType": "number",
    "appliesTo": "people"
  }'

curl -X POST https://api.suresend.ai/api/partner/customFields \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "preferred_location",
    "label": "Preferred Location",
    "fieldType": "text",
    "appliesTo": "people"
  }'

curl -X POST https://api.suresend.ai/api/partner/customFields \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bedrooms_needed",
    "label": "Bedrooms Needed",
    "fieldType": "dropdown",
    "appliesTo": "people",
    "choices": ["1", "2", "3", "4", "5+"]
  }'

curl -X POST https://api.suresend.ai/api/partner/customFields \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "financing_status",
    "label": "Financing Status",
    "fieldType": "dropdown",
    "appliesTo": "people",
    "choices": ["Pre-Approved", "Pre-Qualified", "Cash Buyer", "Not Started"]
  }'

2. Lead Qualification

async function setupLeadQualificationFields() {
  const fields = [
    {
      name: 'lead_score',
      label: 'Lead Score',
      fieldType: 'number',
      appliesTo: 'people',
      description: 'Qualification score 0-100'
    },
    {
      name: 'qualification_status',
      label: 'Qualification Status',
      fieldType: 'dropdown',
      appliesTo: 'people',
      choices: ['Unqualified', 'Marketing Qualified', 'Sales Qualified', 'Opportunity']
    },
    {
      name: 'last_contact_date',
      label: 'Last Contact Date',
      fieldType: 'date',
      appliesTo: 'people'
    },
    {
      name: 'buying_timeline',
      label: 'Buying Timeline',
      fieldType: 'dropdown',
      appliesTo: 'people',
      choices: ['Immediate', '1-3 months', '3-6 months', '6-12 months', '12+ months']
    }
  ];

  for (const field of fields) {
    await axios.post(
      'https://api.suresend.ai/api/partner/customFields',
      field,
      { headers: { Authorization: `Bearer ${API_TOKEN}` } }
    );
  }
}

3. Integration Mappings

Store IDs from external systems:

// Create fields for external system IDs
await axios.post(
  'https://api.suresend.ai/api/partner/customFields',
  {
    name: 'salesforce_account_id',
    label: 'Salesforce Account ID',
    fieldType: 'text',
    appliesTo: 'people',
    description: 'Salesforce Account ID for sync'
  },
  { headers: { Authorization: `Bearer ${API_TOKEN}` } }
);

// Store external ID when syncing
await axios.put(
  `https://api.suresend.ai/api/partner/people/${personId}`,
  {
    customFields: {
      salesforce_account_id: 'SF-12345'
    }
  },
  { headers: { Authorization: `Bearer ${API_TOKEN}` } }
);

4. Dynamic Form Building

Build forms based on custom fields:

async function buildDynamicForm() {
  const response = await axios.get(
    'https://api.suresend.ai/api/partner/customFields',
    {
      params: { appliesTo: 'people' },
      headers: { Authorization: `Bearer ${API_TOKEN}` }
    }
  );

  const fields = response.data.customFields;

  // Generate form fields
  const formFields = fields.map(field => {
    switch (field.fieldType) {
      case 'text':
        return {
          type: 'input',
          name: field.name,
          label: field.label,
          required: field.required,
          defaultValue: field.defaultValue
        };
      case 'number':
        return {
          type: 'number',
          name: field.name,
          label: field.label,
          required: field.required
        };
      case 'date':
        return {
          type: 'date',
          name: field.name,
          label: field.label,
          required: field.required
        };
      case 'dropdown':
        return {
          type: 'select',
          name: field.name,
          label: field.label,
          required: field.required,
          options: field.choices
        };
    }
  });

  return formFields;
}

5. Bulk Update Custom Fields

async function bulkUpdateCustomFields(peopleIds, customFieldData) {
  const promises = peopleIds.map(personId =>
    axios.put(
      `https://api.suresend.ai/api/partner/people/${personId}`,
      { customFields: customFieldData },
      { headers: { Authorization: `Bearer ${API_TOKEN}` } }
    )
  );

  await Promise.all(promises);
  console.log(`Updated ${peopleIds.length} contacts`);
}

// Usage
await bulkUpdateCustomFields(
  ['person-1', 'person-2', 'person-3'],
  {
    campaign_source: 'Spring 2025',
    last_campaign_date: '2025-03-15'
  }
);

6. Validation Before Submission

async function validateCustomFields(personData) {
  // Get field definitions
  const response = await axios.get(
    'https://api.suresend.ai/api/partner/customFields',
    {
      params: { appliesTo: 'people' },
      headers: { Authorization: `Bearer ${API_TOKEN}` }
    }
  );

  const fields = response.data.customFields;
  const errors = [];

  // Validate required fields
  fields.forEach(field => {
    if (field.required && !personData.customFields[field.name]) {
      errors.push(`${field.label} is required`);
    }

    // Validate dropdown values
    if (field.fieldType === 'dropdown') {
      const value = personData.customFields[field.name];
      if (value && !field.choices.includes(value)) {
        errors.push(`Invalid value for ${field.label}: ${value}`);
      }
    }

    // Validate number fields
    if (field.fieldType === 'number') {
      const value = personData.customFields[field.name];
      if (value && isNaN(value)) {
        errors.push(`${field.label} must be a number`);
      }
    }

    // Validate date fields
    if (field.fieldType === 'date') {
      const value = personData.customFields[field.name];
      if (value && !isValidDate(value)) {
        errors.push(`${field.label} must be a valid date (ISO 8601)`);
      }
    }
  });

  return errors;
}

Field Types in Detail

Text Fields

Use For:

Short text values
Names, titles, descriptions
External IDs
URLs

Example Values:

{
  "customFields": {
    "referral_source": "John Smith",
    "website_url": "https://example.com",
    "external_id": "EXT-12345"
  }
}

Number Fields

Use For:

Prices, budgets, costs
Scores, ratings
Quantities, counts
Percentages

Example Values:

{
  "customFields": {
    "property_budget": 500000,
    "lead_score": 85,
    "number_of_properties": 3,
    "conversion_rate": 12.5
  }
}

Note: Supports integers and decimals.

Date Fields

Use For:

Deadlines, due dates
Event dates
Timeline milestones

Format: ISO 8601 (YYYY-MM-DD)

Example Values:

{
  "customFields": {
    "move_in_date": "2025-06-01",
    "contract_expiry": "2025-12-31",
    "last_contact": "2025-03-15"
  }
}

Dropdown Fields

Use For:

Predefined options
Status values
Categories
Single-select choices

Example Values:

{
  "customFields": {
    "buyer_stage": "House Hunting",
    "property_type": "Single Family Home",
    "financing_status": "Pre-Approved"
  }
}

Note: Must provide choices array when creating dropdown fields.

Best Practices

Planning Custom Fields

Start with essentials - Only create fields you'll actually use
Use standard fields first - Check if standard fields meet your needs
Plan for scale - Consider how many fields you need
Document fields - Add descriptions to help your team
Group related fields - Use consistent naming prefixes

Naming Conventions

Lowercase with underscores - property_budget, not PropertyBudget
Descriptive names - move_in_date, not date1
Avoid abbreviations - property_budget, not prop_bud
Use prefixes for integrations - sf_account_id, hs_deal_id
Don't conflict with standard fields - Check existing field names

Field Organization

// Good: Organized with prefixes
{
  // Qualification fields
  "qual_score": 85,
  "qual_status": "Sales Qualified",

  // Property preferences
  "prop_budget": 500000,
  "prop_location": "Portland",
  "prop_bedrooms": 3,

  // Integration IDs
  "sf_account_id": "SF-12345",
  "hs_contact_id": "HS-67890"
}

// Bad: No organization
{
  "score": 85,
  "status": "Sales Qualified",
  "budget": 500000,
  "location": "Portland",
  "beds": 3
}

Data Validation

Validate before submission - Check data types and required fields
Validate dropdown values - Ensure value exists in choices
Validate date formats - Use ISO 8601 format
Validate number ranges - Check min/max values
Handle errors gracefully - Provide clear error messages

Performance

Don't create too many fields - Keep it manageable (< 50 fields)
Index important fields - Contact support for indexing
Cache field definitions - Reduce API calls
Batch updates - Update multiple people at once

Troubleshooting

Field Not Appearing

✅ Check appliesTo setting (people, companies, both)
✅ Verify field was created successfully
✅ Check you're querying the correct entity type

Validation Errors

✅ For dropdown fields, ensure value matches choices exactly
✅ For date fields, use ISO 8601 format (YYYY-MM-DD)
✅ For number fields, ensure value is numeric
✅ Check required fields are provided

Can't Update Field Name or Type

⚠️ Field name and fieldType cannot be changed after creation
Create a new field with the correct name/type
Migrate data from old field to new field
Delete old field when migration is complete

Data Not Saving

✅ Verify custom field exists
✅ Check field name spelling (case-sensitive)
✅ Ensure you have permission to update the person/company
✅ Check API response for validation errors

Next Steps

Learn about People API to use custom fields with contacts
Check Events API to track custom field changes
Set up Webhooks for custom field updates
Review Getting Started for authentication

Need Help?

API Reference: See full Custom Fields endpoints in sidebar
Support: [email protected]
Examples: Check our GitHub examples (coming soon)