Tags in Pinpoint let you categorise and filter candidates and applications. This guide explains how to apply tags correctly via the API so they appear in the right filter groups inside the Pinpoint UI.

How Tags and Categories Work

Every tag in Pinpoint belongs to a tag category (also called a tag group). In the UI, these categories appear as named sections — for example, "Rejection Reasons" or "Skills" — and they power the filter panel.

If you want the tag to be filtrable you must first create it in the UI!

When you apply a tag via the API, you must supply two pieces of information:

Getting the context right is the critical step — it is what determines which filter group the tag appears under in the UI.

Finding the Right context Value

The context value is derived from the name of the tag category in Pinpoint settings (Settings → Tag Management). The rules are:

• Custom categories (anything you create): take the category name, lowercase it, replace spaces with underscores, and prefix with custom_. For example:
  • Category named "Rejection Reasons" → context: "custom_rejection_reasons"
  • Category named "Skills" → context: "custom_skills"
  • Category named "Green Skills" → context: "custom_green_skills"
• The built-in Rejection category: context is always "rejection" (no custom_ prefix).
• System tags (Internal, Duplicate, Referral, External Recruiter, etc.): these are applied automatically by Pinpoint and cannot be set via the API. Their context is null in API responses.

Tip: The safest way to confirm the correct context for a category is to read back an existing application that already has a tag from that category. The response will include the context value you need (see Reading Tags below).

Reading Tags

Tags are returned as an array in the tags attribute when you fetch an application or job seeker:

Request: GET /api/v1/applications/{id}?extra_fields[applications]=tags

Response (tags field):

"tags": [
  { "context": "custom_rejection_reasons", "name": "Not Qualified" },
  { "context": "custom_skills",            "name": "Ruby" },
  { "context": "rejection",               "name": "Availability" },
  { "context": null,                      "name": "Internal" }
]

The context value in any existing tag response is exactly the value you should pass when writing tags.

Adding Tags

Use a PATCH or PUT request on the resource. You can add one tag at a time or several in one request.

Add a single tag:

PATCH /api/v1/applications/{id}

{
  "add_tag_with_context": {
    "tag": "Not Qualified",
    "context": "custom_rejection_reasons"
  }
}

Add multiple tags at once:

PATCH /api/v1/applications/{id}

{
  "add_tags_with_context": [
    { "tag": "Not Qualified",  "context": "custom_rejection_reasons" },
    { "tag": "Ruby",           "context": "custom_skills" }
  ]
}

The same fields work on job seeker records: PATCH /api/v1/job_seekers/{id}

Removing Tags

PATCH /api/v1/applications/{id}

{
  "remove_tag_with_context": {
    "tag": "Not Qualified",
    "context": "custom_rejection_reasons"
  }
  }

To remove several at once, use remove_tags_with_context with an array, following the same pattern as add_tags_with_context.