View Source ExPipedrive.Goals (ex_pipedrive v0.2.0)

API v1 client for Pipedrive goals.

Sales goals (company, team, or user) live only on /api/v1/goals; there is no /api/v2 equivalent. Every function here explicitly routes to api_version: :v1.

Pipedrive's goals API has no plain "get by id" endpoint — only find (list/2, with optional filters), create/2, update/3, delete/2, and get_result/4 (a goal's progress for a period) are supported.

Unlike most Pipedrive entities, goal ids are Pipedrive-generated hex strings (e.g. "5665cef556ddff22606fc8f6c0004807"), not integers.

:type, :assignee, :expected_outcome, and :duration are accepted (and decoded) as plain maps matching Pipedrive's nested JSON shape:

%{
  title: "Some example goal",
  assignee: %{"id" => 123_456, "type" => "company"},
  type: %{"name" => "deals_started", "params" => %{"pipeline_id" => [5, 2]}},
  expected_outcome: %{"target" => 100, "tracking_metric" => "quantity"},
  duration: %{"start" => "2019-11-01", "end" => "2020-10-30"},
  interval: "weekly"
}

Example

{:ok, goal} = ExPipedrive.Goals.create(client, attrs)
{:ok, [goal]} = ExPipedrive.Goals.list(client, title: "Some example goal")
{:ok, goal} = ExPipedrive.Goals.update(client, goal.id, %{title: "Renamed"})

{:ok, %{progress: 42, goal: goal}} =
  ExPipedrive.Goals.get_result(client, goal.id, ~D[2020-01-01], ~D[2020-01-31])

{:ok, :ok} = ExPipedrive.Goals.delete(client, goal.id)

Summary

Functions

create(client, attrs)

Creates a goal via POST /api/v1/goals.

delete(client, goal_id)

Marks a goal as deleted via DELETE /api/v1/goals/:id.

get_result(client, goal_id, period_start, period_end)

Gets a goal's progress for a period via GET /api/v1/goals/:id/results.

list(client, opts \\ [])

Finds goals via GET /api/v1/goals/find.

update(client, goal_id, attrs)

Updates a goal via PUT /api/v1/goals/:id.

Functions

create(client, attrs)

@spec create(Tesla.Client.t(), map()) ::
  {:ok, ExPipedrive.Goal.t()} | {:error, ExPipedrive.Error.t()}

Creates a goal via POST /api/v1/goals.

Pipedrive requires :type, :assignee, :expected_outcome, :duration, and :interval; :title is optional. Returns {:ok, %Goal{}}.

delete(client, goal_id)

@spec delete(Tesla.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ExPipedrive.Error.t()}

Marks a goal as deleted via DELETE /api/v1/goals/:id.

Returns {:ok, :ok}.

get_result(client, goal_id, period_start, period_end)

@spec get_result(
  Tesla.Client.t(),
  String.t(),
  Date.t() | String.t(),
  Date.t() | String.t()
) ::
  {:ok, %{progress: integer(), goal: ExPipedrive.Goal.t()}}
  | {:error, ExPipedrive.Error.t()}

Gets a goal's progress for a period via GET /api/v1/goals/:id/results.

period_start and period_end accept a Date or a "YYYY-MM-DD" string and must fall within the goal's own duration.

Returns {:ok, %{progress: integer(), goal: %Goal{}}}.

list(client, opts \\ [])

@spec list(
  Tesla.Client.t(),
  keyword()
) :: {:ok, [ExPipedrive.Goal.t()]} | {:error, ExPipedrive.Error.t()}

Finds goals via GET /api/v1/goals/find.

Accepts filter options matching Pipedrive's dot-notation search fields: :type_name, :title, :is_active (server defaults to true when omitted), :assignee_id, :assignee_type, :expected_outcome_target, :expected_outcome_tracking_metric, :expected_outcome_currency_id, :pipeline_id, :stage_id, :activity_type_id, :period_start, and :period_end (the latter two must be given together).

Returns {:ok, [%Goal{}]}.

update(client, goal_id, attrs)

@spec update(Tesla.Client.t(), String.t(), map()) ::
  {:ok, ExPipedrive.Goal.t()} | {:error, ExPipedrive.Error.t()}

Updates a goal via PUT /api/v1/goals/:id.

Accepts a map of any of :title, :assignee, :type, :expected_outcome, :duration, :interval. Returns {:ok, %Goal{}}.