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, and nothing happened. Three days later the contact still has no tag.

That's Systeme.io telling you, in its own quiet way, to use the number instead.

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, and 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 in the dashboard is a human-readable label for you. The API only works with integers.

Pass {"tagName": "social-agent"} to the assign endpoint and 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.

Pass {"tagId": 482910} and it works every time. The only task left is finding that number.

Create a tag in Systeme.io

If the tag already exists, skip ahead 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 too, but hyphens are easier to reference in API calls.
6. Click Save.

The social agent workflows we build use exactly two Systeme.io tags: social_agent, applied to every contact who interacts through any social platform, and comment, applied specifically to contacts who came in through a public Facebook comment. Platform and channel state live in Supabase, not in extra CRM tags. Two tags is deliberate, it keeps the whole setup running on Systeme.io's Startup plan ($17/month) with 8 tag slots left over.

One plan note worth flagging: Systeme.io's free plan allows 1 tag. If your automation needs two tags, budget for at least the Startup plan.

Find the ID: method one (URL)

Click your tag in the Tags list and check the browser address bar: https://systeme.io/contacts/tags/482910.

That number, 482910 in this example, is your tag ID.

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

Find the ID: method two (API)

Open your terminal or a REST client and run 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 sits under Settings, then API Keys, in your dashboard. The response looks like { "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 one tag, add a query: curl "https://api.systeme.io/api/tags?query=social-agent" -H "X-API-Key: YOUR_SYSTEME_API_KEY".

This is also how to check a tag still exists before trusting a stored ID. Automation that fails silently usually fails because the tag was deleted or renamed and nobody updated the environment variable.

Use the ID in your N8N workflow

The tag ID belongs in your environment variables, not hardcoded into the workflow JSON. Hardcoded values break the moment you deploy to a new instance or hand the workflow to a client.

In your .env file alongside docker-compose.yml, set SYSTEME_TAG_ID_SOCIAL_AGENT=482910 and SYSTEME_TAG_ID_COMMENT=391847. Reference them inside N8N nodes as {{ $env.SYSTEME_TAG_ID_SOCIAL_AGENT }}.

The HTTP Request node that assigns a tag to a contact needs a POST method, the URL https://api.systeme.io/api/contacts/{{ $json.systeme_contact_id }}/tags, an X-API-Key header set to {{ $env.SYSTEME_IO_API_KEY }}, a Content-Type: application/json header, and a body of {"tagId": {{ $env.SYSTEME_TAG_ID_SOCIAL_AGENT }} }.

One thing to watch: the tagId field expects an integer, and N8N environment variables come back as strings by default. If the tag assignment step throws 400 errors, wrap the reference: {{ parseInt($env.SYSTEME_TAG_ID_SOCIAL_AGENT) }}. Most setups never need this, but it's the first thing to check when the assign step fails.

If you're still setting up the self-hosted VPS, 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 runs alongside these tag IDs.

Systeme.io tag API reference

Everything for tag operations, in one place. Base URL: https://api.systeme.io/api. Every request needs the header X-API-Key: YOUR_KEY.

• List all tags: GET /api/tags, no body.
• Create a tag: POST /api/tags, body {"name": "tag-name"}.
• Get one tag: GET /api/tags/{id}, no body.
• Update a tag: PUT /api/tags/{id}, body {"name": "new-name"}.
• Delete a tag: DELETE /api/tags/{id}, no body.
• Assign tag to contact: POST /api/contacts/{id}/tags, body {"tagId": 482910}.
• Remove tag from contact: DELETE /api/contacts/{id}/tags/{tagId}, no body.

Full reference: developer.systeme.io/reference. For the broader logic behind identifying resources by number instead of name, restfulapi.net's resource naming guide covers it well. The short version: names change, numbers don't. Your tag could get renamed "social-lead" tomorrow. The ID stays exactly the same.

Three mistakes that stop this cold

Using the tag name instead of the ID. The assign endpoint doesn't accept tag names. {"tagName": "social-agent"} fails silently, {"tagId": 482910} works. The API has the energy of a tired IT manager who has answered this question one too many times, it simply won't comply, and it won't explain why.

Assigning a tag before the contact exists. POST /api/contacts/{id}/tags needs a valid contact ID. If you're creating the contact and tagging them in the same workflow, the tag step has to run after the contact-creation step returns an ID. N8N's default sequential execution handles this fine as long as you don't split the flow too early.

Using a string ID instead of an integer. The tagId field expects {"tagId": 482910}, not {"tagId": "482910"}. If your workflow passes the environment variable straight into a JSON body, test whether the API accepts it as-is. Use {{ parseInt($env.SYSTEME_TAG_ID_SOCIAL_AGENT) }} if you're getting 400 errors on the tag assignment node.

Once your tag IDs are confirmed and sitting in your environment variables, the automation has everything it needs to start tagging contacts on its own. If you'd rather have someone else configure the N8N workflows, Supabase tables, and Systeme.io integration, that's what our AI Readiness Blueprint covers.