Import API Mapper Set

Updated on May 4, 2025
Published on Jan 6, 2025

8 minute(s) read

Post

/api/1.0/api-mapper-sets/{envId}

This API supports UPDATE operations for API Mapper Sets, which are collections of API Mappers associated with a specific Application.

Notice

Accessing the APIs is through a dedicated domain/URL, according to your PlainID Tenant Location

United States (US) - `https://api.us1.plainid.io`

Canada (CA) - `https://api.ca1.plainid.io`

Europe (EU) - `https://api.eu1.plainid.io`

Using HTML Encoded Special Characters

Use HTML encoded patterns when working with values that contain special characters like spaces, dashes, etc. Refer to this HTML URL Encoding Reference for a full list.

Important note about headers

Refer to the headers below to modify your cURL sample. Check if the following headers are in the sample, if not, ensure you add it to your cURL sample before pasting into your API tool.

Headers

*Required

Header	Value	cURL Line
Accept	`application/json`	`-H "Accept:application/json"`
Content-Type	`application/json`	`-H "Content-Type:application/json"`

cURL Sample Guidelines

In order for the relevant parameters to appear in the cURL sample, you can input the values in the interactive API console on the right. They will then appear in the cURL sample on the bottom of the page in the correct format.

Object Limits

To ensure a smooth API Mapper Import, take note of the following limits:

API Mappers per Application - 100
Associated Asset Types per API Mapper - 5
Mappings to Attributes per Asset Type per API Mapper - 20
Mappings to Actions per Asset Type per API Mapper - 80

Security

HTTP

Type bearer

For more details about Administration API Authentication, check out the Authentication APIs documentation. Provide your bearer token in the Authorization header when making requests to protected resources. Example: Authorization: Bearer 123

Path parameters

envId

string (uuid) Required

The Environment ID can be found under the Details Tab in the Environment Settings.

Query parameters

authWsId

string (uuid) Required

Authorization Workspace ID. This can be found in your Authorization Workspace Settings under Workspace ID.

Body parameters

Fields to update in the API Mapper Set.

example

{
  "apiMappersSetId": "App1",
  "applicationIds": [
    "App1"
  ],
  "apiMappers": [
    {
      "mapperId": "mapper_1",
      "displayName": "mapper-1",
      "isActive": true,
      "matchPattern": "/bank/*/accountNum/**",
      "matchType": "EXACT",
      "restMethods": [
        "GET",
        "POST"
      ],
      "priority": 1,
      "isRequireIdentitySourcesFiltering": true,
      "filteringType": "INCLUDE",
      "identitySourceIds": [
        "sourceId1234567"
      ],
      "assetTemplates": [
        {
          "templateId": "accounts",
          "attributes": [
            {
              "attributeId": "acctType",
              "source": "PATH",
              "path": "[0]"
            }
          ],
          "actions": [
            {
              "actionId": "read",
              "source": "BODY",
              "value": "fetchData",
              "path": "$.function"
            }
          ]
        },
        {
          "templateId": "loans",
          "attributes": [],
          "actions": []
        }
      ]
    },
    {
      "mapperId": "mapper_2",
      "displayName": "mapper-2",
      "description": "desc",
      "isActive": true,
      "matchPattern": "/bank/*/loans/**",
      "matchType": "EXACT",
      "restMethods": [
        "POST"
      ],
      "priority": 2,
      "isRequireIdentitySourcesFiltering": false,
      "filteringType": "INCLUDE",
      "identitySourceIds": [
        "sourceId1234567"
      ],
      "assetTemplates": [
        {
          "templateId": "loans",
          "attributes": [],
          "actions": []
        }
      ]
    }
  ]
}

Expand All

object

API Mapper Set

apiMappersSetId

string Required

API Mapper Set Unique Identifier.

Min length1

Max length128

Pattern^[a-zA-Z0-9_:.-]+$

applicationIds

Array of string Required

Associated Application IDs. These IDs can be found in the individual Application Details section under Application ID.

string

apiMappers

Array of object (ApiMapper)

object

API Mapper

mapperId

string Required

API Mapper Unique Identifier. This can be found the API Mappers details section within the relevant Application.

Min length1

Max length128

Pattern^[a-zA-Z0-9_:.-]+$

displayName

string Required

API Mapper Name

Min length1

Max length100

description

string

API Mapper Description

Max length200

isActive

boolean Required

Indicates if the Mapper is active.

