Create matrix

POST /v1/matrix

Create matrix

cURL

curl --request POST \
  --url https://staging.api.us.aptlydone.com/matrix/v1/matrix \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "matrixName": "Grady LLC Approval Matrix",
  "matrixDescription": "Umerus odio cervus soleo considero minima utilis synagoga.",
  "matrixStatusId": "7ef3b8cd-83e1-4aea-a993-fd75e1c37eba",
  "authorityMatrix": true,
  "roleMatrix": true,
  "tenantId": "6d9e0600-7970-4ab7-8c1e-d51f3f4412ec",
  "ownerId": "1d69eb11-8c07-455d-807e-07582252c104",
  "copiedFrom": "c8c0a176-ea46-4f6e-a58b-4eb6431ea8c3",
  "authorityRoleIds": [
    "f793b2c6-d777-4efb-8adf-888da93a0ae3",
    "7af1cf99-3a3d-420b-a917-0ccecb809013"
  ],
  "groupIds": [
    "050ed07b-c0d2-41df-8323-5e1cae080fdc",
    "111ee836-e6b9-430c-bff3-571c11ad797b"
  ],
  "positionIds": [
    "43d09e5c-f839-4ba0-9343-2afe7912df55",
    "e2bc5f41-17bf-472c-a6e0-7efe1efb8602"
  ],
  "userIds": [
    "34a02c72-ce7a-47cc-8db6-ca8a976ae02e",
    "fb730d4f-66e4-4ba2-a37b-074c255f37cc"
  ],
  "decisionIds": [
    "4e9315ba-65e4-4102-914a-b423f6359c7e",
    "04bd203e-e79c-43cd-9b28-d286fd2220a9"
  ],
  "matrixExternalSharing": {
    "isEnabled": true,
    "isExpirationEnabled": true,
    "expirationDate": "2026-01-08T06:33:22.244Z",
    "isPasswordRequired": true,
    "password": "<string>"
  },
  "currentTab": "Sharing"
}
'

201

{
  "statusCode": 200,
  "timestamp": "2026-01-08T06:33:22.023Z",
  "message": "Success",
  "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

matrixName · string · required

Matrix name

Example:

"Grady LLC Approval Matrix"

matrixDescription · string · required

Matrix description

Example:

"Umerus odio cervus soleo considero minima utilis synagoga."

matrixStatusId · string<uuid> · required

Matrix status ID

Example:

"7ef3b8cd-83e1-4aea-a993-fd75e1c37eba"

authorityMatrix · boolean · required

Whether this is an authority matrix

Example:

true

roleMatrix · boolean · required

Whether this is a role matrix

Example:

true

tenantId · string<uuid> · required

Tenant ID

Example:

"6d9e0600-7970-4ab7-8c1e-d51f3f4412ec"

ownerId · string<uuid> · required

Owner ID

Example:

"1d69eb11-8c07-455d-807e-07582252c104"

copiedFrom · string<uuid>

Matrix copied from ID

Example:

"c8c0a176-ea46-4f6e-a58b-4eb6431ea8c3"

authorityRoleIds · string<uuid>[]

Authority role IDs

Example:

[
  "f793b2c6-d777-4efb-8adf-888da93a0ae3",
  "7af1cf99-3a3d-420b-a917-0ccecb809013"
]

groupIds · string<uuid>[]

Group IDs

Example:

[
  "050ed07b-c0d2-41df-8323-5e1cae080fdc",
  "111ee836-e6b9-430c-bff3-571c11ad797b"
]

positionIds · string<uuid>[]

Position IDs

Example:

[
  "43d09e5c-f839-4ba0-9343-2afe7912df55",
  "e2bc5f41-17bf-472c-a6e0-7efe1efb8602"
]

userIds · string<uuid>[]

User IDs

Example:

[
  "34a02c72-ce7a-47cc-8db6-ca8a976ae02e",
  "fb730d4f-66e4-4ba2-a37b-074c255f37cc"
]

decisionIds · string<uuid>[]

Decision IDs

Example:

[
  "4e9315ba-65e4-4102-914a-b423f6359c7e",
  "04bd203e-e79c-43cd-9b28-d286fd2220a9"
]

delegation · object

Delegation

Show child attributes

authorityFormatting · object

Authority formatting

Show child attributes

matrixSharing · object

Matrix sharing options

Show child attributes

matrixExternalSharing · object

Matrix external sharing configuration

Show child attributes

currentTab · string

Current tab in create matrix flow

Example:

"Sharing"

Response

201 - application/json

Matrix created successfully

statusCode · number · required

HTTP Status code

Example:

200

timestamp · string · required

Timestamp of the response

Example:

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

message · string · required

Response message

Example:

"Success"

data · object · required

Response data

Show child attributes