Add tags to a contact

add (merge) one or more tags to a contact; existing tags are preserved.

POST https://api.centerfy.ai/webhooks/inbound/contacts/:id/tags

Headers

Header	Required	Value	Description
`x-api-key`	Yes	your sub-account API key (cfy_…)	Authenticates the request; or use Authorization: Bearer `<key>`.
`Content-Type`	Yes	application/json	JSON request body.
`X-Webhook-Source`	No	your-system-name	Optional loop-prevention label; the outbound contact.updated trigger won’t echo this change back to the same source.

Path parameters

Name	Type	Required	Description
`id`	`string (uuid)`	Yes	The contact id to add tags to.

Body parameters

Name	Type	Required	Default	Description
`tag`	`string`	No	—	A single tag to add; normalized (lowercased and trimmed). Provide at least one of tag or tags.
`tags`	`array`	No	—	Array of tag strings to add; normalized (lowercased and trimmed) and de-duped. Provide at least one of tag or tags — 400 ‘provide at least one tag via “tag” or “tags”’ if both are empty.

Request body

{
  "tag": "vip",
  "tags": [
    "newsletter",
    "renewal"
  ]
}

Example

curl -X POST "https://api.centerfy.ai/webhooks/inbound/contacts/{id}/tags" \
  -H "x-api-key: $CENTERFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tag": "vip",
  "tags": [
    "newsletter",
    "renewal"
  ]
}'

import { CenterfyClient } from "@centerfy/sdk";

const centerfy = new CenterfyClient({ apiKey: process.env.CENTERFY_API_KEY! });

const result = await centerfy.contacts.addTags("<contactId>", {
  "tag": "vip",
  "tags": [
    "newsletter",
    "renewal"
  ]
});
console.log(result);

centerfy contacts add-tags <contactId> '{"tag":"vip","tags":["newsletter","renewal"]}'

MCP tool: centerfy_contacts_add_tags (see MCP server)

Response

{
  "status": "success",
  "contact_id": "3f1c2a9e-7b4d-4c8a-9e2f-1a2b3c4d5e6f",
  "tags": [
    "existing-tag",
    "vip",
    "newsletter",
    "renewal"
  ],
  "added": [
    "vip",
    "newsletter",
    "renewal"
  ]
}

Errors

400 — if :id is not a valid UUID or no tags are provided.
404 — if the contact does not exist.

Notes

Merge semantics — existing tags are preserved and the new tags are unioned in. Tags are managed only via this endpoint and the DELETE /tags endpoint; the create endpoint doesn’t accept tags. Accepts a single ‘tag’ and/or a ‘tags[]’ array (combined, lowercased, trimmed, de-duped). A write occurs only when the tag set actually changes, which fires the outbound contact.updated webhook. ‘added’ echoes the normalized incoming tags; ‘tags’ is the resulting full set.