> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recruitier.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating & Managing Tags
> Create custom tags to organize your jobs and track your recruitment pipeline.
## What Are Tags?
Tags are custom labels that you create and apply to your saved jobs. They are one of Recruitier's most flexible organizational tools, letting you categorize, filter, and track jobs in whatever way makes sense for your workflow. Unlike fixed categories or statuses, tags are entirely user-defined -- you decide what tags to create, what colors to assign them, and how to use them.
Every recruiter works differently. Some organize by client name, others by priority level, and others by industry or pipeline stage. Tags accommodate all of these approaches and more, because you define the system that works for you.
There are two fundamental types of tags in Recruitier:
| Type | Behavior | Best For |
| ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------- |
| **Standard tags** | Remain on a job permanently until you manually remove them | Client names, role categories, industries, pipeline stages |
| **Time-based tags** | Automatically expire after a configured number of days | Follow-up reminders, deadlines, review cycles, availability windows |
This distinction is powerful because it lets you separate permanent categorization from temporary workflow states -- all within the same tagging system.
## Creating a New Tag
Navigate to the tag management area, accessible from the Jobs section or through the Organization settings. The tag management dashboard shows all your existing tags with their names, colors, and usage counts.
Start creating a new tag. You will need to provide a name and optionally a color and time-based settings.
Choose a clear, descriptive name for the tag. Keep it short -- tag names appear as small labels on job cards, so brevity matters. Examples: "High Priority," "Client: Acme Corp," "Tech Roles," "Follow Up Needed."
Avoid overly generic names like "Important" or "Check" that will not mean anything to you in two weeks. The best tag names are self-explanatory.
Pick a color from the predefined color swatches. Recruitier provides a palette of carefully chosen colors that look great as tag labels. Simply click on the swatch that best represents your tag. Colors provide instant visual identification when scanning your job list. Use consistent color schemes -- for example, red for urgent, green for confirmed, blue for a specific client.
If this tag should automatically expire, enable the time-based option and set the duration in days. When you apply this tag to a job, it will automatically be removed after the configured number of days. See the [Tag Expiration](/organization/tags/expiration) page for details on how time-based tags work.
Save your new tag. It is immediately available to apply to any of your saved jobs.
## Tag Properties
Every tag has the following properties:
| Property | Description | Required |
| ----------------- | ------------------------------------------------------------------------------- | --------------------------------- |
| **Name** | The text label displayed on the tag. Must be unique within your tag collection. | Yes |
| **Color** | A color selected from the predefined palette swatches. | No (defaults to a standard color) |
| **Time-Based** | Whether the tag has an automatic expiration when applied to a job. | No (defaults to false) |
| **Days Duration** | If time-based, the number of days before the tag expires on a job. | Required if time-based is true |
| **Scope** | Whether the tag is personal (only you) or shared with your agency. | Automatic based on context |
Colors are selected from a predefined palette of color swatches. Click on any swatch to assign that color to your tag. This ensures consistent, visually appealing tag colors throughout the application.
## Deleting Tags
When you delete a tag:
1. The tag is permanently removed from your tag list.
2. **All associations** between that tag and your jobs are also removed (cascading delete).
3. Jobs that had the tag will no longer display it.
4. Any time-based expiration data for that tag is also removed.
Deleting a tag is permanent and cannot be undone. All job-tag associations are removed immediately across every job that had the tag. If you have dozens or hundreds of jobs tagged, this action removes the tag from all of them in one step. If you are unsure, consider renaming the tag instead of deleting it.
## The Tag Management Page
The tag management page is organized into two top-level tabs:
* **Manage Tags** -- view, create, search, and delete your tags.
* **Expiring Tags** -- monitor jobs with time-based tags that are approaching their expiration date.
### The Manage Tags Tab
Within the Manage Tags tab, your tags are organized into sub-tabs for easy navigation:
* **All** -- shows every tag you have created, with a count of total tags.
* **Normal** -- shows only standard (non-expiring) tags.
* **Time-Based** -- shows only time-based tags with their configured duration.
Each tag is displayed as a card showing its name, color, type indicator (normal or time-based with duration), and creation date. You can search for tags by name using the search bar at the top, and delete any tag directly from its card.
Tags cannot be edited after creation. If you need to change a tag's name, color, or duration, delete the existing tag and create a new one. Keep this in mind when setting up your tags -- choose names and colors carefully.
## Best Practices for Tag Naming Conventions
A well-organized tagging system makes your job collection far more useful. Here are proven approaches:
### By Client
Create a tag for each client or prospect you work with:
| Tag | Color | Purpose |
| --------------------- | ------------- | ------------------------------------- |
| Client: Acme Corp | Blue swatch | All jobs from or related to Acme Corp |
| Client: TechStart BV | Green swatch | All jobs from TechStart BV |
| Client: FinServ Group | Purple swatch | All jobs from FinServ Group |
### By Priority
Use priority tags to highlight the jobs that need attention first:
| Tag | Color | Purpose |
| ------------- | ------------- | ------------------------- |
| Urgent | Red swatch | Needs immediate action |
| High Priority | Orange swatch | Important, but not urgent |
| Normal | Blue swatch | Standard priority |
| Low Priority | Gray swatch | Nice-to-have, no rush |
### By Status or Stage
Track where each job stands in your process:
| Tag | Color | Purpose |
| -------------- | ------------- | ------------------------------------- |
| Researching | Blue swatch | Currently gathering information |
| Ready to Pitch | Green swatch | Research complete, ready for outreach |
| In Discussion | Orange swatch | Active conversation with the company |
| On Hold | Gray swatch | Paused for now |
### By Role Type
Categorize jobs by technical domain or seniority:
| Tag | Color | Purpose |
| -------- | ---------------- | -------------------------------------- |
| Backend | Dark blue swatch | Backend engineering roles |
| Frontend | Teal swatch | Frontend development roles |
| DevOps | Orange swatch | DevOps and infrastructure roles |
| Senior+ | Purple swatch | Senior, lead, and management positions |
You can combine approaches. A job can have multiple tags -- "Client: Acme Corp" + "High Priority" + "Backend" gives you maximum flexibility for filtering and organization. Do not force every job into a single category. The power of tags is in layering multiple dimensions.
## Tags and Your Team
Tags have two scoping levels depending on whether you are part of an agency:
* **Personal tags** -- Created by you, visible only to you. Every user has personal tags regardless of whether they are in an agency. Your tags are not visible to other team members, and their tags are not visible to you.
* **Agency tags** -- If you are part of an agency, admins can create shared tags that all team members can see and use. These provide organizational consistency across the team.
This dual scoping means you can maintain your own personal organization system while also benefiting from team-wide conventions.
If your agency needs shared organizational structures across the team, consider using [Projects](/organization/projects/creating-projects) for team-level tracking and tags for individual organization. Agency-shared tags are a good middle ground when your team needs consistent categorization.
## Advanced
### How Tags Work Under the Hood
Tags in Recruitier use a many-to-many relationship model. Each tag is stored as its own record with properties (name, color, time settings), and a separate junction table tracks which tags are applied to which jobs. When you apply a tag to a job, a new record is created in the junction table linking the tag ID to the job ID.
The junction record also stores a `created_at` timestamp (when the tag was applied) and, for time-based tags, an `expires_at` timestamp calculated as `created_at + days_duration`. This per-association expiration means the same time-based tag can have different expiration dates on different jobs depending on when it was applied.
### Duplicate Prevention
Recruitier enforces uniqueness at the job-tag association level. You cannot apply the same tag to the same job twice. If a tag is already on a job, attempting to apply it again has no effect. This prevents accidental duplicates when batch-tagging or when multiple workflows touch the same job.
### Tag Deletion and Cascading
When you delete a tag, the system performs a cascading delete: the tag record is removed, and every junction record referencing that tag is also removed. This means deleting a tag that is applied to 500 jobs will remove all 500 associations in one operation. The jobs themselves are never affected -- only the tag labels disappear.
### Performance and Batch Loading
When Recruitier loads your job list, it does not make a separate database query for each job's tags. Instead, it uses a batch loading mechanism (`get_tags_for_multiple_jobs`) that retrieves all tags for all visible jobs in a single query. This is why tag-heavy views remain fast even when you have hundreds of tagged jobs -- the system avoids the "N+1 query problem" that would otherwise slow down the page.
### Connection to Other Features
* **Filtering**: Tags connect directly to the job list filtering system. When you apply a tag filter, the system queries the junction table to find matching jobs. See [Filtering by Tags](/organization/tags/filtering).
* **Projects**: Tags and projects serve complementary organizational roles. Tags categorize individual jobs with flexible labels, while projects group searches and their jobs into broader engagement containers. Use both together for maximum organization.
* **Outreach**: Tags do not directly affect outreach flows, but they are visible on job cards during outreach planning, helping you prioritize which jobs to reach out on first.
* **Search results**: Tags appear on job cards in search results, letting you recognize previously tagged jobs and avoid duplicate work.
### Power-User Tips
* **Prefix conventions**: Use prefixes like "Client:", "Skill:", "Stage:" to create a pseudo-hierarchical tag system. This makes tags easier to find in long lists and creates natural groupings in the tag selector.
* **Color coding by category**: Assign a consistent color to each prefix group (all client tags in blue, all priority tags in red/orange, all skill tags in green). This creates instant visual parsing in your job list.
* **Seasonal cleanup**: At the end of each quarter, review your tag list and delete tags that are no longer relevant. Tags with zero jobs applied are candidates for removal.
* **Time-based tags for accountability**: Use short-duration time-based tags (1-3 days) as personal accountability markers. Apply them when you commit to taking action on a job, and their approaching expiration keeps you honest.
## Next Steps
Learn how to apply tags to your saved jobs.
Use tags to quickly find and filter your job collection.
Apply tags to multiple jobs at once.
Set up time-based tags that automatically expire.