Mutual Action Plan

Mutual Action Plan (MAP) is a solution attached to Shared Spaces to facilitate the vendor/customer partnership. It's a centralized location where both sellers and buyers can enjoy a two-way collaboration to track progress and manage a deal's milestones and tasks from start to finish:

Prerequisites

Showpad Ultimate package
Shared Spaces enabled
Shared Space member or Showpad administrator account

Base Endpoint

Every request needs to be prefixed with the base endpoint:

https://{{subdomain}}.api.showpad.com/v4

MAPs use Showpad API v4. Therefore, your calls will use the base endpoint + the API version + the purpose of the call:

https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/...

MAP Domain Language

To start working with Mutual Action Plans via API, it's important to understand the required terminology in order to work effectively.

	Description
`mutual-action-plan`	A structured plan of actions and milestones linked to defined Showpad Shared Space. Synonyms: Next Steps Note: Must be added to a specific context: `contextType=SHARED-SPACE`
`contextType`	Identifies `SHARED-SPACE` as the entity to which a MAP is added.
`milestone`	A grouping of `actions` within a MAP. It defines a single goal which includes individual tasks to complete.
`action`	A single task to execute. It can have: zero or more `assignees` an optional `due date` A action has two states: `COMPLETED` `NOT_COMPLETED`
`participantId`	A defined Showpad Identity with access to the Shared Space the MAP is linked to. A participant has two states: `ACTIVE` `INACTIVE`
`assignee`	A `participant` of a Mutual Action Plan charged with completing a specific `action`. Only `ACTIVE` participants can be assigned to an action. Note: If an assignee is not a participant of the MAP, the assignment is omitted.
`dueAt`	A date defining the deadline for a `action` to be completed. Due dates have three color-coded statuses: `DEFAULT` - default state `ALMOST DUE` - 7 days or less until deadline `OVERDUE` - deadline is in the past
`sourceMapId`	The identifier of a MAP to use as a template.

MAP

The following sections describe how to make requests concerning a MAP.

Create MAP

note

This action can only be performed by internal users (sellers).

Before you can create a Mutual Action Plan, you must know the ID of the context to which you want to add it. For Shared Spaces, you can obtain this id by executing a GET request for a List of Shared Spaces.

Once you have the context, you can create a MAP with the following request:

Method	Endpoint	Description
`POST`	`/mutual-action-plan`	Creates a MAP in the identified context.

In the payload, add the MAP to a context with contextType and contextId. For Shared Spaces, you would define:

contextType : SHARED-SPACE
contextId: {Shared Space Id}

Example Request

POST https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan

Payload: `{"contextType":"SHARED-SPACE", "contextId": "f10ea2108f07cafb3edd62a46346f234"}

Example Response

{
    "id": "01HBR3C8AB2PMYMEMJREVF4DBY",
    "context": {
        "type": "SHARED-SPACE",
        "id": "f10ea2108f07cafb3edd62a46346f234"
    },
    "createdAt": "2023-10-02T11:46:33.931Z",
    "updatedAt": "2023-10-02T11:46:33.931Z"
}

caution

Only one MAP can be added to a context. If a MAP has already exists for the specified context, an error is returned.

Duplicate MAP

You can use a MAP as a template to create another MAP by following the Create MAP process and including a sourceMapId in the request payload:

sourceMapId: {MAP ID}

This is the identifier of another MAP that you want to use as a template. The entire structure of the source MAP (milestones and actions, including their positions) will be copied to the new MAP.

Example Request

POST https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan

Payload: `{"contextType":"SHARED-SPACE", "contextId": "f10ea2108f07cafb3edd62a46346f234", "sourceMapId":"01HBR3C8AB2PMYMEMJREVF4DAY"}

Example Response

{
    "id": "01HBR3C8AB2PMYMEMJREVF4DBY",
    "context": {
        "type": "SHARED-SPACE",
        "id": "f10ea2108f07cafb3edd62a46346f234"
    },
    "createdAt": "2023-10-02T11:46:33.931Z",
    "updatedAt": "2023-10-02T11:46:33.931Z"
}

caution

You must have access to the MAP specified in sourceMapId.

Delete MAP

note

This action can only be performed by internal Showpad users.

You can delete a MAP with the following request:

Method	Endpoint	Description
`DELETE`	`/mutual-action-plan/{mapId}`	Permanently removes the specified MAP in its entirity (including milestones, actions, assignees, etc.)

Example Request

DELETE https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY

