Unique Name Used by API
A Unique Name Used by API is the programmatic identifier Salesforce assigns to an object, field, or component so that code, formulas, and integrations can reference it precisely.
Definition
A Unique Name Used by API is the programmatic identifier Salesforce assigns to an object, field, or component so that code, formulas, and integrations can reference it precisely. It is more commonly called the API Name, and in some setup screens it appears as the Developer Name. Every standard and custom element carries one, separate from the human-friendly Label shown on the screen.
The API Name is what stays constant when admins relabel things for users. A field can read "Annual Revenue" today and "Yearly Revenue" tomorrow, yet its API Name keeps pointing every Apex line, flow, and report formula at the same column. Custom objects and fields end with the __c suffix, and components from a managed package gain a namespace prefix.
How the API Name keeps your automation pointed at the right thing
Label versus API Name, and why both exist
Salesforce gives every object and field two names. The Label is the display text users read on page layouts, list views, and reports. The API Name is the identifier that code and the platform use under the hood. Splitting these apart solves a real problem. Business teams want to rename things to match how they talk, and they should be able to do that without breaking anything. So the Label is editable at will, while the API Name is meant to hold steady. When you build a flow, write an Apex query, or author a formula, you reference the API Name, not the Label. A SOQL line like SELECT Annual_Revenue__c FROM Account uses the API Name. If someone later changes the field Label to "Yearly Revenue," that query keeps working because the API Name did not move. This is the whole reason the two names are decoupled. You get a stable contract for your automation on one side and a flexible display name for your users on the other. Knowing which name a tool expects saves a lot of confused debugging.
The __c suffix and the namespace prefix
The shape of an API Name tells you where the element came from. Standard fields that ship with Salesforce, like Name or Industry on Account, use plain API Names with no suffix. Anything you create yourself gets the custom marker. A custom field named "Region" becomes Region__c, and a custom object named "Project" becomes Project__c. That double-underscore-c suffix is how the platform separates your additions from its own. Components delivered inside a managed package add one more piece: a namespace prefix. If a package with the namespace acme installs a custom field, its API Name looks like acme__Region__c. The prefix guarantees that two packages, or a package and your own org, never collide on the same name. You will see this pattern constantly when you integrate with AppExchange products. When you write code or build integrations against packaged data, you must include the namespace prefix exactly, or the reference will not resolve. Standard objects and fields never carry a prefix.
The rules a valid API Name must follow
Salesforce enforces a strict format so API Names stay safe to use in code. The name must begin with a letter, never a number or symbol. It cannot contain spaces, so the setup screen converts a Label like "Annual Revenue" into Annual_Revenue automatically by swapping the space for an underscore. The name cannot end with an underscore, and it cannot contain two consecutive underscores in the part you control. That second rule matters because the platform reserves the double underscore for its own suffix and prefix machinery. Length is capped at 40 characters for the name you enter. If you query field metadata, the describe call reports this 40-character maximum for the API Name. Plan for it when you have long, descriptive labels, because the API Name may need to abbreviate. Allowed characters are letters, numbers, and single underscores. The platform also blocks reserved words and names that would clash with existing elements on the same object. Following these constraints up front prevents save errors and keeps your naming predictable across the whole org.
Why renaming an API Name is risky
Changing a Label is free. Changing an API Name is not. Salesforce itself advises against renaming an API Name unless it is truly necessary, because the platform does not automatically rewrite every reference for you. Your Apex classes, triggers, Visualforce pages, flows, formula fields, validation rules, and outside integrations all store the old API Name as text. Rename the field underneath them and those references can throw errors or silently point at nothing. The safe order of operations is to find and update the references first, then change the API Name. Salesforce recommends using the Salesforce Extension for VS Code to search your metadata for every place the old name appears. Web service callouts written in Apex are easy to miss, since they often build queries as strings. External systems that call your org through REST or SOAP are the riskiest of all, because they live outside Salesforce and will not show up in any in-org search. This fragility is exactly why experienced teams treat the first API Name as close to permanent.
Where to find an API Name fast
You rarely have to guess an API Name. In Lightning Experience, open Setup, go to Object Manager, and pick the object. The object detail page shows the object API Name, and under Fields and Relationships the column labeled Field Name holds each field API Name. The Label and the API Name sit side by side, so you can match them at a glance. In Salesforce Classic the same information lives under Setup, then Create, then Objects. For standard objects and fields, the Object Reference in the developer documentation lists every API Name. That reference is the authoritative source when you are coding against Account, Contact, or any out-of-the-box element. Developers also pull API Names programmatically through the describe calls in the Metadata and REST APIs, which is how tools like data loaders build their field pickers. When you build a report-type formula or a flow resource, the builder usually presents the Label but stores the API Name. Keeping a habit of checking the real API Name before you write any reference removes a whole class of typo bugs.
Choosing API Names you will not regret
Because API Names are hard to change, the time to think about them is the moment you create the element. Pick a name that reads clearly in code, not just on a screen. A field for a customer loyalty tier is better as Loyalty_Tier__c than as something cryptic, since the next developer has to read it cold. Consistency across the org matters more than any single clever choice. If you abbreviate "Number" as Num in one place, do it everywhere, so people can predict the name without looking it up. Avoid baking volatile facts into the name. A field named FY24_Target__c ages badly the moment the fiscal year turns over, yet its API Name is the part you cannot easily fix. Keep the Label for the wording that may shift and let the API Name describe the stable concept underneath. Teams that ship managed packages think even harder here, since their namespace prefix and field names become public surface that customers code against. A few minutes of deliberate naming at creation saves hours of risky renames later.
Create a custom field and set its API Name
You assign an API Name every time you create a custom field. The setup wizard proposes one from your Label, but you can refine it. Here is how to create a custom field and set a clean API Name on a custom or standard object in Lightning Experience.
- Open the object in Object Manager
From Setup, type Object Manager in Quick Find and open it. Click the object you want to extend, then choose Fields and Relationships, and click New.
- Pick the field type
Select the data type, such as Text, Number, or Picklist, then click Next. The type cannot be changed freely later, so choose carefully.
- Enter the Label and review the API Name
Type the Field Label. Salesforce fills in Field Name (the API Name) by replacing spaces with underscores. Adjust it now to keep it clear, short, and consistent with your other fields.
- Set visibility and save
Choose field-level security and the page layouts where the field appears, then click Save. The platform appends __c to your API Name automatically.
The display name users see. Salesforce derives a starting API Name from it but the two can differ.
The programmatic identifier. Must start with a letter, use only letters, numbers, and single underscores, and stay within 40 characters.
Determines how the field stores and validates data, and shapes how it behaves in queries and formulas.
- The API Name cannot end with an underscore or contain two consecutive underscores in the part you enter; the platform reserves __ for its own suffix.
- Renaming the API Name after code or integrations reference it can throw errors, so settle on the name before you build automation.
- On a field added by a managed package, the API Name includes the namespace prefix, and you must reference it exactly in code.
Trust & references
Cross-checked against the following references.
- How to Find the API Name of a Field or ObjectSalesforce
- Change the API name of a fieldSalesforce
Straight from the source - Salesforce's reference material on Unique Name Used by API.
Hands-on resources to go deeper on Unique Name Used by API.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is the API Name?
Q2. What suffix do custom fields use?
Q3. Can API names be changed easily?
Discussion
Loading discussion…