Goals API - HubSpot docs

Scope requirements

In HubSpot, goals are used to create user-specific quotas for their sales and services teams based on templates provided by HubSpot. The goals API allow you to retrieve goals data in your HubSpot account. Learn more about using goals in HubSpot.

Understanding goal architecture

Unlike standard objects (like deals or contacts) which exist as single rows, a “Goal” in HubSpot is a container for multiple time-bound objects. To successfully create or manage goals, you must understand the hierarchy of the three key components: Goal Family, Goal Target Group, and Goal Target.

The goal hierarchy

The API defines a goal using a nesting structure linked by specific IDs.

Goal family (the “goal”)

This is what a user perceives as one goal (e.g., “2025 Revenue Quota”). It is identified by the hs_group_correlation_uuid. This ID links every time-slice together into one cohesive unit.

A screenshot of the Edit targets tab for the Calls made goal in HubSpot. The view is set to Users with goals for the year 2026. A table lists two representatives, Daniel the Cat and Jess Geist, both with a Number of calls unit of measurement. Each rep has a target of 100 for the months of February, March, April, and May 2026. The All reps row at the bottom shows a total of 200 calls for each of these four months. The table also includes an Actions column with Apply target links and an Import user targets button above the table.

In your account, all targets (whether weekly, monthly, quarterly, or yearly) appear under a single goal name (e.g., Calls made) because they share the same hs_group_correlation_uuid. If this ID differs across targets, they will appear as separate goals.

Goal Target Group (The Schedule)

This represents the schedule or assignment constraints (e.g., “Monthly targets for User A”). It is identified by the hs_goal_target_group_id. All time periods for that specific user’s schedule share this ID.

A screenshot of the Edit targets tab for the Calls made goal in HubSpot. There are red outlines around the rows for Daniel the Cat and Jess Geist. The outlines highlight these two rows, which contain the target information for the two representatives for the months of February, March, April, and May 2026. The Apply target links, the numerical target values, and the unit of measurement are all included within the outlined areas.

In your account, this determines which targets are grouped together for a specific assignment. For user goals, the hubspot_owner_id property determines who sees this goal in their dashboard. For team goals, the hs_assignee_team_id (or hubspot_team_id) property is used instead to assign the goal to the entire team.

Goal target (the time slice)

These are the individual objects holding the data. For a monthly goal, there are 12 separate goal_target objects (Jan, Feb, Mar…). Each has its own hs_start_datetime and hs_target_amount.

This image displays the Edit targets interface for the Calls made goal. Red outlines highlight the individual target input cells for February, March, April, and May 2026. Each outlined cell contains a value of 100 for representatives Daniel the Cat and Jess Geist, emphasizing the specific goal targets for each time slice.

In your account, each target appears as a distinct column in the goal timeline, showing the specific target for that period and tracking progress against that individual slice.

Example: Structure of a Monthly Goal

The JSON below illustrates two separate goal objects: one for January and one for February. While the target data (dates and amounts) changes for each month, they belong to the same Goal Family and Goal Target Group. As shown in the highlighted lines, the hs_goal_name, hs_group_correlation_uuid, and hs_goal_target_group_id remain constant to link these objects into a single cohesive goal schedule.

