Worlds / Sales and crm

Pipedrive API

A local Pipedrive with deals, pipelines, stages, persons, organizations and activities. Test the agent that moves deals, schedules activities and marks deals won or lost with a reason.

Base path: /api/v1
Auth: API token or OAuth bearer token, the world key
Endpoints: 18
Status: Active today

This reference previews the surface the Pipedrive world serves in the closed beta. Paths mirror the public Pipedrive API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_PIPEDRIVE_URL`	This world's origin followed by `/api/v1`
`WORLDS_API_KEY`	The world key, accepted wherever Pipedrive expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · pipedrive

import pipedrive from "pipedrive";

const client = new pipedrive.ApiClient();
client.basePath = process.env.WORLDS_PIPEDRIVE_URL;
client.authentications.api_key.apiKey = process.env.WORLDS_API_KEY;

const deals = await new pipedrive.DealsApi(client).getDeals();

API reference

18 of 18

Deals

Sales opportunities moving through stages.

GET/api/v1/dealsGet all deals
POST/api/v1/dealsAdd a deal
GET/api/v1/deals/{id}Get a deal
PUT/api/v1/deals/{id}Update a deal
DELETE/api/v1/deals/{id}Delete a deal

Fields · 7

`id`	integer	Deal id
`title`	string	Deal title
`value`	number	Deal value
`currency`	string	Currency code
`stage_id`	integer	Pipeline stage
`status`	string	open, won, lost or deleted
`person_id`	integer	Linked person

Persons

Contacts you sell to.

GET/api/v1/personsGet all persons
POST/api/v1/personsAdd a person
GET/api/v1/persons/{id}Get a person
PUT/api/v1/persons/{id}Update a person

Fields · 5

`id`	integer	Person id
`name`	string	Full name
`email`	array	Email addresses
`phone`	array	Phone numbers
`org_id`	integer	Organization

Organizations

Companies you sell to.

GET/api/v1/organizationsGet all organizations
POST/api/v1/organizationsAdd an organization
GET/api/v1/organizations/{id}Get an organization

Fields · 4

`id`	integer	Organization id
`name`	string	Name
`address`	string	Address
`owner_id`	integer	Owner user

Activities

Calls, meetings and tasks.

GET/api/v1/activitiesGet all activities
POST/api/v1/activitiesAdd an activity
PUT/api/v1/activities/{id}Update an activity

Fields · 6

`id`	integer	Activity id
`subject`	string	Subject
`type`	string	call, meeting, task and so on
`due_date`	string	Due date
`done`	boolean	Whether it is completed
`deal_id`	integer	Linked deal

Notes

Free-text notes on deals and people.

GET/api/v1/notesGet all notes
POST/api/v1/notesAdd a note
PUT/api/v1/notes/{id}Update a note

Fields · 4

`id`	integer	Note id
`content`	string	Note text
`deal_id`	integer	Linked deal
`person_id`	integer	Linked person

Test workflow

Prepare. Select the Pipedrive setup for your workflow and review its starting records, including deals, persons, organizations.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Deal #211 in Demo Scheduled with a demo activity
Deal #215 lost with lost_reason Timing
Deal #214 still open in Proposal Made
Deal #214 has a call activity in two weeks
No open deal without a next activity

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Pipedrive
version: 2
connector: pipedrive
seed: pipedrive-starter
mode: isolated
policy: >
  Update deals from today's call notes. Moss & Co agreed to a demo. Lee
  Holdings is lost on Timing. Ortiz Labs asked for two weeks, keep it open and
  schedule a call. Every open deal needs a next activity.
tasks:
  - id: move-a-deal-to-the-next-stage-after-a-call
    prompt: Move a deal to the next stage after a call
  - id: schedule-the-follow-up-activity-on-the-deal
    prompt: Schedule the follow up activity on the deal
  - id: mark-a-deal-lost-with-the-right-lost-reason
    prompt: Mark a deal lost with the right lost reason
expected:
  - "Deal #211 in Demo Scheduled with a demo activity"
  - "Deal #215 lost with lost_reason Timing"
  - "Deal #214 still open in Proposal Made"
  - "Deal #214 has a call activity in two weeks"
  - No open deal without a next activity
scenarios:
  - rate-limited
  - stage-not-found
  - deal-deleted

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`rate-limited`	429 once the token budget for the window is spent
`stage-not-found`	400 when the stage id belongs to another pipeline
`deal-deleted`	404 because a teammate deleted the deal
`token-revoked`	401 after the API token is regenerated

Starting data

Start each run from the same records and relationships. The overview below describes the Pipedrive starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
deals	30 open, won and lost in two pipelines
persons	50 linked to 15 organizations
activities	40 calls, meetings and tasks, some overdue
stages	Qualified, Contact Made, Demo Scheduled, Proposal Made, Negotiations Started
lost reasons	Price, Timing, Went with competitor, No budget

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Deals records

Deals

Sales opportunities moving through stages.

Field	Type	Meaning / relationship
`id`	integer	Deal id
`title`	string	Deal title
`value`	number	Deal value
`currency`	string	Currency code
`stage_id`	integer	Pipeline stage
`status`	string	open, won, lost or deleted
`person_id`	integer	Linked person

json · illustrative record shape

{
  "id": 1,
  "title": "<Deal title>",
  "value": 1,
  "currency": "<Currency code>",
  "stage_id": 1,
  "status": "<open, won, lost or deleted>"
}

See deals operations

Persons records

Persons

Contacts you sell to.

Field	Type	Meaning / relationship
`id`	integer	Person id
`name`	string	Full name
`email`	array	Email addresses
`phone`	array	Phone numbers
`org_id`	integer	Organization

json · illustrative record shape

{
  "id": 1,
  "name": "<Full name>",
  "email": [],
  "phone": [],
  "org_id": 1
}

See persons operations

Organizations records

Organizations

Companies you sell to.

Field	Type	Meaning / relationship
`id`	integer	Organization id
`name`	string	Name
`address`	string	Address
`owner_id`	integer	Owner user

json · illustrative record shape

{
  "id": 1,
  "name": "<Name>",
  "address": "<Address>",
  "owner_id": 1
}

See organizations operations

Activities records

Activities

Calls, meetings and tasks.

Field	Type	Meaning / relationship
`id`	integer	Activity id
`subject`	string	Subject
`type`	string	call, meeting, task and so on
`due_date`	string	Due date
`done`	boolean	Whether it is completed
`deal_id`	integer	Linked deal

json · illustrative record shape

{
  "id": 1,
  "subject": "<Subject>",
  "type": "<call, meeting, task and so on>",
  "due_date": "<Due date>",
  "done": false,
  "deal_id": 1
}

See activities operations

Notes records

Notes

Free-text notes on deals and people.

Field	Type	Meaning / relationship
`id`	integer	Note id
`content`	string	Note text
`deal_id`	integer	Linked deal
`person_id`	integer	Linked person

json · illustrative record shape

{
  "id": 1,
  "content": "<Note text>",
  "deal_id": 1,
  "person_id": 1
}

See notes operations

See the Pipedrive world in the catalog