Hey @dombarnes
Welcome to the community 
Using pipeline_id with the POST /deals endpoint will add a new deal, by default, to the first stage of the supplied pipeline. Since this parameter does not allow to choose a stage, we recommend using and have documented the stage_id parameter, because it allows to add the new deal to a specific stage in a specific pipeline.
Please note that stage_id and pipeline_id should not be used together, because pipeline_id will be ignored.
We totally see how using pipeline_id can be intuitive, so we’ll be taking your feedback up for discussion! 