{
  "inputs": [
    {
      "properties": {
        "hs_goal_name": "Sales Quota 2027",
        "hs_milestone": "monthly",
        "hs_goal_type": "sales_quota",
        "hs_target_amount": "1200.00",
        "hs_start_datetime": "2027-01-01T00:00:00Z",
        "hs_end_datetime": "2027-01-31T23:59:59.999Z",
        "hs_group_correlation_uuid": "40499cb1-d8e7-495d-a1c7-07e3ed4b5468",
        "hs_goal_target_group_id": "1234567",
        "hs_fiscal_year_offset": "0",
        "hs_status": "pending",
        "hs_outcome": "pending",
        "hs_assignee_user_id": "123456789",
        "hs_user_ids_of_all_owners": "123456789",
        "hs_kpi_object_type_id": "0-3",
        "hs_kpi_property_name": "amount",
        "hs_kpi_metric_type": "SUM",
        "hs_kpi_unit_type": "currency",
        "hs_should_notify_on_kickoff": "true",
        "hs_should_notify_on_exceeded": "true",
        "hs_should_notify_on_achieved": "true",
        "hs_should_notify_on_missed": "true",
        "hs_should_notify_on_edit_updates": "false",
        "hs_should_notify_on_progress_updates": "false",
        "hubspot_owner_id": "987654321"
      }
    },
    {
      "properties": {
        "hs_goal_name": "Sales Quota 2027",
        "hs_milestone": "monthly",
        "hs_goal_type": "sales_quota",
        "hs_target_amount": "1500.00",
        "hs_start_datetime": "2027-02-01T00:00:00Z",
        "hs_end_datetime": "2027-02-28T23:59:59.999Z",
        "hs_group_correlation_uuid": "40499cb1-d8e7-495d-a1c7-07e3ed4b5468",
        "hs_goal_target_group_id": "1234567",
        "hs_fiscal_year_offset": "0",
        "hs_status": "pending",
        "hs_outcome": "pending",
        "hs_assignee_user_id": "123456789",
        "hs_user_ids_of_all_owners": "123456789",
        "hs_kpi_object_type_id": "0-3",
        "hs_kpi_property_name": "amount",
        "hs_kpi_metric_type": "SUM",
        "hs_kpi_unit_type": "currency",
        "hs_should_notify_on_kickoff": "true",
        "hs_should_notify_on_exceeded": "true",
        "hs_should_notify_on_achieved": "true",
        "hs_should_notify_on_missed": "true",
        "hs_should_notify_on_edit_updates": "false",
        "hs_should_notify_on_progress_updates": "false",
        "hubspot_owner_id": "987654321"
      }
    }
  ]
}

Retrieve goals

To retrieve goals, make a request in one of the following ways:

Retrieve a single target: GET /crm/objects/2026-03/goal_targets/{goalTargetId}/
Retrieve all targets: GET /crm/objects/2026-03/goal_targets
Search for targets: POST /crm/objects/2026-03/goal_targets/search

To retrieve goals that meet a specific set of criteria (filtering), you can make a POST request to the search endpoint and include filters in the request body. Learn more about searching the CRM. For example, to retrieve a goal with an ID of 44027423340, the request URL would be the following: https://api.hubapi.com/crm/objects/2026-03/goal_targets/44027423340/ The response will include a few default properties, including the create date, last modified date.

{
  "id": "87504620389",
  "properties": {
    "hs_createdate": "2021-11-30T22:18:49.923Z",
    "hs_lastmodifieddate": "2023-12-11T19:21:32.851Z",
    "hs_object_id": "87504620389"
  },
  "createdAt": "2021-11-30T22:18:49.923Z",
  "updatedAt": "2023-12-11T19:21:32.851Z",
  "archived": false
}

To return specific properties, include a properties query parameter in the request URL along with comma-separated property names. Learn more about goal properties below. For example, making a GET request to the following URL would result in the response below: crm/objects/2026-03/goal_targets/{goalTargetId}?properties=hs_goal_name,hs_target_amount

{
  "id": "87504620389",
  "properties": {
    "hs_createdate": "2021-11-30T22:18:49.923Z",
    "hs_lastmodifieddate": "2023-12-11T19:21:32.851Z",
    "hs_object_id": "87504620389"
  },
  "createdAt": "2021-11-30T22:18:49.923Z",
  "updatedAt": "2023-12-11T19:21:32.851Z",
  "archived": false
}

Create goals

To create goals, make a POST request to /crm/objects/2026-03/goal_targets/batch/create. To ensure these objects appear as a single goal in the UI, your batch request must adhere to specific architectural constraints:

Shared Identifiers: Every target object in the batch must share the same hs_group_correlation_uuid and hs_goal_target_group_id. This links them into a “Goal Family”.
Sequential Dates: You must increment the hs_start_datetime and hs_end_datetime for each object. For monthly goals, start dates must be the first millisecond of the month, and end dates must be the last millisecond of the month.
Milestone Accuracy: The number of objects must match the hs_milestone frequency (e.g., creating 12 objects for a “monthly” milestone).

This example shows the creation of the first two months of an annual sales quota goal. Note that the UUIDs remain constant while the dates increment. /crm/objects/2026-03/goal_targets/batch/create

