Summary
A keyable is a unique ID field you define on a custom model, used to match records when syncing with an external system.
It's the custom-model equivalent of Source ID and External ID on system models — which custom models don't have by default.
Integrations use it to decide whether to create a new record or update an existing one (an "upsert").
Source IDis still the base case for most syncs — reach for a custom keyable when you need more flexibility (a non-standard ID, or several external systems).
Who is this article for?
Admins and power users setting up integrations with custom models — for example CS Ops or Tech/Ops.
Series
This article is part of a series on Custom Models:
Creating and managing custom models · create a model, add fields, set permissions, previews, and profiles
Custom associations · associate records across models, *primary* associations, and many-to-many (junction models)
Salesforce integration for custom models · mirror a Salesforce object into a model
Custom keyables ⬅️ You are here
Joined tables · show an associated model's field as a column
Article Contents
What is a keyable?
System models (e.g. Company, End User, License) come with Source ID and External ID - a unique ID fields that integrations match records on. Custom models don't have these. A keyable is a field you add to a custom model to play that role - the unique ID an integration uses to tell whether an incoming record is one it has seen before.
For example, you might store your external system's record ID in a keyable. Then, when that record syncs again, the integration finds the existing Planhat record by its keyable and updates it, instead of creating a duplicate.
If you've worked with integrations before: a keyable is Planhat's version of an External ID (Salesforce) or an upsert / match key (ETL tools) — the field used to match records across systems.
How to create a keyable
Go to Data Model → [your model] → Fields.
Create a text field (or edit an existing text field).
Mark it as a keyable.
Save.
Once saved, the keyable appears wherever you choose a unique ID in an integration. For example the "Snowflake Id reference" dropdown in the Snowflake integration, or the record-matching field in the Salesforce integration.
✏️ Note
A keyable can't be changed after you create it (see Constraints). Name it carefully before saving.
Constraints
Must be a text field.
Name: up to 50 characters, using letters, numbers, and underscores only, no spaces or special characters. (A space in the name is a common setup mistake.)
Immutable once created: you can't change whether a field is a keyable, or its name, type, or parent. To change any of these, create a new field.
A model can have more than one keyable, up to 10.
A keyable can be used as the match key when upserting records via the API.
When to use a keyable vs. Source ID
Source ID is the recommended default for most sync scenarios. Use a custom keyable when you need more flexibility: matching against IDs from more than one external system, using a non-standard ID, or mapping associations. Don't reach for a custom keyable when Source ID would do the job.
Keyables vs. Association fields
Keyables and association fields, while both important concepts, do different jobs:
| Keyable | Association field |
Stores | An external system's ID (e.g. a Salesforce or Snowflake record key) | A Planhat record — a link to a related record |
Used for | Upsert matching — is this the same record? | Relationships — what is this record related to? |
In short: a keyable answers "is this the same record?"; an association answers "what is this record related to?" See Custom associations.
Where keyables are used
Snowflake integration the "Snowflake Id reference"
BigQuery integration the "BigQuery Id reference"
Bulk upsert via the API
Matching on a keyable in a spreadsheet import
When importing a spreadsheet, you can match rows on a custom keyable. Put the plain value in the cell, no prefix, and select the keyable in the import dialog: pick the spreadsheet column, then the field, then the keyable to match on.
The extid- and srcid- prefixes you may have seen apply only to External ID and Source ID (the system keyables). There is no prefix for custom keyables — and prefixes are optional now anyway, since the import UI lets you pair a column with an ID directly.
For more guidance on spreadsheet import, see Importing Data via Excel spreadsheet