Example Response

HTTP Status 204 No Content

View MAP

You can retrieve the details of a MAP with the following request:

Method	Endpoint	Description
`GET`	`/mutual-action-plan/{mapId}`	Returns the details of a MAP. The `view` query parameter has two values: `BASIC` - (default value). Provides minimal information of a MAP `FULL` - Provides the complete MAP tree

Basic

Example Request

GET https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY?view=BASIC

Example Response

{
    "view": "BASIC",
    "id": "01HBR3C8AB2PMYMEMJREVF4DBY",
    "context": {
        "id": "f10ea2108f07cafb3edd62a46346f234",
        "type": "SHARED-SPACE",
        "title": "my super MAP"
    },
    "createdAt": "2023-10-02T11:46:33.931Z",
    "updatedAt": "2023-10-02T11:46:33.931Z"
}

Full

GET https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY?view=FULL

Example Response

{
    "view": "FULL",
    "id": "01HBR3C8AB2PMYMEMJREVF4DBY",
    "context": {
        "id": "f10ea2108f07cafb3edd62a46346f234",
        "type": "SHARED-SPACE",
        "title": "my super MAP"
    },
    "createdAt": "2023-10-02T11:46:33.931Z",
    "updatedAt": "2023-10-02T11:46:33.931Z",
    "milestones": [
        {
            "id": "01HBR3JF73V2YNX2CP75B1103G",
            "title": "Nice!",
            "createdAt": "2023-10-02T11:49:57.603Z",
            "updatedAt": "2023-10-02T11:49:57.603Z",
            "actions": [
                {
                    "id": "01HBR4QK8A42E4W1WYKEKMYABR",
                    "title": "First one",
                    "dueAt": null,
                    "createdAt": "2023-10-02T12:10:14.154Z",
                    "updatedAt": "2023-10-02T12:11:15.983Z",
                    "status": "NOT_COMPLETED",
                    "assignees": [
                        {
                            "id": "01HBR5EE675E7PSG8WMKECKRR5",
                            "participantId": "eddd773d2cbdc57a70f73aa7b40c1e72",
                            "createdAt": "2023-10-02T12:22:42.630Z",
                            "updatedAt": "2023-10-02T12:22:42.630Z"
                        }
                    ]
                },
                {
                    "id": "01HBR3SZ3ZJXCJBKEJBJZEVFQY",
                    "title": "Nice action!",
                    "dueAt": null,
                    "createdAt": "2023-10-02T11:54:03.263Z",
                    "updatedAt": "2023-10-02T12:11:15.996Z",
                    "status": "NOT_COMPLETED",
                    "assignees": []
                }
            ]
        }
    ]
}

List of MAPs

You can retrieve a list of all your Mutual Action Plans with the following request:

Method	Endpoint	Description
`GET`	`/mutual-action-plan`	Returns a list of all MAPs for your organization. The `contextType` query parameter is required.

note

All internal users can request a list of MAPs, but only the MAPs to which they have access are returned (i.e., the user must must be a participant in the context the MAP is attached to).

Example Request

GET https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan?contextType=SHARED-SPACE

Example Response

{
    "items": [
        {
            "id": "01HBR3C8AB2PMYMEMJREVF4DAY",
            "context": {
                "id": "f10ea2108f07cafb3edd62a46346f234",
                "type": "SHARED-SPACE",
                "title": "my first map"
            },
            "createdAt": "2023-10-02T11:46:33.931Z",
            "updatedAt": "2023-10-02T11:46:33.931Z"
        },
        {
            "id": "01HBR3C8AB2PMYMEMJREVF4DBY",
            "context": {
                "id": "f10ea2108f07cafb3edd62a46346f567",
                "type": "SHARED-SPACE",
                "title": "my second map"
            },
            "createdAt": "2023-11-02T10:15:45.823Z",
            "updatedAt": "2023-11-02T10:15:45.823Z"
        }
    ]
}

Milestones

The following sections describe how to make requests concerning the Milestones within a MAP.

Add Milestone

In order to add milestones to your MAP, you'll need its ID. You can get this ID from the Create MAP request response or you can use the List of MAPs request and filter by contextType (Shared Space) and contextId (Shared Space ID).

Once you have the MAP ID, you can add Milestones with the following request:

Method	Endpoint	Description
`POST`	`/mutual-action-plan/{mapId}/milestones`	Adds a milestone to the MAP with the given ID.

Example Request

POST: https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY/milestones

