Global search matrices with full filtering support

Search matrices with support for all filters including status, owner, groups, positions, users, dates, favorites, and more. Functionally identical to the listing API.

POST /v1/matrix/global-search

Global search matrices with full filtering support

cURL

curl --request POST \
  --url https://staging.api.us.aptlydone.com/matrix/v1/matrix/global-search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tenantId": "c084a3e6-9b4d-4d47-b6cc-7f3515f85a46",
  "page": 1,
  "limit": 10,
  "matrixStatusName": "Active",
  "countStatusName": "Draft,Archived",
  "search": "Investment",
  "isFavorite": true,
  "sortBy": "matrixName",
  "sortOrder": "asc",
  "groupIds": "2dff871a-296c-469c-85b6-c89768c1b21e, 60ad6e06-bd98-4627-9af6-a292323e2852",
  "positionIds": "6bdce3f9-a33c-4066-bd6a-56bb746ed01c, 3e56eb2d-bb81-4b2f-816d-349ea78efd90",
  "sectionIds": "d3d42bcb-04b7-4b89-83be-e1c7a77cb91a, a2128768-d7da-4bf4-8fcc-e56b4b8662e7",
  "categoryIds": "750229fc-dd2e-43e7-b611-2a2ad14a5d01, d17cbcae-334f-424b-8c53-5004243b4058",
  "matrixSharingType": "SHARED",
  "ownerId": "19568d14-a7e3-4dbb-a6bd-6d73de03ac3d, 496d5267-6b5c-4bc8-9f89-14f3f5cbc2a4",
  "userIds": "ffe779a4-9bb9-4c80-89f2-61e88891b37c, 727dec5b-06b7-4ff5-8f5c-e7a1574f4302",
  "links": null,
  "selectedMatrixIds": "7d05458c-30c2-44c9-9bdc-c14c36385b36, 9352f86b-499d-4a2e-a048-8fd5cb98f7de",
  "createdAtStart": "2025-01-01T00:00:00.000Z",
  "createdAtEnd": "2025-12-31T23:59:59.999Z",
  "updatedAtStart": "2025-01-01T00:00:00.000Z",
  "updatedAtEnd": "2025-12-31T23:59:59.999Z",
  "select": "id,matrixName,matrixDescription,matrixStatus",
  "selectedTab": "active"
}
'

200

