How to create a custom datetime property in HubSpot
Step-by-step guide with tips, pitfalls, and troubleshooting.
Sometimes tracking “just the date” isn’t enough. You want the exact moment something happened, like when a contact downloaded content, when a demo was booked, or when a deal hit a certain stage.
That’s where a Datetime Property comes in.
As of 2025, many HubSpot portals now allow you to create Date and Time properties directly in the UI. If you don’t see the option, you can still build one with the CRM Properties API. Both methods work, but the UI is easier if it’s available.
Let’s walk through when to use datetime vs date, what’s required, and two different ways to set it up.
If you want to skip manual setup and get a team of HubSpot-Salesforce experts to take over the wheel? Drop us a line.
When to use datetime vs date
Datetime is worth the effort when your Workflows, Reports, or Personalization Tokens need the specific hour and minute. Examples: webinar registrations, downloads, and meetings booked.
If all you need is the day itself, like for renewals or birthdays, stick with Date. It’s just simpler.
One important update: since April 16, 2025, Marketing Emails that use datetime tokens now render both the date and the time. If you expected date-only formatting, you’ll want to adjust your templates.
Prerequisites for both methods
Before you start, you’ll need:
- HubSpot Super Admin access to change Properties and, if using the API, create a Private App.
- Six data points for your new Property:
- Name (internal system name)
- Label (the friendly name you’ll see in HubSpot)
- Type (datetime or date)
- Field Type (Date and Time if creating in the UI; see notes below for API)
- Group Name (the Property Group you want it to live under)
- Object Type (Contacts, Companies, Deals, Tickets, or a Custom Object)
Method 1: create a datetime property in the HubSpot UI
Use this method if your portal shows “Date and Time” as a field type.
- Go to Settings → Objects → [Your Object] → Properties.
- Click Create property.
- Select the Object, choose the Group, and set the Label. HubSpot will auto-generate the Internal Name.
- For Field Type, select Date and Time. You can also set display preferences, such as showing relative time (“3 hours ago”).
- Save the Property.
- Test by adding it to a record and checking that both the Date and Time appear.
Tip: Right now, HubSpot Forms only support date-only fields. If you need both date and time, capture it through Workflows, Integrations, or a custom form.
Also keep in mind that HubSpot stores a single consistent timestamp in the background. What you see depends on the portal or user’s timezone. Always test in your region before rolling out.
Method 2: create a datetime property via the API (works everywhere)
If the UI doesn’t show a Date and Time option OR if you want to script it, use the CRM Properties API.
Step 1: gather your property data
- objectType: for example, contacts
- name: intro_guide_download_date
- label: Intro Guide Download Date
- type: datetime
- fieldType: see note below (API quirk: sometimes still “date”)
- groupName: for example, conversioninformation
- Optional: description, displayOrder (set to 1), hidden, etc.
Step 2: create a private app
- In HubSpot, create a Private App with the schema write scope for your object.
- For Contacts, the scope is crm.schemas.contacts.write.
- Once created, go to the Auth tab and copy the Access Token.
Step 3: Send the request
- Use POST /crm/v3/properties/{objectType}.
- Include your JSON body with the details above.
- Authenticate with your Bearer Token.
- A successful request will return HTTP 201 with your new property definition.
Important API notes
Type vs. fieldType: Set type = datetime. The API sometimes expects fieldType = date. If you get a 400 error, adjust this.
400 errors: If you’re stuck, set displayOrder = 1 and clear out advanced attributes like referencedObjectType, calculationFormula, or externalOptions.
Posting values: Use UNIX milliseconds or ISO-8601 format, depending on the endpoint. Always test with one record before scaling.
A property setup example:
Say you want to track the exact date and time an “Intro Guide” was downloaded on a Contact.
Your properties will look something like this:
- Object Type: Contacts
- Group Name: conversioninformation
- Name: intro_guide_download_date
- Label: Intro Guide Download Date
- Type: datetime
- Field Type: Date and Time (UI) or date (API quirk)
- Display Order: 1
Now test!
Once you’ve created the property, head to Settings → Properties and look it up.
Add it to a test Contact and set a value to make sure it’s working. In some portals, it may display as just a Date in the UI; don’t worry, the property is still stored as a full Datetime behind the scenes.
To be sure everything works as expected, try using it in a Workflow trigger or a Report. That way you’ll confirm both the Date and the Time carry through into your automations and reporting.
FAQ: custom datetime property in HubSpot
Can I convert a Date Property into a Datetime Property?
You can update a Property definition via the API, but existing values won’t magically gain a time component. Plan a Backfill if you need time.
Can I use Datetime in Calculations (time since, time between)?
Yes. Calculation Properties support time-based math. Remember, the raw values are stored in Milliseconds.
What formats are accepted when writing values via API?
Use UNIX Milliseconds or ISO-8601 (endpoint-dependent). Prefer one format across your stack to stay sane.