{
  "inputs": [
    {
      "properties": {
        "hs_goal_name": "Sales Quota 2027",
        "hs_milestone": "monthly",
        "hs_goal_type": "sales_quota",
        "hs_target_amount": "1200.00",
        "hs_start_datetime": "2027-01-01T00:00:00Z",
        "hs_end_datetime": "2027-01-31T23:59:59.999Z",
        "hs_group_correlation_uuid": "40499cb1-d8e7-495d-a1c7-07e3ed4b5468",
        "hs_goal_target_group_id": "1234567"
      }
    },
    {
      "properties": {
        "hs_goal_name": "Sales Quota 2027",
        "hs_milestone": "monthly",
        "hs_goal_type": "sales_quota",
        "hs_target_amount": "1200.00",
        "hs_start_datetime": "2027-02-01T00:00:00Z",
        "hs_end_datetime": "2027-02-28T23:59:59.999Z",
        "hs_group_correlation_uuid": "40499cb1-d8e7-495d-a1c7-07e3ed4b5468",
        "hs_goal_target_group_id": "1234567"
      }
    }
  ]
}

Update goals

To update goals, make a request in one of the following ways:

Update a single target: PATCH /crm/objects/2026-03/goal_targets/{goalTargetId}
Batch update multiple targets: POST /crm/objects/2026-03/goal_targets/batch/update

Because a “Goal” consists of multiple independent objects (e.g., 12 monthly targets), you must choose the correct update method to avoid breaking the goal structure in the UI.

When to use Single Update (PATCH): Use this when changing data specific to one time slice.
- Example: Changing the hs_target_amount for just the month of October.
- Example: Manually overriding the hs_kpi_value for a specific month.
When to use Batch Update (POST): Use this when changing properties that define the Goal Family. If you change these on one object but not the others, the goal may disappear from the UI or appear as duplicates.
- Example: Renaming the goal (hs_goal_name). You must update all 12 targets.
- Example: Changing the pipeline (hs_pipeline_ids). You must update all 12 targets.

This example shows updates to the target amount for a specific month and triggers a notification to the user. PATCH /crm/objects/2026-03/goal_targets/{goalTargetId}

{
  "properties": {
    "hs_target_amount": "5500.00",
    "hs_should_notify_on_edit_updates": "true"
  }
}

Merge goals

To merge two goal records, make a POST request to /crm/objects/2026-03/goal_targets/merge. The remaining record combines activities, associations, and most property values from both records. For example, merge duplicate goals to preserve historical context and consolidate their activity timelines. Learn more about what happens when you merge HubSpot records. Include the following in your request body:

Field	Description
`objectIdToMerge`	The record ID to merge with the primary record.
`primaryObjectId`	The record ID of the primary record, which is the record that will remain after the merge.

For example, to merge the record 45678 into the record 12345, your request would look like:

{
  "objectIdToMerge": "45678",
  "primaryObjectId": "12345"
}

In a successful merge response, the id is the record ID of the merged record.

Please note: if an account is enrolled in the Primary ID Preservation for Merged Records public beta, the primary (i.e., the remaining record after a merge) record’s Record ID value (primaryObjectId) is preserved instead of generating a new one. Once enrolled, this behavior applies to all merges, including in HubSpot and all versions of the API.

Delete goals

To delete goals, make a request in one of the following ways:

Delete a single target: DELETE /crm/objects/2026-03/goal_targets/{goalTargetId}
Batch delete multiple targets: POST /crm/objects/2026-03/goal_targets/batch/archive

Because a standard goal consists of multiple distinct objects (e.g., 12 monthly targets), you must understand the scope of your deletion request.

Deleting a Single Target (DELETE): If you use the DELETE endpoint on a single ID, you are removing only that specific slice of time.
- Example: If you delete the target for “January,” the goal will still exist in the UI for February through December. The goal family remains active, but the start date or total target amount may calculate incorrectly in reports.
Deleting a Goal Family (POST): To completely remove a goal (e.g., “2025 Revenue Quota”) from the system, you must delete every target object associated with that goal’s hs_group_correlation_uuid.
- Example: You must first query the goal targets to retrieve all IDs associated with the Goal Family, and then use the batch archive endpoint to delete them all simultaneously.