{
  "statusCode": 200,
  "timestamp": "2026-01-08T06:33:22.604Z",
  "message": "Success",
  "data": {
    "page": 1,
    "limit": 10,
    "total": 10,
    "data": [
      {
        "id": "151efa58-ddbb-4d4a-a99a-7c3be5736f61",
        "matrixId": "10001",
        "matrixName": "Pagac - Kuvalis Approval Matrix",
        "matrixDescription": "Vomica sursum pariatur carcer.",
        "link": "/matrix/view/base64",
        "roleMatrix": true,
        "authorityMatrix": true,
        "tenantId": "49d7d738-c73c-4bcb-a413-1f986120855a",
        "ownerId": "cbe8bfb3-8d18-4e46-8bc8-ff7b764c5cb3",
        "decisionCount": 5,
        "delegationCount": 2,
        "copiedFromMatrix": "7fee7df1-3258-4ea8-9cef-43677e080395",
        "createdOn": "2026-01-07T20:16:28.638Z",
        "updatedOn": "2026-01-07T15:41:54.037Z",
        "matrixStatus": {
          "id": "8c2af516-88d6-4265-95d8-5bbd38b29fae",
          "statusName": "Active",
          "isActive": true
        },
        "matrixSharing": {
          "id": "45ea7f06-0011-43f4-8551-55f54447f298",
          "type": "SHARED",
          "sharingOption": "USERS_GROUPS",
          "link": true,
          "viewerAdjustableFilters": true,
          "externalSharing": false,
          "users": [
            {
              "id": "8111bdb2-e098-4dae-af0f-146b35ce3cb8",
              "userId": "bd61d3b1-1ef8-4a0f-8c14-8c62083b4c0e",
              "userDetails": {
                "id": "de3695df-aaf3-4a85-a02b-1a12655ee292",
                "email": "[e-mail]",
                "name": "Elias Graham MD",
                "displayName": "Helen Mohr IV",
                "firstName": "Esperanza",
                "lastName": "Murray",
                "mobilePhone": "1-493-376-0816",
                "isActive": true,
                "profileImageUrl": "https://cdn.jsdelivr.net/gh/faker-js/assets-person-portrait/male/512/72.jpg",
                "positions": [
                  {
                    "id": "3ded4c3f-6d9e-4b53-970d-1bd37d66ffe7",
                    "positionName": "System Administrator",
                    "autoProvisioned": true
                  }
                ],
                "primaryOrganization": {
                  "groupName": "North America Region",
                  "displayName": "North America Region",
                  "tenantGroupTypeId": "6d8cbc6e-7bb1-4b48-88bb-8180c325bcb2",
                  "tenantGroupTypeName": "Region"
                },
                "positionIds": [
                  "a52c5b91-0fb2-492b-bddc-7ea49ee33324"
                ],
                "primaryOrganizationId": "d64eb258-6f52-4fbc-bb25-d1550009a854",
                "manager": {
                  "id": "88d95fc1-0c1f-4f15-8ec2-a8efcf97cf97",
                  "name": "Leon Bogisich",
                  "displayName": "Pedro Toy DDS",
                  "profileImageUrl": "https://cdn.jsdelivr.net/gh/faker-js/assets-person-portrait/female/512/53.jpg"
                },
                "roles": [
                  {
                    "tenantRoleId": "a3ec8adc-96fc-4885-b14e-f273a0c26554",
                    "roleName": "System Administrator"
                  }
                ],
                "groups": [
                  {
                    "groupId": "159004f4-e8f9-49c0-b03c-552172d769b0",
                    "groupTypeId": "fb632b5b-8a45-43e0-95b2-f81a6017ed06"
                  }
                ]
              }
            }
          ],
          "groups": [
            {
              "id": "ebf12383-9fbe-4b45-82db-f1f1a53065c8",
              "groupId": "6d80952b-1dec-43e6-aeec-663e9d43bf0b",
              "groupDetails": {
                "id": "2edae481-425c-4b95-a95f-2356204c84b5",
                "groupName": "Finance Department",
                "displayName": "Finance Department",
                "legalName": "Finance Department LLC",
                "tenantId": "8c1a760b-2f94-4d63-983f-834bda0b9664",
                "groupTypeName": "Department",
                "groupTypeId": "0c543086-e010-430d-981c-f2d162434478",
                "status": "ACTIVE",
                "parentGroupIds": [
                  "624636ab-7f25-4e86-bfbc-7775a67fb60c"
                ],
                "isSynced": false
              }
            }
          ]
        },
        "matrixAuthorityRoles": [
          {
            "id": "42743462-f0eb-48e6-94f7-9295ffbe0a98",
            "authorityRoleId": "25a46c38-21dd-4b7f-a53b-e7a3fc7e8d93",
            "isEnabled": true
          }
        ],
        "matrixGroups": [
          {
            "id": "c90be4ec-5306-4a00-a818-4b45193c1b9e",
            "tenantGroupsMappingId": "0504d5fc-7075-4cc2-a172-a60c4bbfe816",
            "groupDetails": {
              "id": "2edae481-425c-4b95-a95f-2356204c84b5",
              "groupName": "Finance Department",
              "displayName": "Finance Department",
              "legalName": "Finance Department LLC",
              "tenantId": "8c1a760b-2f94-4d63-983f-834bda0b9664",
              "groupTypeName": "Department",
              "groupTypeId": "0c543086-e010-430d-981c-f2d162434478",
              "status": "ACTIVE",
              "parentGroupIds": [
                "624636ab-7f25-4e86-bfbc-7775a67fb60c"
              ],
              "isSynced": false
            }
          }
        ],
        "matrixPositions": [
          {
            "id": "37d09091-7f71-4572-9ed2-7a9f6330513d",
            "positionId": "72e810ec-bbb6-4ac9-b703-6d7374d854e7",
            "positionDetails": {
              "id": "141c47ca-351b-4653-abfb-6d886c60dcdc",
              "tenantId": "7f798579-7373-49cc-831a-6f8e0064c02b",
              "positionName": "System Administrator",
              "isScimProvisioned": false,
              "status": "ACTIVE",
              "groupIds": [
                "8bcee726-cc45-4e45-9e3b-60ba3e32bd8e",
                "70e09536-afed-438a-aa40-e12e8a6abae4"
              ]
            }
          }
        ],
        "matrixUsers": [
          {
            "id": "c51ea83f-8157-437a-b4f0-936db66726ba",
            "userId": "3746c737-9003-458d-9460-85d0ffa9e27d",
            "userDetails": {
              "id": "de3695df-aaf3-4a85-a02b-1a12655ee292",
              "email": "[e-mail]",
              "name": "Elias Graham MD",
              "displayName": "Helen Mohr IV",
              "firstName": "Esperanza",
              "lastName": "Murray",
              "mobilePhone": "1-493-376-0816",
              "isActive": true,
              "profileImageUrl": "https://cdn.jsdelivr.net/gh/faker-js/assets-person-portrait/male/512/72.jpg",
              "positions": [
                {
                  "id": "3ded4c3f-6d9e-4b53-970d-1bd37d66ffe7",
                  "positionName": "System Administrator",
                  "autoProvisioned": true
                }
              ],
              "primaryOrganization": {
                "groupName": "North America Region",
                "displayName": "North America Region",
                "tenantGroupTypeId": "6d8cbc6e-7bb1-4b48-88bb-8180c325bcb2",
                "tenantGroupTypeName": "Region"
              },
              "positionIds": [
                "a52c5b91-0fb2-492b-bddc-7ea49ee33324"
              ],
              "primaryOrganizationId": "d64eb258-6f52-4fbc-bb25-d1550009a854",
              "manager": {
                "id": "88d95fc1-0c1f-4f15-8ec2-a8efcf97cf97",
                "name": "Leon Bogisich",
                "displayName": "Pedro Toy DDS",
                "profileImageUrl": "https://cdn.jsdelivr.net/gh/faker-js/assets-person-portrait/female/512/53.jpg"
              },
              "roles": [
                {
                  "tenantRoleId": "a3ec8adc-96fc-4885-b14e-f273a0c26554",
                  "roleName": "System Administrator"
                }
              ],
              "groups": [
                {
                  "groupId": "159004f4-e8f9-49c0-b03c-552172d769b0",
                  "groupTypeId": "fb632b5b-8a45-43e0-95b2-f81a6017ed06"
                }
              ]
            }
          }
        ],
        "matrixDecisions": [
          {
            "id": "fbe1d724-8eff-4d93-9b59-5e7cd66abeba",
            "decisionId": "a7149654-b694-4f1c-9169-a817567d8641",
            "isDisabled": false,
            "disabledOn": null
          }
        ],
        "matrixSections": [
          {
            "sectionId": "47a84333-47ab-4b24-aa3d-4706de8b371b",
            "name": "Finance"
          }
        ],
        "matrixCategories": [
          {
            "categoryId": "fcf3c54d-3adf-4bf9-974b-6d0b093099a2",
            "name": "Approvals"
          }
        ],
        "suspendedDelegationsCount": 2,
        "pendingDelegationsCount": 2,
        "ownerDetails": {
          "id": "de3695df-aaf3-4a85-a02b-1a12655ee292",
          "email": "[e-mail]",
          "name": "Elias Graham MD",
          "displayName": "Helen Mohr IV",
          "firstName": "Esperanza",
          "lastName": "Murray",
          "mobilePhone": "1-493-376-0816",
          "isActive": true,
          "profileImageUrl": "https://cdn.jsdelivr.net/gh/faker-js/assets-person-portrait/male/512/72.jpg",
          "positions": [
            {
              "id": "3ded4c3f-6d9e-4b53-970d-1bd37d66ffe7",
              "positionName": "System Administrator",
              "autoProvisioned": true
            }
          ],
          "primaryOrganization": {
            "groupName": "North America Region",
            "displayName": "North America Region",
            "tenantGroupTypeId": "6d8cbc6e-7bb1-4b48-88bb-8180c325bcb2",
            "tenantGroupTypeName": "Region"
          },
          "positionIds": [
            "a52c5b91-0fb2-492b-bddc-7ea49ee33324"
          ],
          "primaryOrganizationId": "d64eb258-6f52-4fbc-bb25-d1550009a854",
          "manager": {
            "id": "88d95fc1-0c1f-4f15-8ec2-a8efcf97cf97",
            "name": "Leon Bogisich",
            "displayName": "Pedro Toy DDS",
            "profileImageUrl": "https://cdn.jsdelivr.net/gh/faker-js/assets-person-portrait/female/512/53.jpg"
          },
          "roles": [
            {
              "tenantRoleId": "a3ec8adc-96fc-4885-b14e-f273a0c26554",
              "roleName": "System Administrator"
            }
          ],
          "groups": [
            {
              "groupId": "159004f4-e8f9-49c0-b03c-552172d769b0",
              "groupTypeId": "fb632b5b-8a45-43e0-95b2-f81a6017ed06"
            }
          ]
        },
        "currentTab": "Sharing",
        "isFavorite": true,
        "matrixDelegation": {
          "delegationRole": true,
          "delegationDataDetails": true,
          "delegationDataGroups": true,
          "delegationDataDocuments": true,
          "delegationDataConditions": true,
          "delegationDataAuthorities": true,
          "delegationDataRoles": true,
          "authorityTypeIds": [
            "ef444051-af8a-4ce0-a2e8-4e0d0d588c0d",
            "e50a087e-f0e5-499b-8314-35e5856712e8"
          ],
          "roleIds": [
            "2a8bbebc-8e8c-40da-a55c-ac0f327bc3bb",
            "3cb123a4-6561-42ea-9560-7211f289ecf1"
          ],
          "issuanceStatusNames": [
            "Accepted",
            "Pending"
          ],
          "primaryLimitTypes": {
            "Value (Currency)": {
              "min": 1,
              "max": 2
            },
            "Time (Months)": {
              "min": 1,
              "max": 2
            },
            "Time (Years)": {
              "min": 1,
              "max": 2
            },
            "Authority": true
          }
        },
        "matrixAuthorityFormatting": {
          "valueAbbrevations": "Actual Values",
          "valueRounding": "0 decimals",
          "timeUnit": "Actual Values",
          "timeRounding": "0 decimals",
          "delegationIdentification": "Position Username",
          "displayCurrencyCode": "USD"
        },
        "permissions": [
          {
            "relationship_key": "<string>",
            "allowed": true
          }
        ],
        "isUserSavedPersonalView": true,
        "matrixExternalSharing": {
          "id": "<string>",
          "link": "<string>",
          "isExpirationEnabled": true,
          "expirationDate": "2026-01-08T06:33:22.245Z",
          "isPasswordRequired": true,
          "matrixSharingId": "<string>",
          "matrixId": "<string>",
          "createdOn": "2026-01-08T06:33:22.246Z",
          "updatedOn": "2026-01-08T06:33:22.246Z",
          "password": "<string>"
        }
      }
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

tenantId · string · required

Tenant ID

Example:

"c084a3e6-9b4d-4d47-b6cc-7f3515f85a46"

page · number

Page number

Required range: x >= 1

Example:

1

limit · number

Number of items per page

Required range: 1 <= x <= 100

Example:

10

matrixStatusName · string[]

Comma separated Matrix Status values for matrices list

Example:

"Active"

countStatusName · string[]

Comma separated Matrix Status values for count section

Example:

"Draft,Archived"

search · string

Search string for matrix name, description, or matrix ID

Example:

"Investment"

isFavorite · boolean

Is the Matrix a favorite

Example:

true

sortBy · string

Criteria for sorting Decisions

Example:

"matrixName"

sortOrder · enum<string>

Order for sorting Decisions

Available options: asc, desc

Example:

"asc"

groupIds · string[]

Comma separated Group IDs

Example:

"2dff871a-296c-469c-85b6-c89768c1b21e, 60ad6e06-bd98-4627-9af6-a292323e2852"

positionIds · string[]

Comma separated Position IDs

Example:

"6bdce3f9-a33c-4066-bd6a-56bb746ed01c, 3e56eb2d-bb81-4b2f-816d-349ea78efd90"

sectionIds · string[]

Comma separated Section IDs

Example:

"d3d42bcb-04b7-4b89-83be-e1c7a77cb91a, a2128768-d7da-4bf4-8fcc-e56b4b8662e7"

categoryIds · string[]

Comma separated Category IDs

Example:

"750229fc-dd2e-43e7-b611-2a2ad14a5d01, d17cbcae-334f-424b-8c53-5004243b4058"

matrixSharingType · object[]

Comma separated Matrix Sharing Type values

Example:

"SHARED"

ownerId · string[]

Comma separated Owner User IDs

Example:

"19568d14-a7e3-4dbb-a6bd-6d73de03ac3d, 496d5267-6b5c-4bc8-9f89-14f3f5cbc2a4"

userIds · string[]

Comma separated User IDs

Example:

"ffe779a4-9bb9-4c80-89f2-61e88891b37c, 727dec5b-06b7-4ff5-8f5c-e7a1574f4302"

links · string[]

Comma separated Matrix Link

Example:

null

decisionsCount · object

Decisions count filter

Show child attributes

delegationsCount · object

Delegations count filter

Show child attributes

selectedMatrixIds · string[]

Comma separated Selected Matrix IDs

Example:

"7d05458c-30c2-44c9-9bdc-c14c36385b36, 9352f86b-499d-4a2e-a048-8fd5cb98f7de"

createdAtStart · string

Start date for creation date filtering (ISO format)

Example:

"2025-01-01T00:00:00.000Z"

createdAtEnd · string

End date for creation date filtering (ISO format)

Example:

"2025-12-31T23:59:59.999Z"

updatedAtStart · string

Start date for last update filtering (ISO format)

Example:

"2025-01-01T00:00:00.000Z"

updatedAtEnd · string

End date for last update filtering (ISO format)

Example:

"2025-12-31T23:59:59.999Z"

select · string

Comma separated fields to select in response

Example:

"id,matrixName,matrixDescription,matrixStatus"

selectedTab · enum<string>

Selected tab to filter counts and listings (active, inactive, favorite, all)

Available options: active, inactive, favorite, all

Example:

"active"

Response

200

application/json

Matrix list retrieved successfully

statusCode · number · required

Example:

200

timestamp · string · required

Example:

"2026-01-08T06:33:22.604Z"

message · string · required

Example:

"Success"

data · object

Show child attributes