Goals

Goals help your team meet your sales targets. There are three types of goals - company, team and user.

Find goals

Copy link

Returns data about goals based on criteria. For searching, append {searchField}={searchValue} to the URL, where searchField can be any one of the lowest-level fields in dot-notation (e.g. type.params.pipeline_id; title). searchValue should be the value you are looking for on that field. Additionally, is_active=<true|false> can be provided to search for only active/inactive goals. When providing period.start, period.end must also be provided and vice versa.

API v1
Request
GET

/v1/goals/find

Query parameters

type.name

string

The type of the goal. If provided, everyone's goals will be returned.

Values

deals_won

deals_progressed

activities_completed

activities_added

deals_started

title

string

The title of the goal

is_active

boolean

Whether the goal is active or not

Default

true

assignee.id

integer

The ID of the user who's goal to fetch. When omitted, only your goals will be returned.

assignee.type

string

The type of the goal's assignee. If provided, everyone's goals will be returned.

Values

person

company

team

expected_outcome.target

number

The numeric value of the outcome. If provided, everyone's goals will be returned.

expected_outcome.tracking_metric

string

The tracking metric of the expected outcome of the goal. If provided, everyone's goals will be returned.

Values

quantity

sum

expected_outcome.currency_id

integer

The numeric ID of the goal's currency. Only applicable to goals with expected_outcome.tracking_metric with value sum. If provided, everyone's goals will be returned.

type.params.pipeline_id

array

An array of pipeline IDs or null for all pipelines. If provided, everyone's goals will be returned.

type.params.stage_id

integer

The ID of the stage. Applicable to only deals_progressed type of goals. If provided, everyone's goals will be returned.

type.params.activity_type_id

array

An array of IDs or null for all activity types. Only applicable for activities_completed and/or activities_added types of goals. If provided, everyone's goals will be returned.

period.start

string

The start date of the period for which to find goals. Date in format of YYYY-MM-DD. When period.start is provided, period.end must be provided too.

Format

date

period.end

string

The end date of the period for which to find goals. Date in format of YYYY-MM-DD.

Format

date

Response
200

OK

Expand all
Copy code
    • true
    • 20000
    • "OK"
    • "statistics-goals-api"
    • { ... }

    Get result of a goal

    Copy link

    Gets the progress of a goal for the specified period.

    API v1
    Request
    GET

    /v1/goals/{id}/results

    Path parameters

    id

    string

    required

    The ID of the goal that the results are looked for

    Query parameters

    period.start

    string

    required

    The start date of the period for which to find the goal's progress. Format: YYYY-MM-DD. This date must be the same or after the goal duration start date.

    Format

    date

    period.end

    string

    required

    The end date of the period for which to find the goal's progress. Format: YYYY-MM-DD. This date must be the same or before the goal duration end date.

    Format

    date

    Response
    200

    OK

    Expand all
    Copy code
      • true
      • 20000
      • "OK"
      • "statistics-goals-api"
      • { ... }

      Add a new goal

      Copy link

      Adds a new goal. Along with adding a new goal, a report is created to track the progress of your goal.

      API v1
      Request
      POST

      /v1/goals

      Body parameters

      application/json

      title

      string

      The title of the goal

      assignee

      object

      required

      Who this goal is assigned to. It requires the following JSON structure: { "id": "1", "type": "person" }. type can be either person, company or team. ID of the assignee person, company or team.

      type

      object

      required

      The type of the goal. It requires the following JSON structure: { "name": "deals_started", "params": { "pipeline_id": [1, 2], "activity_type_id": [9] } }. Type can be one of: deals_won, deals_progressed, activities_completed, activities_added, deals_started or revenue_forecast. params can include pipeline_id, stage_id or activity_type_id. stage_id is related to only deals_progressed type of goals and activity_type_id to activities_completed or activities_added types of goals. The pipeline_id and activity_type_id need to be given as an array of integers. To track the goal in all pipelines, set pipeline_id as null and similarly, to track the goal for all activities, set activity_type_id as null.”

      expected_outcome

      object

      required

      The expected outcome of the goal. Expected outcome can be tracked either by quantity or by sum. It requires the following JSON structure: { "target": "50", "tracking_metric": "quantity" } or { "target": "50", "tracking_metric": "sum", "currency_id": 1 }. currency_id should only be added to sum type of goals.

      duration

      object

      required

      The date when the goal starts and ends. It requires the following JSON structure: { "start": "2019-01-01", "end": "2022-12-31" }. Date in format of YYYY-MM-DD. "end" can be set to null for an infinite, open-ended goal.

      interval

      string

      required

      The interval of the goal

      Values

      weekly

      monthly

      quarterly

      yearly

      Response
      200

      OK

      Expand all
      Copy code
        • true
        • 20000
        • "OK"
        • "statistics-goals-api"
        • { ... }

        Update existing goal

        Copy link

        Updates an existing goal.

        API v1
        Request
        PUT

        /v1/goals/{id}

        Path parameters

        id

        string

        required

        The ID of the goal

        Body parameters

        application/json

        title

        string

        The title of the goal

        assignee

        object

        Who this goal is assigned to. It requires the following JSON structure: { "id": "1", "type": "person" }. type can be either person, company or team. ID of the assignee person, company or team.

        type

        object

        The type of the goal. It requires the following JSON structure: { "name": "deals_started", "params": { "pipeline_id": [1, 2], "activity_type_id": [9] } }. Type can be one of: deals_won, deals_progressed, activities_completed, activities_added, deals_started or revenue_forecast. params can include pipeline_id, stage_id or activity_type_id. stage_id is related to only deals_progressed type of goals and activity_type_id to activities_completed or activities_added types of goals. The pipeline_id and activity_type_id need to be given as an array of integers. To track the goal in all pipelines, set pipeline_id as null and similarly, to track the goal for all activities, set activity_type_id as null.”

        expected_outcome

        object

        The expected outcome of the goal. Expected outcome can be tracked either by quantity or by sum. It requires the following JSON structure: { "target": "50", "tracking_metric": "quantity" } or { "target": "50", "tracking_metric": "sum", "currency_id": 1 }. currency_id should only be added to sum type of goals.

        duration

        object

        The date when the goal starts and ends. It requires the following JSON structure: { "start": "2019-01-01", "end": "2022-12-31" }. Date in format of YYYY-MM-DD. "end" can be set to null for an infinite, open-ended goal.

        interval

        string

        The interval of the goal

        Values

        weekly

        monthly

        quarterly

        yearly

        Response
        200

        OK

        Expand all
        Copy code
          • true
          • 20000
          • "OK"
          • "statistics-goals-api"
          • { ... }

          Delete existing goal

          Copy link

          Marks a goal as deleted.

          API v1
          Request
          DELETE

          /v1/goals/{id}

          Path parameters

          id

          string

          required

          The ID of the goal

          Response
          200

          OK

          Expand all
          Copy code
            • true
            • 20000
            • "OK"
            • "statistics-goals-api"

          Subscribe to Pipedrive’s Developer Newsletter