This example shows the deletion of an entire quarterly goal. You must include the IDs for all four quarters in the batch archive request. POST /crm/objects/2026-03/goal_targets/batch/archive

{
  "inputs": [
    {"id": "11111"},
    {"id": "22222"},
    {"id": "33333"},
    {"id": "44444"}
  ]
}

Goals properties

When making a GET request to the Goals API, you can also request specific goal properties. For example, if you wanted to include properties such as hs_goal_name, hs_target_amount, hs_start_datetime, hs_end_datetime, and hs_created_by_user_id, the request URL may resemble the following:

https://api.hubapi.com/crm/objects/2026-03/goal_targets/44027423340?properties=hs_goal_name,hs_target_amount,hs_start_datetime,hs_end_datetime,hs_created_by_user_id

The response may look similar to the JSON excerpt below:

{
  "id": "44027423340",
  "properties": {
    "hs_created_by_user_id": "885536",
    "hs_createdate": "2023-02-15T15:53:07.080Z",
    "hs_end_datetime": "2024-01-01T00:00:00Z",
    "hs_goal_name": "Revenue Goal 2023",
    "hs_lastmodifieddate": "2023-02-16T10:02:21.131Z",
    "hs_object_id": "44027423340",
    "hs_start_datetime": "2023-12-01T00:00:00Z",
    "hs_target_amount": "2000.00"
  },
  "createdAt": "2023-02-15T15:53:07.080Z",
  "updatedAt": "2023-02-16T10:02:21.131Z",
  "archived": false
}

See all available properties and their descriptions in the Goal object definition page.

Create campaign goals

Create campaign goals by associating goals with existing campaigns, either when creating the campaign or by updating it after creation. You can create goals for campaign influence, website traffic, revenue, deal count, deal amount, and contact lifecycle metrics.

A goal must be associated with a campaign to count toward that campaign’s performance. If you create a goal without an association, you can associate it with a campaign later. Until the association exists, the goal won’t be linked to a campaign or counted toward its performance.

Associate a goal with a campaign

To associate a goal with a campaign, include an associations array alongside the properties object. The association uses the HubSpot-defined association type 809 for goal-to-campaign associations. In the following example, to.id is the campaign record ID:

"associations": [
  {
    "to": {
      "id": 421448680258
    },
    "types": [
      {
        "associationCategory": "HUBSPOT_DEFINED",
        "associationTypeId": 809
      }
    ]
  }
]

Including the association when you create the goal links the goal to the campaign in a single request. If you omit the association, the goal is created without a campaign association. You must add the association in a separate request before the goal can count toward campaign performance.

Properties common to campaign goal types

These properties appear in every campaign-goal request:

Property	Description
`hs_goal_type`	The campaign goal type. This property determines which additional properties are required.
`hs_goal_name`	The display name of the goal.
`hs_goal_target_group_id`	The ID of the goal target group. Generate and manage this ID. Use the same value to group related goal targets.
`hs_group_correlation_uuid`	A UUID that correlates goals in the same group or creation batch. Generate a valid UUID and reuse it for the goals you want to correlate.
`hs_milestone`	The goal milestone or cadence, such as `custom` or `monthly`.
`hs_start_datetime` and `hs_end_datetime`	The goal timeframe. The examples use epoch milliseconds. ISO 8601 strings, such as `2026-01-01T00:00:00Z`, are also accepted.
`hs_target_amount`	The target value used to measure the goal.
`hs_assignee_user_id`	The ID of the user assigned to the goal.
`hs_kpi_unit_type`	The unit used to measure the goal: `number` or `currency`.
`hs_kpi_tracking_method`	Whether a higher or lower value is better: `HIGHER_IS_BETTER` or `LOWER_IS_BETTER`.
`hs_status` and `hs_outcome`	The lifecycle status and outcome of the goal. These are typically set to `pending` when the goal is created.
`hs_should_recalculate`	Whether HubSpot should recalculate the goal’s progress.
`hs_should_notify_on_` / `hs__notification_frequency`	The goal’s notification preferences.

Type-specific properties

