---
updatedAt: 2026-05-20T23:04:33.000Z
agentTools:
  projectIndex: https://developer.sprucehealth.com/llms.txt
---

# Create a contact tag

This operation creates a contact tag for the given organization. This tag can then be applied to contacts in subsequent operations. Requesting creation of an already existing tag will result in a `201` response and the response will contain the existing tag.

# OpenAPI definition

```json
{
  "components": {
    "headers": {
      "s-ratelimit-limit": {
        "description": "Request limit per minute",
        "example": 100,
        "schema": {
          "type": "integer"
        }
      },
      "s-ratelimit-remaining": {
        "description": "Requests remaining this minute",
        "example": 94,
        "schema": {
          "type": "integer"
        }
      },
      "s-request-id": {
        "description": "The ID of the request",
        "example": "0E5QDGJC030000E5QDGJC03000",
        "schema": {
          "type": "string"
        }
      }
    },
    "parameters": {
      "s-idempotency-key": {
        "description": "A unique value generated by the client used to recognize subsequent retries of the same request. Idempotency keys can be up to 255 characters long.",
        "example": "S7uiKYMMRzAcuG8S",
        "in": "header",
        "name": "s-idempotency-key",
        "required": false,
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "contact_tag": {
        "properties": {
          "id": {
            "$ref": "#/components/schemas/contact_tagId"
          },
          "object": {
            "$ref": "#/components/schemas/objectType"
          },
          "value": {
            "$ref": "#/components/schemas/contact_tagValue"
          }
        },
        "required": [
          "id",
          "value",
          "object"
        ],
        "type": "object"
      },
      "contact_tagId": {
        "description": "Spruce's contact tag ID",
        "example": "tag_0E5QDGJC03000",
        "type": "string"
      },
      "contact_tagValue": {
        "description": "The text value of a contact tag",
        "example": "Smith",
        "type": "string"
      },
      "contact_tagValueContent": {
        "properties": {
          "value": {
            "$ref": "#/components/schemas/contact_tagValue"
          }
        },
        "required": [
          "value"
        ],
        "type": "object"
      },
      "error": {
        "properties": {
          "message": {
            "example": "Invalid Contact ID",
            "type": "string"
          },
          "statusCode": {
            "example": 400,
            "type": "integer"
          },
          "type": {
            "example": "BAD_PARAMETER",
            "type": "string"
          }
        },
        "required": [
          "message",
          "statusCode",
          "type"
        ],
        "type": "object"
      },
      "objectType": {
        "description": "String representing the object's type",
        "type": "string"
      }
    },
    "securitySchemes": {
      "spruceAPIToken": {
        "description": "API token provided by Spruce should be passed in an \"Authorization\" header with the value \"Bearer <token>\"",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "title": "Spruce Health API",
    "version": "1.0.0"
  },
  "openapi": "3.0.0",
  "paths": {
    "/contacts/tags": {
      "post": {
        "description": "This operation creates a contact tag for the given organization. This tag can then be applied to contacts in subsequent operations. Requesting creation of an already existing tag will result in a `201` response and the response will contain the existing tag.",
        "operationId": "CreateContactTag",
        "parameters": [
          {
            "$ref": "#/components/parameters/s-idempotency-key"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/contact_tagValueContent"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/contact_tag"
                }
              }
            },
            "description": "created",
            "headers": {
              "s-ratelimit-limit": {
                "$ref": "#/components/headers/s-ratelimit-limit"
              },
              "s-ratelimit-remaining": {
                "$ref": "#/components/headers/s-ratelimit-remaining"
              },
              "s-request-id": {
                "$ref": "#/components/headers/s-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            },
            "description": "bad request"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            },
            "description": "duplicate request"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            },
            "description": "unexpected error"
          }
        },
        "summary": "Create a contact tag",
        "tags": [
          "Contact Tags"
        ]
      }
    }
  },
  "security": [
    {
      "spruceAPIToken": []
    }
  ],
  "servers": [
    {
      "url": "https://api.sprucehealth.com/v1",
      "variables": {
        "domain": {
          "default": "api.sprucehealth.com"
        }
      }
    }
  ]
}
```