List candidate tags of the organization | Deel

curl -G https://api.letsdeel.com/rest/ats/tags \
     -H "Authorization: Bearer <token>" \
     -d cursor=eyJwYWdlIjoyfQ \
     -d include_archived=true \
     -d include_counts=false \
     -d limit=20 \
     -d search_text=Referral \
     -d tag_group_slug=CANDIDATE

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2026-02-26T12:00:00.000Z",
      "updated_at": "2026-02-26T12:00:00.000Z",
      "label": "Referral",
      "archived_at": "2026-09-03T10:24:11.512Z",
      "tag_group_slug": "CANDIDATE",
      "candidates_count": 5,
      "created_by_hris_organization_user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "updated_by_hris_organization_user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJwYWdlIjoyfQ==",
  "total_count": 10
}

Lists the candidate tags of the organization. Use it to find tag ids before setting the tags of a candidate with POST /rest/ats/candidates/{candidate_id}/tags or filtering candidates by tag with GET /rest/ats/candidates.

Token scopes: ats:read, worker:read

Authentication

AuthorizationBearer

Authentication

The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail.

curl -X GET 'https://api.deel.training/rest/v2/contracts' \
  -H 'Authorization: Bearer YOUR-TOKEN-HERE'

Learn more about authentication

AuthorizationBearer

Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/

Query parameters

search_textstringOptional<=50 characters

Filter tags by label (case-insensitive partial match)

tag_group_slugenumOptional

Filter by tag group. Use CANDIDATE for candidate tags.

Allowed values:

include_archivedstringOptional

If true, archived tags are included in the response; they are excluded by default.

include_countsenumOptionalDefaults to false

When true, each tag includes candidates_count (number of candidates with that tag)

Allowed values:

cursorstringOptional<=1000 characters

Opaque cursor for pagination. Use the value from next_cursor of the previous response to fetch the next page.

limitintegerOptional1-100Defaults to 20

Maximum number of tags to return per page (default: 20, max: 100).

Response

Successful operation. Returns the list of tags for the organization.

datalist of objects

List of tags.

has_moreboolean

Whether more results exist (pagination).

next_cursorstring or null<=1000 characters

Cursor for the next page of results, or null if none.

total_countinteger>=0

Total number of tags returned.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error