Goal type	`hs_kpi_unit_type`	Tracking	Additional required properties
`marketing_campaign_influence_contacts`	`number`	`HIGHER_IS_BETTER`	—
`website_traffic`	`number`	`HIGHER_IS_BETTER`	—
`campaign_revenue`	`currency`	`HIGHER_IS_BETTER`	`hs_goal_target_currency_code`, `hs_kpi_object_type_id`, `hs_kpi_property_name`, `hs_kpi_metric_type`, `hs_kpi_time_period_property`, `hs_kpi_time_period_property_type`, and `hs_kpi_attribution_model`
`campaign_deal_count`	`number`	`HIGHER_IS_BETTER`	`hs_kpi_object_type_id`, `hs_kpi_property_name`, `hs_kpi_metric_type`, `hs_kpi_time_period_property`, `hs_kpi_time_period_property_type`
`campaign_deal_amount`	`currency`	`HIGHER_IS_BETTER`	`hs_goal_target_currency_code`, `hs_kpi_object_type_id`, `hs_kpi_property_name`, `hs_kpi_metric_type`, `hs_kpi_time_period_property`, and `hs_kpi_time_period_property_type`
`campaign_cost_per_contact_lifecycle`	`currency`	`LOWER_IS_BETTER`	`hs_contact_lifecycle_stage`
`campaign_number_of_contact_lifecycle`	`number`	`HIGHER_IS_BETTER`	`hs_assignee_type`, `hs_contact_lifecycle_stage`

Campaign goal types

1. Marketing campaign influence goal

This goal tracks the number of contacts influenced by a campaign. It doesn’t require any properties beyond the common properties. Use number for hs_kpi_unit_type and HIGHER_IS_BETTER for hs_kpi_tracking_method.

{
  "inputs": [
    {
      "properties": {
        "hs_goal_type": "marketing_campaign_influence_contacts",
        "hs_goal_name": "My influence contacts goal",
        "hs_goal_target_group_id": "84296",
        "hs_group_correlation_uuid": "f6c7d8e9-eabc-4234-dfb0-234567890123",
        "hs_milestone": "custom",
        "hs_start_datetime": "1767225600000",
        "hs_end_datetime": "1787184000000",
        "hs_target_amount": "50000.00",
        "hs_assignee_user_id": "886538326",
        "hs_kpi_unit_type": "number",
        "hs_kpi_tracking_method": "HIGHER_IS_BETTER",
        "hs_status": "pending",
        "hs_outcome": "pending",
        "hs_should_recalculate": "true",
        "hs_should_notify_on_kickoff": "false",
        "hs_should_notify_on_exceeded": "false",
        "hs_should_notify_on_achieved": "false",
        "hs_should_notify_on_missed": "false",
        "hs_should_notify_on_edit_updates": "false",
        "hs_should_notify_on_progress_updates": "false",
        "hs_edit_updates_notification_frequency": "weekly",
        "hs_progress_updates_notification_frequency": "weekly"
      },
      "associations": [
        {
          "to": {
            "id": 421448680258
          },
          "types": [
            {
              "associationCategory": "HUBSPOT_DEFINED",
              "associationTypeId": 809
            }
          ]
        }
      ]
    }
  ]
}

2. Website traffic goal

This goal tracks visits or sessions driven by a campaign. It doesn’t require any properties beyond the common properties. Use number for hs_kpi_unit_type and HIGHER_IS_BETTER for hs_kpi_tracking_method.

{
  "inputs": [
    {
      "properties": {
        "hs_goal_type": "website_traffic",
        "hs_goal_name": "My website traffic goal",
        "hs_goal_target_group_id": "84297",
        "hs_group_correlation_uuid": "a7d8e9f0-fbcd-4345-e0c1-345678901234",
        "hs_milestone": "custom",
        "hs_start_datetime": "1767225600000",
        "hs_end_datetime": "1787184000000",
        "hs_target_amount": "10000.00",
        "hs_assignee_user_id": "886538326",
        "hs_kpi_unit_type": "number",
        "hs_kpi_tracking_method": "HIGHER_IS_BETTER",
        "hs_status": "pending",
        "hs_outcome": "pending",
        "hs_should_recalculate": "true",
        "hs_should_notify_on_kickoff": "false",
        "hs_should_notify_on_exceeded": "false",
        "hs_should_notify_on_achieved": "false",
        "hs_should_notify_on_missed": "false",
        "hs_should_notify_on_edit_updates": "false",
        "hs_should_notify_on_progress_updates": "false",
        "hs_edit_updates_notification_frequency": "weekly",
        "hs_progress_updates_notification_frequency": "weekly"
      },
      "associations": [
        {
          "to": {
            "id": 421449118569
          },
          "types": [
            {
              "associationCategory": "HUBSPOT_DEFINED",
              "associationTypeId": 809
            }
          ]
        }
      ]
    }
  ]
}

