---
sourceDocument: Yokohama API Reference
sourceDocumentLink: https://www.servicenow.com/docs/r/yokohama/api-reference

 Release :

    - yokohama

ft:locale :

    - en-US

ft:publication_title :

    - Yokohama API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Project Portfolio Management API

# Project Portfolio Management API {#ariaid-title1}

* Release version: Yokohama
* 
* Updated January 30, 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 minutes to read

The Project Portfolio Management API provides endpoints to bulk
import cost plans and project tasks.
The PPM Standard plugin (com.snc.financial_planning_pmo) is required to access this API. The
calling user must have the it_project_manager role.

This API is provided within the `now` namespace.

## Project Portfolio Management - POST /now/ppm/insert_cost_plans {#ariaid-title2}

Creates cost plans in the Cost Plan \[cost_plan\] table.

### URL format

Default URL:
/api/now/ppm/insert_cost_plans

### Supported request parameters

{#ppm-POST-costplans__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 1. Path parameters]

{#ppm-POST-costplans__entry__6}

| Name | Description |
|-|-|
| None |   |
[Table 2. Query parameters]

{#ppm-POST-costplans__entry__10}

| Name | Description |
|-|-|
| end_fiscal_period | Required. Sys_id of the ending fiscal period for the cost plan. Data type: String Table: Fiscal Period \[fiscal_period\] |
| name | Required. Name of the cost plan. Data type: String |
| resource_type | Required. Sys_id of the resource type. Data type: String Table: Resource Type Definition \[resource_type_definition\] |
| start_fiscal_period | Required. Sys_id of the starting fiscal period for the cost plan. Data type: String Table: Fiscal Period \[fiscal_period\] |
| task | Required. Sys_id of the project or demand for the cost plan. Data type: String Table: Project \[pm_project\] or Demand \[dmn_demand\] |
| unit_cost | Required. Unit cost for the cost plan. Data type: String |
[Table 3. Request body parameters (JSON)]

### Headers

The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#ppm-POST-costplans__entry__24}{#ppm-POST-costplans__accept-JSON-only-entry-RESTAPI}{#ppm-POST-costplans__content_type-JSON-only-entry-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Only supports application/json. |
| Content-Type | Data format of the request body. Only supports application/json. |
[Table 4. Request headers]

{#ppm-POST-costplans__entry__30}

| Header | Description |
|-|-|
| None |   |
[Table 5. Response headers]

### Status codes

The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#ppm-POST-costplans__entry__34}{#ppm-POST-costplans__entry-200-status-code}{#ppm-POST-costplans__entry-401-status-code}

| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
[Table 6. Status codes]

### Response body parameters (JSON)

{#ppm-POST-costplans__entry__40}

| Name | Description |
|-|-|
| result | Object containing information about the status of the API request. Data type: Object "result": { "status": "String" } |
| result.status | Status of the API request. Data type: String |
[ ]

### cURL request

This example imports two cost plans.

    curl "https://instance.servicenow.com/api/now/ppm/insert_cost_plans" \
    --request POST \
    --header "Accept:application/json" \
    --header "Content-Type:application/json" \
    --data "[
       {
          "name": "Cost plan 1",
          "resource_type": "3d16eaf79330120064f572edb67ffb04",
          "start_fiscal_period": "ed47e5d90b3010108d9ac74363673a98",
          "end_fiscal_period": "0a47e5d90b3010108d9ac74363673afd",
          "task": "0fc9f992db601810852ca6dc13961951",
          "unit_cost": 1200
       },
       {
          "name": "Cost plan 2",
          "resource_type": "3d16eaf79330120064f572edb67ffb04",
          "start_fiscal_period": "ed47e5d90b3010108d9ac74363673a98",
          "end_fiscal_period": "7947e5d90b3010108d9ac74363673ac9",
          "task": "0fc9f992db601810852ca6dc13961951",
          "unit_cost": 3600
       }
    ]" \
    --user 'username':'password'

Response body.

    {
       "result": {
          "status": "success"
       }
    }

## Project Portfolio Management - POST /now/ppm/insert_project_tasks {#ariaid-title3}

Creates a project and associated project tasks.
Projects are created in the Project \[pm_project\] table and project tasks are created in the
Project Task \[pm_project_task\] table.

### URL format

Default URL:
/api/now/ppm/insert_project_tasks

### Supported request parameters

{#ppm-POST-projecttasks__table_m1f_w5s_bwb__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 7. Path parameters]

{#ppm-POST-projecttasks__table_m1f_w5s_bwb} {#ppm-POST-projecttasks__table_nhq_w5s_bwb__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 8. Query parameters]

{#ppm-POST-projecttasks__table_nhq_w5s_bwb} {#ppm-POST-projecttasks__table_qqf_x5s_bwb__entry__2}

| Name | Description |
|-|-|
| child_tasks | Array of tasks for the project. Each task is an object in the array. Data type: Array "child_tasks": [ { "child_tasks": [Array], "external_id": "String", "short_description": "String" } ] |
| child_tasks.child_tasks | Array of child tasks for the parent task. Each child task is an object in the array. Each child task can have its own array of child tasks. Data type: Array "child_tasks": [ { "child_tasks": [Array], "external_id": "String", "short_description": "String" } ] |
| child_tasks.external_id | Unique identifier of the task from the external system. Data type: String |
| child_tasks.short_description | Short description of the task. Data type: String |
| end_date | End date for the project. Data type: String |
| external_id | Unique identifier of the project from the external system. Data type: String |
| short_description | Short description of the project. Data type: String |
| start_date | Start date for the project. Data type: String |
[Table 9. Request body parameters (JSON)]

{#ppm-POST-projecttasks__table_qqf_x5s_bwb}

### Headers

The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#ppm-POST-projecttasks__table_gtc_jbt_bwb__entry__2}{#ppm-POST-projecttasks__accept-JSON-only-entry-RESTAPI}{#ppm-POST-projecttasks__content_type-JSON-only-entry-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Only supports application/json. |
| Content-Type | Data format of the request body. Only supports application/json. |
[Table 10. Request headers]

{#ppm-POST-projecttasks__table_gtc_jbt_bwb} {#ppm-POST-projecttasks__entry__34}

| Header | Description |
|-|-|
| None |   |
[Table 11. Response headers]

### Status codes

The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#ppm-POST-projecttasks__table_acm_3bt_bwb__entry__2}{#ppm-POST-projecttasks__entry-200-status-code}{#ppm-POST-projecttasks__entry-401-status-code}

| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
[Table 12. Status codes]

{#ppm-POST-projecttasks__table_acm_3bt_bwb}

### Response body parameters (JSON) {#ppm-POST-projecttasks__section_vtd_kbt_bwb}

{#ppm-POST-projecttasks__table_wtd_kbt_bwb__entry__2}

| Name | Description |
|-|-|
| result | Object containing information about the status of the API request. Data type: Object "result": { "status": "String" } |
| result.status | Status of the API request. Data type: String |
[ ]

{#ppm-POST-projecttasks__table_wtd_kbt_bwb}  

### cURL request

This example imports a project with two tasks (zpq_T1 and zpq_T2). The first task contains
several child tasks, and the second task has dependencies on the child tasks from the first
task.

    curl "https://instance.servicenow.com/api/now/ppm/insert_project_tasks" \
    --request POST \
    --header "Accept:application/json" \
    --header "Content-Type:application/json" \
    --data "{
       "start_date": "2022-05-18 08:00:00",
       "end_date": "2022-05-18 17:00:00",
       "short_description": "zpq_Project",
       "external_id": "0",
       "child_tasks": [
          {
             "short_description": "zpq_T1",
             "external_id": "1",
             "child_tasks": [
                {
                   "external_id": "1.1",
                   "short_description": "zpq_T11",
                   "child_tasks": [
                      {
                         "external_id": "1.1.1",
                         "short_description": "zpq_T111"
                      }
                   ]
                },
                {
                   "external_id": "1.2",
                   "short_description": "zpq_T12"
                }
             ]
          },
          {
             "short_description": "zpq_T2",
             "external_id": "2",
             "dependencies": [
                {
                   "external_id": "1.1",
                   "lag": -1,
                   "type": "fs"
                },
                {
                   "external_id": "1.2",
                   "lag": 2,
                   "type": "fs"
                }
             ]
          }
       ]
    }" \
    --user 'username':'password'

Response body.

    {
       "result": {
          "status": "success"
       }
    }