matchPattern

string Required

The URL pattern to which the Mapper applies.

matchType

string Required

Indicates if the matching is performed using a wildcard or exact match.

Valid values[ "EXACT", "WILDCARDS", "REGEX" ]

restMethods

Array of string Required

HTTP Methods that are applicable for the pattern.

string

Valid values[ "GET", "POST", "PUT", "PATCH", "DELETE" ]

priority

number Required

Mapper priority. Set the API Mapper priority to adjust the processing priority. For more information, see Managing API Mappers.

isRequireIdentitySourcesFiltering

boolean Required

Indicates if the API Mapper requires Identity Source filtering.

filteringType

string Required

Indicates which Identity Source filtering type is required. This parameter is required if isRequireIdentitySourcesFiltering is set to true.

Valid values[ "INCLUDE", "EXCLUDE" ]

identitySourceIds

Array of string Required

Indicates which Identity Sources need to be filtered. This parameter is required if isRequireIdentitySourcesFiltering is set to true. This can be located in the Attribute Source tab in the Identity Workspace Settings.

string

assetTemplates

Array of object (AssetTemplateApiMapping) Required

A list of Asset Templates associates with the API Mappers. You can locate Asset Template IDs under the relevant Assets' Details tab.

object

asset template api mapping

templateId

string Required

Asset Template unique identifier. You can locate the relevant Asset Template ID under the relevant Asset details.

attributes

Array of object (AssetAttributesApiMapping)

List of Attributes associated with the Asset Template containing API Mappers. You can locate the relevant Attribute IDs under the relevant Assets' Asset Attribute tab.

object

attributeId

string Required

Attribute unique identifier. You can locate the relevant Attribute ID under the relevant Asset's Asset Attribute tab.

source

string Required

Attribute Source. You can locate it in the Attribute Mapping Settings section under the relevant Asset Type's Asset Attribute.

Valid values[ "BODY", "HEADER", "PATH", "URI_REGEX" ]

path

string Required

JSON Path or relevant Path for the Attribute. You can locate it in the Attribute Mapping Settings section under the relevant Asset Type's Asset Attribute tab.

actions

Array of object (ActionApiMapping)

A list of Actions associated with the Asset Template. You can locate the relevant Action IDs under the relevant Assets' Actions tab.

object

actionId

string Required

Action unique identifier. You can locate the relevant Action ID under the relevant Asset Type's Actions tab.

source

string Required

Action source. You can locate it in the API Action Mappers section under the relevant Asset Type's Action tab.

Valid values[ "BODY", "HEADER", "PATH", "METHOD", "URI_REGEX" ]

value

string Required

Action value. You can locate it in the API Action Mappers section under the relevant Asset Type's Action tab.

path

string Required

Action path. You can locate it in the API Action Mappers section under the relevant Asset Type's Action tab.

Responses

201

Successful operation

Headers

x-request-id

string

The ID of the request

example

{
  "data": {
    "apiMappersSetId": "App1",
    "applicationIds": [
      "App1"
    ],
    "apiMappers": [
      {
        "mapperId": "mapper_1",
        "displayName": "mapper-1",
        "isActive": true,
        "matchPattern": "/bank/*/accountNum/**",
        "matchType": "EXACT",
        "restMethods": [
          "GET",
          "POST"
        ],
        "priority": 1,
        "isRequireIdentitySourcesFiltering": true,
        "filteringType": "INCLUDE",
        "identitySourceIds": [
          "sourceId1234567"
        ],
        "assetTemplates": [
          {
            "templateId": "accounts",
            "attributes": [
              {
                "attributeId": "acctType",
                "source": "PATH",
                "path": "[0]"
              }
            ],
            "actions": [
              {
                "actionId": "read",
                "source": "BODY",
                "value": "fetchData",
                "path": "$.function"
              }
            ]
          },
          {
            "templateId": "loans",
            "attributes": [],
            "actions": []
          }
        ]
      },
      {
        "mapperId": "mapper_2",
        "displayName": "mapper-2",
        "isActive": true,
        "matchPattern": "/bank/*/loans/**",
        "matchType": "EXACT",
        "restMethods": [
          "POST"
        ],
        "priority": 2,
        "isRequireIdentitySourcesFiltering": false,
        "filteringType": "INCLUDE",
        "identitySourceIds": [
          "sourceId1234567"
        ],
        "assetTemplates": [
          {
            "templateId": "loans",
            "attributes": [],
            "actions": []
          }
        ]
      }
    ]
  }
}

