---
updatedAt: 2026-05-06T14:37:59.000Z
agentTools:
  projectIndex: https://developers.campaignrefinery.com/llms.txt
---

# Update Goal

Updates an existing goal (name, match type, tag mappings). The goal is identified by `goal_uuid` and must belong to the authenticated account. Tag mappings are only rewritten when `tag_ids` is sent in the body: omit the field to leave existing mappings untouched, send an empty array to clear them.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Goals",
    "version": "1.2.0",
    "description": "Create and update goals, list goals in the authenticated account, and mark goals as completed for contacts. Goal endpoints use goal UUIDs and can optionally connect goals to campaigns and tags."
  },
  "servers": [
    {
      "url": "https://api.campaignrefinery.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token authentication"
      }
    }
  },
  "security": [],
  "paths": {
    "/rest/goals/update_goal": {
      "post": {
        "summary": "Update Goal",
        "description": "Updates an existing goal (name, match type, tag mappings). The goal is identified by `goal_uuid` and must belong to the authenticated account. Tag mappings are only rewritten when `tag_ids` is sent in the body: omit the field to leave existing mappings untouched, send an empty array to clear them.",
        "operationId": "update-goal",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "goal_uuid",
                  "goal_name"
                ],
                "properties": {
                  "goal_uuid": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The goal UUID."
                  },
                  "goal_name": {
                    "type": "string",
                    "maxLength": 255
                  },
                  "goal_match_type": {
                    "type": "integer",
                    "enum": [
                      0,
                      1
                    ],
                    "description": "Optional. 0 = ANY, 1 = ALL."
                  },
                  "tag_ids": {
                    "type": "array",
                    "description": "Optional. Tag UUIDs to map. Omit to leave existing mappings untouched; send empty array to clear all mappings.",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              },
              "examples": {
                "Rename only": {
                  "summary": "Rename without touching tags",
                  "value": {
                    "goal_uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
                    "goal_name": "Newsletter Signup (renamed)"
                  }
                },
                "Replace tags": {
                  "summary": "Rewrite tag mappings",
                  "value": {
                    "goal_uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
                    "goal_name": "Newsletter Signup",
                    "goal_match_type": 1,
                    "tag_ids": [
                      "11111111-2222-3333-4444-555555555555"
                    ]
                  }
                },
                "Clear tags": {
                  "summary": "Clear all tag mappings",
                  "value": {
                    "goal_uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
                    "goal_name": "Newsletter Signup",
                    "tag_ids": []
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Goal updated.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "message": "Updated goal",
                  "data": {
                    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
                    "goal_uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
                    "goal_name": "Newsletter Signup (renamed)",
                    "campaign_uuid": "11111111-2222-3333-4444-555555555555",
                    "goal_match_type": 1,
                    "tag_ids": [
                      "11111111-2222-3333-4444-555555555555"
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token."
          },
          "404": {
            "description": "Goal not found for the authenticated account.",
            "content": {
              "application/json": {
                "example": {
                  "success": false,
                  "message": "Goal not found.",
                  "data": []
                }
              }
            }
          },
          "422": {
            "description": "Validation error. Common causes: missing `goal_uuid` or `goal_name`, invalid UUID, `goal_match_type` not in {0, 1}, non-UUID entry in `tag_ids`, unknown tag UUID.",
            "content": {
              "application/json": {
                "example": {
                  "success": false,
                  "message": "Validation failed.",
                  "data": {
                    "errors": {
                      "goal_uuid": [
                        "The goal uuid field is required."
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  }
}
```