3. Campaign revenue goal

This goal tracks revenue attributed to a campaign. Because it is a KPI-based goal, it requires properties that define what is measured and how it is calculated. The following properties are required:

hs_goal_target_currency_code: the currency used for the target, such as USD.
hs_kpi_object_type_id: the object measured by the KPI, such as 0-20.
hs_kpi_property_name: the property aggregated, such as hs_last_touch_amount.
hs_kpi_metric_type: the aggregation method, such as SUM.
hs_kpi_time_period_property and hs_kpi_time_period_property_type: the date property and property type that define the KPI timeframe, such as hs_createdate and datetime.
hs_kpi_attribution_model: the attribution model, such as hs_first_touch_amount.

{
  "inputs": [
    {
      "properties": {
        "hs_goal_target_currency_code": "USD",
        "hs_goal_type": "campaign_revenue",
        "hs_goal_name": "My campaign revenue goal",
        "hs_goal_target_group_id": "84295",
        "hs_group_correlation_uuid": "e5b6c7d8-d9fa-4123-ceaf-123456789012",
        "hs_milestone": "custom",
        "hs_start_datetime": "1767225600000",
        "hs_end_datetime": "1787184000000",
        "hs_target_amount": "500000.00",
        "hs_assignee_user_id": "886538326",
        "hs_kpi_object_type_id": "0-20",
        "hs_kpi_property_name": "hs_last_touch_amount",
        "hs_kpi_metric_type": "SUM",
        "hs_kpi_time_period_property": "hs_createdate",
        "hs_kpi_time_period_property_type": "datetime",
        "hs_kpi_unit_type": "currency",
        "hs_kpi_tracking_method": "HIGHER_IS_BETTER",
        "hs_kpi_attribution_model": "hs_first_touch_amount",
        "hs_status": "pending",
        "hs_outcome": "pending",
        "hs_should_recalculate": "true",
        "hs_should_notify_on_kickoff": "false",
        "hs_should_notify_on_exceeded": "false",
        "hs_should_notify_on_achieved": "false",
        "hs_should_notify_on_missed": "false",
        "hs_should_notify_on_edit_updates": "false",
        "hs_should_notify_on_progress_updates": "false",
        "hs_edit_updates_notification_frequency": "weekly",
        "hs_progress_updates_notification_frequency": "weekly"
      },
      "associations": [
        {
          "to": {
            "id": 421448696231
          },
          "types": [
            {
              "associationCategory": "HUBSPOT_DEFINED",
              "associationTypeId": 809
            }
          ]
        }
      ]
    }
  ]
}

4. Campaign deal count goal

This goal tracks the number of deals attributed to a campaign. The following properties are required:

hs_kpi_object_type_id: the object measured, such as 0-20.
hs_kpi_property_name: the property counted, such as hs_object_id.
hs_kpi_metric_type: the aggregation method, such as COUNT.
hs_kpi_time_period_property and hs_kpi_time_period_property_type: the date property and property type that define the KPI timeframe, such as hs_createdate and datetime.