Payload: {"title":"Nice!"}

Example Response

{
    "id": "01HBR3JF73V2YNX2CP75B1103G",
    "title": "Nice!",
    "createdAt": "2023-10-02T11:49:57.603Z",
    "updatedAt": "2023-10-02T11:49:57.603Z"
}

Update Milestone

You can update the title and/or position of a Milestone with the following request:

Method	Endpoint	Description
`PATCH`	`/mutual-action-plan/{MAP ID}/milestones/{Milestone ID}`	Updates a Milestone in the specified MAP.

Example Request

PATCH: https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY/milestones/01HBR3JF73V2YNX2CP75B1103G

Payload: {"title":"New title"}

Example Response

{
    "id": "01HBR3JF73V2YNX2CP75B1103G",
    "title": "New title",
    "createdAt": "2023-10-02T11:49:57.603Z",
    "updatedAt": "2023-10-02T11:49:57.603Z"
}

Reorder Milestones

You can change the order of Milestons by using their ordinal numbers to define their position in the payload. Note that counting begins at 0 (zero).

milestone A (position 0)
milestone B (position 1)

Method	Endpoint	Description
`PATCH`	`/mutual-action-plan/{MAP ID}/milestones/{Milestone ID}`	Defines the order of the Milestones within a MAP.

Example Request

PATCH: https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY/milestones/01HBR3JF73V2YNX2CP75B1103G

Payload: {"position": 0}

Example Response

{
    "id": "01HBR3JF73V2YNX2CP75B1103G",
    "title": "New title",
    "createdAt": "2023-10-02T11:49:57.603Z",
    "updatedAt": "2023-10-02T11:49:57.603Z"
}

Delete Milestone

You can delete a Milestone with the following request:

Method	Endpoint	Description
`DELETE`	`/mutual-action-plan/{MAP ID}/milestones/{Milestone ID}`	Permanently removes the specified Milestone in its entirety (including actions and assignees).

Example Request

DELETE: https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY/milestones/01HBR3JF73V2YNX2CP75B1103G

Example Response

HTTP Status 204 No Content

Actions

The following sections describe how to make requests concerning the Actions within the Milestones of a MAP.

info

Actions performed as part of automation/integration will appear as "Integration App" in the MAP's activity timeline in Showpad.

Add Action

To add an action to a Milestone, you must specify the IDs for both the MAP and the Milestone:

Method	Endpoint	Description
`POST`	`/mutual-action-plan/{MAP ID}/milestones/{Milestone ID}/actions`	Adds an `action` to the specified Milestone in the designated MAP.

Example Request

POST: https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY/milestones/01HBR3JF73V2YNX2CP75B1103G/actions

Payload: {"title":"Nice action!"}

Example Response

{
    "id": "01HBR3SZ3ZJXCJBKEJBJZEVFQY",
    "title": "Nice action!",
    "dueAt": null,
    "createdAt": "2023-10-02T11:54:03.263Z",
    "updatedAt": "2023-10-02T11:54:03.263Z",
    "status": "NOT_COMPLETED"
}

Update Action

You can update the following fields of an Action:

title,
due date,
status,
Milestone identifier,
position (see reorder-actions)

Method	Endpoint	Description
`PATCH`	`v4/mutual-action-plan/{MAP ID}/milestones/{Milestone ID}/actions/{actionId}`	Updates an `action` in a specified Milestone within the designated MAP.

Example Request

PATCH: https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY/milestones/01HBR3JF73V2YNX2CP75B1103G/actions/01HBR3SZ3ZJXCJBKEJBJZEVFQY

Payload: {"status": "COMPLETED", "title": "new title", "dueAt": "2023-10-10T22:00:00.000Z", "milestoneId": "01HDNZBSEQECHRXPHEA2KS2XKT"}

Example Response

{
    "id": "01HBR3SZ3ZJXCJBKEJBJZEVFQY",
    "title": "new title",
    "dueAt": "2023-10-10T22:00:00.000Z",
    "createdAt": "2023-10-02T11:54:03.263Z",
    "updatedAt": "2023-10-02T11:54:03.263Z",
    "status": "COMPLETED"
}

Reorder Actions

You can change the order of Actions within Milestons by using their ordinal numbers to define their position in the payload. Note that counting begins at 0 (zero).

Milestone A
- Action AA (position 0)
- Action AB (position 1)
Milestone B
- Action BA (position 0)
- Action BB (position 1)

