Create Contact

Create a new contact in your workspace.

Use Cases:

• Add subscribers from your website forms
• Import contacts from external systems
• Programmatically build your contact list
• Create contacts from API integrations
• Add leads captured through your application

Behavior:

• Email addresses are automatically normalized (lowercased, trimmed)
• Duplicate emails return a 409 Conflict error
• Custom properties must be pre-defined in your workspace
• Property values are validated against their defined types (STRING, NUMBER, DATE, BOOLEAN)
• Maximum 100 custom property slots per contact
• Contact is created with 'subscribed' status by default
• Timestamps (createdAt, updatedAt) are automatically set
• Returns the complete contact object including generated ID

Required Scope: write:contacts

Property Validation:

• STRING: Any text value, max 5000 characters
• NUMBER: Valid numeric values (integers or decimals)
• DATE: ISO 8601 format (YYYY-MM-DD or full timestamp)
• BOOLEAN: true or false

Email Validation:

• Must be a valid email format
• Cannot exceed 320 characters
• Automatically converted to lowercase
• Leading/trailing whitespace is trimmed

Note: For bulk imports (>1000 contacts), consider using the batch import endpoint (coming soon) for better performance.