{
  "inputs": [
    {
      "properties": {
        "hs_goal_type": "campaign_deal_count",
        "hs_goal_name": "My deal count goal",
        "hs_goal_target_group_id": "84294",
        "hs_group_correlation_uuid": "d4a5b6c7-c8e9-4012-bdfe-012345678901",
        "hs_milestone": "custom",
        "hs_start_datetime": "1767225600000",
        "hs_end_datetime": "1787184000000",
        "hs_target_amount": "50.00",
        "hs_assignee_user_id": "886538326",
        "hs_kpi_object_type_id": "0-20",
        "hs_kpi_property_name": "hs_object_id",
        "hs_kpi_metric_type": "COUNT",
        "hs_kpi_time_period_property": "hs_createdate",
        "hs_kpi_time_period_property_type": "datetime",
        "hs_kpi_unit_type": "number",
        "hs_kpi_tracking_method": "HIGHER_IS_BETTER",
        "hs_status": "pending",
        "hs_outcome": "pending",
        "hs_should_recalculate": "true",
        "hs_should_notify_on_kickoff": "false",
        "hs_should_notify_on_exceeded": "false",
        "hs_should_notify_on_achieved": "false",
        "hs_should_notify_on_missed": "false",
        "hs_should_notify_on_edit_updates": "false",
        "hs_should_notify_on_progress_updates": "false",
        "hs_edit_updates_notification_frequency": "weekly",
        "hs_progress_updates_notification_frequency": "weekly"
      },
      "associations": [
        {
          "to": {
            "id": 421448986934
          },
          "types": [
            {
              "associationCategory": "HUBSPOT_DEFINED",
              "associationTypeId": 809
            }
          ]
        }
      ]
    }
  ]
}

5. Campaign deal amount goal

This goal tracks the total deal amount attributed to a campaign. The following properties are required:

hs_goal_target_currency_code: the currency used for the target, such as USD.
hs_kpi_object_type_id: the object measured, such as 0-20.
hs_kpi_property_name: the property summed, such as hs_deal_amount.
hs_kpi_metric_type: the aggregation method, such as SUM.
hs_kpi_time_period_property and hs_kpi_time_period_property_type: the date property and property type that define the KPI timeframe, such as hs_deal_close_date and datetime.

{
  "inputs": [
    {
      "properties": {
        "hs_goal_type": "campaign_deal_amount",
        "hs_goal_name": "My deal amount goal",
        "hs_goal_target_group_id": "84293",
        "hs_group_correlation_uuid": "c3f4e5a6-b7d8-4901-acde-f01234567890",
        "hs_milestone": "custom",
        "hs_start_datetime": "1767225600000",
        "hs_end_datetime": "1787184000000",
        "hs_target_amount": "100000.00",
        "hs_assignee_user_id": "886538326",
        "hs_kpi_object_type_id": "0-20",
        "hs_kpi_property_name": "hs_deal_amount",
        "hs_kpi_metric_type": "SUM",
        "hs_kpi_time_period_property": "hs_deal_close_date",
        "hs_kpi_time_period_property_type": "datetime",
        "hs_kpi_unit_type": "currency",
        "hs_goal_target_currency_code": "USD",
        "hs_kpi_tracking_method": "HIGHER_IS_BETTER",
        "hs_status": "pending",
        "hs_outcome": "pending",
        "hs_should_recalculate": "true",
        "hs_should_notify_on_kickoff": "false",
        "hs_should_notify_on_exceeded": "false",
        "hs_should_notify_on_achieved": "false",
        "hs_should_notify_on_missed": "false",
        "hs_should_notify_on_edit_updates": "false",
        "hs_should_notify_on_progress_updates": "false",
        "hs_edit_updates_notification_frequency": "weekly",
        "hs_progress_updates_notification_frequency": "weekly"
      },
      "associations": [
        {
          "to": {
            "id": 421447858819
          },
          "types": [
            {
              "associationCategory": "HUBSPOT_DEFINED",
              "associationTypeId": 809
            }
          ]
        }
      ]
    }
  ]
}

6. Campaign cost per contact goal

This goal tracks the cost per contact reaching a specific lifecycle stage. Because a lower cost is better, set hs_kpi_tracking_method to LOWER_IS_BETTER. The following property is required:

hs_contact_lifecycle_stage: the lifecycle stage measured, such as lead.

