Systeme.io Tags in N8N: How to Find the Numeric ID Fast

You created the tag in Systeme.io. You typed the name into your N8N workflow. The workflow ran. No errors. Nothing happened. Three days later the contact still has no tag.

This is Systeme.io's way of telling you: please use the number.

The tag API identifies tags by numeric ID, not by name. social-agent means nothing to the assign endpoint. 482910 means everything. Think of it like a library catalogue — the spine says The Martian, the database tracks it as an ISBN. The catalogue always wins. This guide gets you from tag name to numeric ID in under two minutes.

Why the tag name breaks your automation

Systeme.io's API identifies every resource — contacts, tags, products — by numeric ID. The name you see in the dashboard is a human-readable label. The API works with integers.

When you pass {"tagName": "social-agent"} to the assign endpoint, one of two things happens: an error, or silence. Usually silence. The workflow runs, the step completes, and nothing gets tagged. No red X. No log entry. The tag name just quietly does nothing.

Passing {"tagId": 482910} works every time. The only task is finding that number.

Create a tag in Systeme.io

If the tag already exists, skip to finding the ID. If not:

1. Log into your Systeme.io dashboard.
2. Click Contacts in the top navigation bar.
3. Click Tags from the sub-menu.
4. Click + New Tag in the top-right corner.
5. Enter a name. Lowercase with hyphens keeps things clean: social-agent, facebook-lead, comment-inquiry. Spaces work but hyphens are easier to work with in API calls.
6. Click Save.

The AIIP Social Agent uses exactly two Systeme.io tags: social_agent — applied to every contact who interacts via any social platform — and comment — applied specifically to contacts who came through a public Facebook comment. Platform and channel state is tracked in Supabase, not via additional CRM tags. Two tags is deliberate: it keeps the system running on a Startup plan ($17/mo) with 8 tag slots to spare.

Free plan note: Systeme.io's free plan allows 1 tag. If you need two tags for the social agent system, you're on at minimum the Startup plan.

Find the ID: method one (URL)

Click on your tag in the Tags list. Check the browser address bar:

https://systeme.io/contacts/tags/482910

That number — 482910 in this example — is your tag ID. Write it down.

If the URL doesn't show a numeric segment, Systeme.io's routing varies between account regions and dashboard versions. Use method two — it works regardless of which dashboard version your account is on.

Find the ID: method two (API)

Open your terminal or a REST client. Run this:

curl -X GET "https://api.systeme.io/api/tags"   -H "X-API-Key: YOUR_SYSTEME_API_KEY"   -H "accept: application/json"

Your Systeme.io API key is at Settings → API Keys in your dashboard. The response looks like this:

{
  "items": [
    { "id": 482910, "name": "social-agent" },
    { "id": 391847, "name": "comment" }
  ]
}

Find your tag name. The integer next to it is your ID. To narrow the response to a specific tag name:

curl "https://api.systeme.io/api/tags?query=social-agent"   -H "X-API-Key: YOUR_SYSTEME_API_KEY"

This is also how you verify a tag still exists before trusting a stored ID. Automation that fails silently usually fails because the tag was deleted or renamed and the ID in your environment variables was never updated.

Use the ID in your N8N workflow

The tag ID belongs in your environment variables — not hardcoded in the workflow JSON. Hardcoded values break when you deploy to a new instance or pass the workflow to a client.

In your .env file alongside docker-compose.yml:

SYSTEME_TAG_ID_SOCIAL_AGENT=482910
SYSTEME_TAG_ID_COMMENT=391847

Reference them inside N8N workflow nodes as:

{{ $env.SYSTEME_TAG_ID_SOCIAL_AGENT }}

The HTTP Request node that assigns a tag to a contact looks like this:

Method: POST
URL: https://api.systeme.io/api/contacts/{{ $json.systeme_contact_id }}/tags
Headers:
  X-API-Key: {{ $env.SYSTEME_IO_API_KEY }}
  Content-Type: application/json
Body:
{
  "tagId": {{ $env.SYSTEME_TAG_ID_SOCIAL_AGENT }}
}

One thing to watch: the tagId field expects an integer. N8N environment variables are returned as strings by default. If you get 400 errors on the tag assignment step, try wrapping the reference: {{ parseInt($env.SYSTEME_TAG_ID_SOCIAL_AGENT) }}. Most setups work without this, but it's the first thing to check if the assign step fails.

If you're setting up the self-hosted VPS first, the N8N VPS setup guide covers the full docker-compose.yml and environment variable structure. The N8N API key guide covers the deployment authentication step that uses the key alongside these tag IDs.

Systeme.io tag API reference

Everything for tag operations in one place. Base URL: https://api.systeme.io/api. All requests require the header X-API-Key: YOUR_KEY.

Operation	Method	Endpoint	Body
List all tags	GET	/api/tags	—
Create a tag	POST	/api/tags	{"name": "tag-name"}
Get one tag	GET	/api/tags/{id}	—
Update a tag	PUT	/api/tags/{id}	{"name": "new-name"}
Delete a tag	DELETE	/api/tags/{id}	—
Assign tag to contact	POST	/api/contacts/{id}/tags	{"tagId": 482910}
Remove tag from contact	DELETE	/api/contacts/{id}/tags/{tagId}	—

Full reference: developer.systeme.io/reference. For broader REST API conventions on resource identification — which explains why numeric IDs are the standard — restfulapi.net's resource naming guide covers the underlying reasoning. The short version: names change, numbers don't. Your tag could be renamed "social-lead" tomorrow. The ID stays the same.

Three mistakes that stop this cold

1. Using the tag name instead of the ID. The assign endpoint does not accept tag names. {"tagName": "social-agent"} fails silently. {"tagId": 482910} works. The API has the energy of a very tired IT manager who has answered this question before — it will simply not comply, and it will not explain why.

2. Assigning a tag before the contact exists. POST /api/contacts/{id}/tags requires a valid contact ID. If you're creating the contact and tagging them in the same workflow, the tag step must run after the contact creation step returns a contact ID. N8N's default sequential execution handles this correctly as long as you don't split the flow prematurely.

3. Using a string ID instead of an integer. The tagId field expects {"tagId": 482910}, not {"tagId": "482910"}. If your workflow passes the env var directly into a JSON body, test whether the API accepts it. Use {{ parseInt($env.SYSTEME_TAG_ID_SOCIAL_AGENT) }} if you get 400 errors on the tag assignment node.

Once your tag IDs are confirmed and stored in your environment variables, the social agent system has everything it needs to start tagging contacts automatically. If you'd rather have someone else configure the N8N workflows, Supabase tables, and Systeme.io integration — that's exactly what the AI-Ready Business Blueprint covers. Book a call to see what that looks like for your setup.