Goals

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

Find goals

Copy link
Copy to clipboard
GET

/v1/goals/find

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.

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

Values

true

false

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

integer

The ID of the pipeline 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

integer

The ID of the activity type. Applicable to only activities_completed 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

Successful response containing payload in the data.goal object

Expand all
Copy code
    • true
    • { ... }

    Get result of a goal

    Copy link
    Copy to clipboard
    GET

    /v1/goals/{id}/results

    Gets the progress of a goal for the specified period.

    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 progress of a goal. Date in format of 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 progress of a goal. Date in format of YYYY-MM-DD. This date must be the same or before the goal duration end date.

    Format

    date

    Response
    200

    Successful response containing payload in the data.goal object

    Expand all
    Copy code
      • true
      • { ... }

      Add a new goal

      Copy link
      Copy to clipboard
      POST

      /v1/goals

      Adds a new goal. Along with adding a new goal, a report is created to track the progress of your 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 } }. 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. To track goal in all pipelines set pipeline_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

      Successful response containing payload in the data.goal object

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

        Update existing goal

        Copy link
        Copy to clipboard
        PUT

        /v1/goals/{id}

        Updates an existing goal.

        Path parameters

        id

        string

        required

        The ID of the goal to be updated

        Body parameters

        application/x-www-form-urlencoded

        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 } }. 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. To track goal in all pipelines set pipeline_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

        Successful response containing payload in the data.goal object

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

          Delete existing goal

          Copy link
          Copy to clipboard
          DELETE

          /v1/goals/{id}

          Marks a goal as deleted.

          Path parameters

          id

          string

          required

          The ID of the goal to be deleted

          Response
          200

          Successful response with id 'success' field only

          Expand all
          Copy code
            • true

          Subscribe to Pipedrive’s Developer Newsletter