{
  "inputs": [
    {
      "properties": {
        "hs_goal_type": "campaign_cost_per_contact_lifecycle",
        "hs_goal_name": "My cost per contact goal",
        "hs_goal_target_group_id": "84292",
        "hs_group_correlation_uuid": "b2e3d4f5-a6c7-4890-9bcd-ef0123456789",
        "hs_milestone": "custom",
        "hs_start_datetime": "1767225600000",
        "hs_end_datetime": "1787184000000",
        "hs_target_amount": "25.00",
        "hs_assignee_user_id": "886538326",
        "hs_contact_lifecycle_stage": "lead",
        "hs_kpi_unit_type": "currency",
        "hs_kpi_tracking_method": "LOWER_IS_BETTER",
        "hs_status": "pending",
        "hs_outcome": "pending",
        "hs_should_recalculate": "true",
        "hs_should_notify_on_kickoff": "false",
        "hs_should_notify_on_exceeded": "false",
        "hs_should_notify_on_achieved": "false",
        "hs_should_notify_on_missed": "false",
        "hs_should_notify_on_edit_updates": "false",
        "hs_should_notify_on_progress_updates": "false",
        "hs_edit_updates_notification_frequency": "weekly",
        "hs_progress_updates_notification_frequency": "weekly"
      },
      "associations": [
        {
          "to": {
            "id": 421445835341
          },
          "types": [
            {
              "associationCategory": "HUBSPOT_DEFINED",
              "associationTypeId": 809
            }
          ]
        }
      ]
    }
  ]
}

7. Campaign number of contacts goal

This goal tracks the number of contacts reaching a specific lifecycle stage. The following properties are required:

hs_assignee_type: the assignee type, such as users.
hs_contact_lifecycle_stage: the lifecycle stage measured, such as lead.

{
  "inputs": [
    {
      "properties": {
        "hs_goal_type": "campaign_number_of_contact_lifecycle",
        "hs_goal_name": "My contact lifecycle goal",
        "hs_goal_target_group_id": "84291",
        "hs_group_correlation_uuid": "a1f2c3d4-e5b6-4789-8abc-def012345678",
        "hs_milestone": "custom",
        "hs_start_datetime": "1767225600000",
        "hs_end_datetime": "1787184000000",
        "hs_target_amount": "500.00",
        "hs_assignee_type": "users",
        "hs_assignee_user_id": "886538326",
        "hs_contact_lifecycle_stage": "lead",
        "hs_kpi_unit_type": "number",
        "hs_kpi_tracking_method": "HIGHER_IS_BETTER",
        "hs_status": "pending",
        "hs_outcome": "pending",
        "hs_should_recalculate": "true",
        "hs_should_notify_on_kickoff": "false",
        "hs_should_notify_on_exceeded": "false",
        "hs_should_notify_on_achieved": "false",
        "hs_should_notify_on_missed": "false",
        "hs_should_notify_on_edit_updates": "false",
        "hs_should_notify_on_progress_updates": "false",
        "hs_edit_updates_notification_frequency": "weekly",
        "hs_progress_updates_notification_frequency": "weekly"
      },
      "associations": [
        {
          "to": {
            "id": 421440625030
          },
          "types": [
            {
              "associationCategory": "HUBSPOT_DEFINED",
              "associationTypeId": 809
            }
          ]
        }
      ]
    }
  ]
}

​Understanding goal architecture

​The goal hierarchy

​Goal family (the “goal”)

​Goal Target Group (The Schedule)

​Goal target (the time slice)

​Example: Structure of a Monthly Goal

​Retrieve goals

​Create goals

​Update goals

​Merge goals

​Delete goals

​Goals properties

​Create campaign goals

​Associate a goal with a campaign

​Properties common to campaign goal types

​Type-specific properties

​Campaign goal types

​1. Marketing campaign influence goal

​2. Website traffic goal

​3. Campaign revenue goal

​4. Campaign deal count goal

​5. Campaign deal amount goal

​6. Campaign cost per contact goal

​7. Campaign number of contacts goal

Understanding goal architecture

The goal hierarchy

Goal family (the “goal”)

Goal Target Group (The Schedule)

Goal target (the time slice)

Example: Structure of a Monthly Goal

Retrieve goals

Create goals

Update goals

Merge goals

Delete goals

Goals properties

Create campaign goals

Associate a goal with a campaign

Properties common to campaign goal types

Type-specific properties

Campaign goal types

1. Marketing campaign influence goal

2. Website traffic goal

3. Campaign revenue goal

4. Campaign deal count goal

5. Campaign deal amount goal

6. Campaign cost per contact goal

7. Campaign number of contacts goal