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

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

Title of the goal.

is_active

boolean

Whether goal is active or not.

Default

true

Values

true

false

assignee.id

integer

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

assignee.type

string

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

Values

person

company

team

expected_outcome.target

number

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

expected_outcome.tracking_metric

string

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

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

ID of the pipeline or null for all pipelines. If provided, everyone's goals will be returned.

type.params.stage_id

integer

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

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

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

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 progress of a goal for specified period.

    Path parameters

    id

    string

    required

    ID of the goal that the results are looked for.

    Query parameters

    period.start

    string

    required

    Start date of the period for which to find progress of a goal. Date in format of YYYY-MM-DD.

    Format

    date

    period.end

    string

    required

    End date of the period for which to find progress of a goal. 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
      • { ... }

      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/x-www-form-urlencoded

      title

      string

      Title of the goal.

      assignee

      object

      Who is this goal 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

      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

      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

      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

      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.

      Values

      weekly

      monthly

      quarterly

      yearly

      Response
      200

      Successful response containing payload in the data.goal object.

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

        Update existing goal

        Copy link
        Copy to clipboard
        PUT

        /v1/goals/{id}

        Updates existing goal.

        Path parameters

        id

        string

        required

        ID of the goal to be updated.

        Body parameters

        application/x-www-form-urlencoded

        title

        string

        Title of the goal.

        assignee

        object

        Who is this goal 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

        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

        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

        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

        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.

        Values

        weekly

        monthly

        quarterly

        yearly

        Response
        200

        Successful response containing payload in the data.goal object.

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

          Delete existing goal

          Copy link
          Copy to clipboard
          DELETE

          /v1/goals/{id}

          Marks goal as deleted.

          Path parameters

          id

          string

          required

          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