Expand All

object

API Mapper Set

data

object (ApiMapperSet)

API Mapper Set

apiMappersSetId

string

API Mapper Set Unique Identifier.

Min length1

Max length128

Pattern^[a-zA-Z0-9_:.-]+$

applicationIds

Array of string

Associated Application IDs. These IDs can be found in the individual Application Details section under Application ID.

string

apiMappers

Array of object (ApiMapper)

object

API Mapper

mapperId

string

API Mapper Unique Identifier. This can be found the API Mappers details section within the relevant Application.

Min length1

Max length128

Pattern^[a-zA-Z0-9_:.-]+$

displayName

string

API Mapper Name

Min length1

Max length100

description

string

API Mapper Description

Max length200

isActive

boolean

Indicates if the Mapper is active.

matchPattern

string

The URL pattern to which the Mapper applies.

matchType

string

Indicates if the matching is performed using a wildcard or exact match.

Valid values[ "EXACT", "WILDCARDS", "REGEX" ]

restMethods

Array of string

HTTP Methods that are applicable for the pattern.

string

Valid values[ "GET", "POST", "PUT", "PATCH", "DELETE" ]

priority

number

Mapper priority. Set the API Mapper priority to adjust the processing priority. For more information, see Managing API Mappers.

isRequireIdentitySourcesFiltering

boolean

Indicates if the API Mapper requires Identity Source filtering.

filteringType

string

Indicates which Identity Source filtering type is required. This parameter is required if isRequireIdentitySourcesFiltering is set to true.

Valid values[ "INCLUDE", "EXCLUDE" ]

identitySourceIds

Array of string

string

assetTemplates

Array of object (AssetTemplateApiMapping)

A list of Asset Templates associates with the API Mappers. You can locate Asset Template IDs under the relevant Assets' Details tab.

object

asset template api mapping

templateId

string

Asset Template unique identifier. You can locate the relevant Asset Template ID under the relevant Asset details.

attributes

Array of object (AssetAttributesApiMapping)

List of Attributes associated with the Asset Template containing API Mappers. You can locate the relevant Attribute IDs under the relevant Assets' Asset Attribute tab.

object

attributeId

string

Attribute unique identifier. You can locate the relevant Attribute ID under the relevant Asset's Asset Attribute tab.

source

string

Attribute Source. You can locate it in the Attribute Mapping Settings section under the relevant Asset Type's Asset Attribute.

Valid values[ "BODY", "HEADER", "PATH", "URI_REGEX" ]

path

string

JSON Path or relevant Path for the Attribute. You can locate it in the Attribute Mapping Settings section under the relevant Asset Type's Asset Attribute tab.

actions

Array of object (ActionApiMapping)

A list of Actions associated with the Asset Template. You can locate the relevant Action IDs under the relevant Assets' Actions tab.

object

actionId

string

Action unique identifier. You can locate the relevant Action ID under the relevant Asset Type's Actions tab.

source

string

Action source. You can locate it in the API Action Mappers section under the relevant Asset Type's Action tab.

Valid values[ "BODY", "HEADER", "PATH", "METHOD", "URI_REGEX" ]

value

string

Action value. You can locate it in the API Action Mappers section under the relevant Asset Type's Action tab.

path

string

Action path. You can locate it in the API Action Mappers section under the relevant Asset Type's Action tab.

400

Validation Error

Headers

x-request-id

string

The ID of the request

validationError

{
  "errors": [
    {
      "code": "APIV-004",
      "args": {
        "0": "apiMapperSetId",
        "path": "$.apiMappersSetId"
      },
      "id": "EBS8Z6",
      "status": "400",
      "name": "apiMappersSetIdUniquenessError",
      "message": "Api Mapper Set ID: [apiMapperSetId] must be unique"
    }
  ]
}

Expand All

object

Response object

errors

Array of object (Error)

object

code

string

status

integer

name

string

message

string

args

object

path

string

401

Unauthorized

Headers

x-request-id

string

The ID of the request

403

Forbidden

Headers

x-request-id

string

The ID of the request

404

Object not found

Headers

x-request-id

string

The ID of the request

422

Payload Validation Error

Headers

x-request-id

string

The ID of the request

500

Internal Server Error

Headers

x-request-id

string

The ID of the request

Was this article helpful?