Example Request

PATCH: https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY/milestones/01HBR3JF73V2YNX2CP75B1103G/actions/01HBR3SZ3ZJXCJBKEJBJZEVFQY

Payload: {"position": 0}

Example Response

{
    "id": "01HBR3SZ3ZJXCJBKEJBJZEVFQY",
    "title": "Nice action!",
    "dueAt": null,
    "createdAt": "2023-10-02T11:54:03.263Z",
    "updatedAt": "2023-10-02T11:54:03.263Z",
    "status": "NOT_COMPLETED"
}

Delete Action

You can delete an action with the following request:

Method	Endpoint	Description
`DELETE`	`/mutual-action-plan/{MAP ID}/milestones/{Milestone ID}/actions/{Action ID}`	Permanently removes the specified action.

Example Request

DELETE: https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY/milestones/01HBR3JF73V2YNX2CP75B1103G/actions/01HBR3SZ3ZJXCJBKEJBJZEVFQY

Example Response

HTTP Status 204 No Content

Participants

The following sections describe how to make requests concerning the Participants that can be assigned Actions within the Milestones of a MAP.

Assign Action

You can assign actions to multiple participants. In order to do so, you must have the ID of the participants. You can use the List of Participants request to retrieve all of the participants in a given MAP.

Once you have the participantId, you can assign an action with the following request:

Method	Endpoint	Description
`POST`	`/mutual-action-plan/{MAP ID}/milestones/[Milestone ID]/actions/{Action ID}/assignees`	Assigns a specific action to a designated particpant. The response provides an Assignee ID of the assignment to the participant.

Example Request

POST https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY/milestones/01HBR3JF73V2YNX2CP75B1103G/actions/01HBR3SZ3ZJXCJBKEJBJZEVFQY/assignees

Payload: `{"participantId":"eddd773d2cbdc57a70f73aa7b40c1e72"}`

Example Response

{
    "id": "01HBR4CBZBEYY1FPEGTNJBH6J1",
    "participantId": "eddd773d2cbdc57a70f73aa7b40c1e72",
    "createdAt": "2023-10-02T12:04:06.251Z",
    "updatedAt": "2023-10-02T12:04:06.251Z"
}

Unassign Action

You can unassign an action from an Assignee, you use the following request:

Method	Endpoint	Description
`DELETE`	`DELETE /mutual-action-plan/{MAP ID}/milestones/{Milestone ID}/actions/{Action ID}/assignees/{Assignee ID}`	Permanently removes a specific assigned action from a designated particpant.

Example Request

DELETE https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/01HBR3C8AB2PMYMEMJREVF4DBY/milestones/01HBR3JF73V2YNX2CP75B1103G/actions/01HBR3SZ3ZJXCJBKEJBJZEVFQY/assignees/01HBR4CBZBEYY1FPEGTNJBH6J1

List of Participants

You can retrieve a list of all of the participants in a MAP:

Method	Endpoint	Description
`GET`	`/mutual-action-plan/{MAP Id}/participants`	Returns all participants in a MAP.

Example Request

GET https://{{subdomain}}.api.showpad.com/v4/mutual-action-plan/{MAP ID}/participants

Example Response

{
    "items": [
        {
            "id": "eddd773d2cbdc57a70f73aa7b40c1972",
            "status": "ACTIVE",
            "userId": "b5f5e881324f61479002be5cda41abba",
            "email": "Kris.P.Bacon@yummy.com",
            "firstName": "Kris",
            "lastName": "Bacon",
            "avatar": "https://doc.staging.showpad.biz/api/v3/assets/a95f81268091ab912ae1ee48c5e5r2d2/preview/v1.0"
        }
    ]
}

Base Endpoint​

MAP Domain Language​

MAP​

Create MAP​

Duplicate MAP​

Delete MAP​

View MAP​

List of MAPs​

Milestones​

Add Milestone​

Update Milestone​

Reorder Milestones​

Delete Milestone​

Actions​

Add Action​

Update Action​

Reorder Actions​

Delete Action​

Participants​

Assign Action​

Unassign Action​

List of Participants​

Base Endpoint

MAP Domain Language

MAP

Create MAP

Duplicate MAP

Delete MAP

View MAP

List of MAPs

Milestones

Add Milestone

Update Milestone

Reorder Milestones

Delete Milestone

Actions

Add Action

Update Action

Reorder Actions

Delete Action

Participants

Assign Action

Unassign Action

List of Participants