## TL;DR
Pipedrive stages are numeric ids scoped to a pipeline, and the API rejects a stage that doesn't exist or belongs to a different pipeline than the deal's. The UI shows stage names; the API wants ids. Fetch the pipeline's stages, send the numeric id with its pipeline, and stop sending names.

## The query

```text
pipedrive api deal stage invalid
```

## Use this when

- Deal creates or updates fail on the stage field
- Stage names from the UI don't work in API calls
- Deals land in the wrong pipeline after creation


## Not for

- Pipedrive authentication errors
- Deal custom field validation errors
- Pipedrive webhook issues


## Steps

### 1. Fetch the pipeline's stages

Call the stages endpoint for the pipeline and read the numeric ids. Each stage belongs to one pipeline. Don't guess ids from the UI; the names and ids are different things.

Expected output: the pipeline's stages with names mapped to numeric ids.

### 2. Send stage_id with its pipeline

Set the deal's stage_id to the numeric id from step 1, and make sure the deal's pipeline_id matches the stage's pipeline. A stage from pipeline A on a deal in pipeline B fails.

Expected output: a deal create returning success in the intended stage.

### 3. Stop sending stage names

If your code maps names to ids with a hardcoded table, replace it with the fetched definitions. Renames break hardcoded maps; fetched definitions stay current.

Expected output: no hardcoded stage names in the integration.

### 4. Check for archived or deleted stages

A stage id from an old export may have been archived. Re-fetch and confirm every id you send is active in the current pipeline.

Expected output: every stored stage id resolving to an active stage.

## Variant phrasings

### pipedrive deal stage id api

Steps 1 and 2: fetch the ids, send the pair.

### pipedrive move deal to stage failed

Step 4's archive check for ids that used to work.

## Why it happens

Pipedrive's UI speaks stage names and its API speaks numeric ids, and the pipeline scoping is invisible in the UI. Teams hardcode what they see, it works until someone adds a pipeline or renames a stage, and then every deal write fails. The stages endpoint is the source of truth.

## Edge cases

- Multiple pipelines need separate stage maps. Don't share one map.
- Stage ids differ between Pipedrive accounts. Never copy ids across accounts.
- The default pipeline catches deals when the stage's pipeline is ambiguous. Be explicit.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_H0700o96rYZj_O32asdtfg