Source: https://sprinto-test.docs-staging.pageloop.ai/api-reference/framework-health-and-vendor-data-apis

# Framework Health & Vendor Data APIs

Use the Framework Health & Vendor Data APIs to retrieve framework health and vendor information from your Sprinto workspace. These APIs are read-only and do not modify data.

### Before you begin

Before you use these APIs, make sure you have:

- Your Sprinto application URL, such as `https://app.sprinto.com`
- A valid Developer API key

To generate an API key:

1. Log in to Sprinto.
2. Go to **Settings > Developer API**.

![](/assets/db40bad8fd1e-screenshot-2026-08-19-at-14.55.49.png)

3. Generate a new API key.
4. Copy and securely store the key.

> [!INFO]
>
> #### Note
>
> Keep your API key secure. Treat it like a password and never commit it to source control.

### Request format

All Framework Health & Vendor Data APIs:

- Use the **POST** method.
- Require the Developer API key in the `api-key` header.
- Accept request parameters inside the `args` object.

#### Endpoint format

```
POST {baseURL}/api/external/schema/queries/<queryName>/execute
```

#### Headers

```
api-key: <YOUR_API_KEY>
Content-Type: application/json
```

#### Request body

```json
{
  "args": {
    ...
  }
}
```

> [!INFO]
>
> #### Note
>
> Responses key entities by their primary key (`pk`). Pair a list query with a detail query when you need readable entity names.

## Framework health API

Returns the dashboard's per-framework `controlsCount`, `setupControlsCount`, and `averageReadiness`.

### Endpoint

```
POST /api/external/schema/queries/frameworkControlSetupAndReadinessCounts/execute
```

### Request body

```json
{
  "args": {
    "filterEnabledFrameworks": true,
    "filterDisabledOrGlobalFrameworks": false
  }
}
```

Set `filterEnabledFrameworks` to `true` to match the Sprinto UI. Without this filter, the response includes the full framework catalogue.

#### Example request

```bash
curl -X POST 'https://app.sprinto.com/api/external/schema/queries/frameworkControlSetupAndReadinessCounts/execute' \
  -H 'api-key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"args":{"filterEnabledFrameworks":true,"filterDisabledOrGlobalFrameworks":false}}'
```

#### Example response

```json
{
  "isSuccess": true,
  "data": [
    {
      "frameworkPk": "<framework-uuid>",
      "controlsCount": 73,
      "setupControlsCount": 46,
      "averageReadiness": 78
    },
    {
      "frameworkPk": "<framework-uuid>",
      "controlsCount": 19,
      "setupControlsCount": 12,
      "averageReadiness": 63
    }
  ]
}
```

`averageReadiness` is a percentage from 0 to 100.

To retrieve readable framework names, pair each `frameworkPk` with the `listFrameworks` query.

#### Response fields

| Field                | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `frameworkPk`        | Unique identifier of the framework.                        |
| `controlsCount`      | Number of controls in the framework.                       |
| `setupControlsCount` | Number of controls that have been set up.                  |
| `averageReadiness`   | Average framework readiness as a percentage from 0 to 100. |

## Vendor due-diligence status

Use `vendorsPaginated` or `getVendorByPk` with `includeDueDiligenceStatus: true` to retrieve vendor due-diligence status.

### List vendors with due-diligence status

#### Endpoint

```
POST /api/external/schema/queries/vendorsPaginated/execute
```

#### Example request

```bash
curl -X POST 'https://app.sprinto.com/api/external/schema/queries/vendorsPaginated/execute' \
  -H 'api-key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"args":{"first":50,"isArchived":false,"includeDueDiligenceStatus":true}}'
```

#### Request parameters

| Parameter                   | Type    | Required | Description                                                 |
| --------------------------- | ------- | -------- | ----------------------------------------------------------- |
| `first`                     | Integer | No       | Number of vendors to return.                                |
| `after`                     | String  | No       | Cursor for retrieving the next page.                        |
| `searchQuery`               | String  | No       | Search vendors by name.                                     |
| `categories`                | Array   | No       | Filter vendors by category.                                 |
| `isArchived`                | Boolean | No       | Filter vendors by their archived status.                    |
| `includeDueDiligenceStatus` | Boolean | No       | Set to `true` to include the vendor's due-diligence status. |

#### Example response

When using `vendorsPaginated`, `dueDiligenceStatus` appears on each `edges[].node`.

```json
{
  "isSuccess": true,
  "data": {
    "totalCount": 128,
    "edges": [
      {
        "cursor": "eyJ...",
        "node": {
          "pk": "<vendor-uuid>",
          "name": "Acme Cloud Services",
          "category": "Cloud Infrastructure",
          "riskLevel": "HIGH",
          "isActive": true,
          "dueDiligenceStatus": "PENDING"
        }
      }
    ],
    "pageInfo": {
      "hasNextPage": true,
      "endCursor": "eyJ..."
    }
  }
}
```

The list response follows a standard connection structure with `totalCount`, `edges`, and `pageInfo`.

### Get due-diligence status for one vendor

#### Endpoint

```
POST /api/external/schema/queries/getVendorByPk/execute
```

#### Example request

```json
{
  "args": {
    "vendorPk": "<uuid>",
    "includeDueDiligenceStatus": true
  }
}
```

#### Example response

```json
{
  "isSuccess": true,
  "data": {
    "pk": "<vendor-uuid>",
    "name": "Acme Cloud Services",
    "category": "Cloud Infrastructure",
    "riskLevel": "HIGH",
    "isActive": true,
    "dueDiligenceStatus": "PENDING"
  }
}
```

#### Due-diligence status values

The API can return the following values:

| Value                | Description                                    |
| -------------------- | ---------------------------------------------- |
| `OPTIONAL`           | Due diligence is optional.                     |
| `PENDING`            | Due diligence is pending.                      |
| `COMPLETED`          | Due diligence has been completed.              |
| `COMPLETED_APPROVED` | Due diligence has been completed and approved. |
| `COMPLETED_REJECTED` | Due diligence has been completed and rejected. |
| `SKIPPED`            | Due diligence has been skipped.                |
| `NA`                 | Due diligence is not applicable.               |

## Vendor custom fields

Use `getVendorByPk` or `vendorsPaginated` with `includeCustomAttributes: true` to retrieve vendor custom fields.

### Get custom fields for one vendor

#### Endpoint

```
POST /api/external/schema/queries/getVendorByPk/execute
```

#### Example request

```bash
curl -X POST 'https://app.sprinto.com/api/external/schema/queries/getVendorByPk/execute' \
  -H 'api-key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"args":{"vendorPk":"<uuid>","includeCustomAttributes":true}}'
```

#### Example response

```json
{
  "isSuccess": true,
  "data": {
    "pk": "<vendor-uuid>",
    "name": "Acme Cloud Services",
    "entityCustomAttributeValues": [
      {
        "entityCustomAttributeDefinitionPk": "<definition-uuid>",
        "definitionName": "Contract expiry date",
        "type": "DATE",
        "entityType": "Vendor",
        "entityPk": "<vendor-uuid>",
        "stringValue": null,
        "dateValue": "2026-09-14T18:30:00.000Z",
        "decimalValue": null,
        "unit": null,
        "userValue": null,
        "systemGroupValue": null,
        "arrayValue": null,
        "hasAttachment": false
      },
      {
        "entityCustomAttributeDefinitionPk": "<definition-uuid>",
        "definitionName": "DPIA",
        "type": "ATTACHMENT",
        "entityType": "Vendor",
        "entityPk": "<vendor-uuid>",
        "stringValue": null,
        "dateValue": null,
        "decimalValue": null,
        "unit": null,
        "userValue": null,
        "systemGroupValue": null,
        "arrayValue": null,
        "hasAttachment": true
      }
    ]
  }
}
```

#### Custom field response

The `entityCustomAttributeValues` object returns the custom field definition and its typed value.

Each value includes:

| Field                               | Description                                                |
| ----------------------------------- | ---------------------------------------------------------- |
| `entityCustomAttributeDefinitionPk` | Unique identifier of the custom field definition.          |
| `definitionName`                    | Name of the custom field.                                  |
| `type`                              | Type of the custom field.                                  |
| `entityType`                        | Entity type associated with the field.                     |
| `entityPk`                          | Unique identifier of the entity.                           |
| `stringValue`                       | Value for string-type fields.                              |
| `dateValue`                         | Value for date-type fields.                                |
| `decimalValue`                      | Value for decimal-type fields.                             |
| `userValue`                         | Value for user-type fields.                                |
| `systemGroupValue`                  | Value for system-group-type fields.                        |
| `arrayValue`                        | Value for array-type fields.                               |
| `hasAttachment`                     | Indicates whether files are present for attachment fields. |

Only the typed value corresponding to the field's `type` is populated. Other value fields are `null`.

For `ATTACHMENT` fields, `arrayValue` is `null` and `hasAttachment` indicates whether files are present. The API does not return raw file keys.

### List vendors with custom fields

You can also use `includeCustomAttributes: true` with `vendorsPaginated` to include custom fields in the vendor list response.

## Error responses

The APIs return the following errors:

| Error                  | Description                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| **401 Unauthorized**   | API key is missing (`User login required!`).                                                       |
| **401 Unauthorized**   | API key is invalid or inactive.                                                                    |
| **Invalid parameters** | One or more request parameters are invalid. The response includes details about the invalid input. |

> [!INFO]
>
> #### Note
>
> These APIs are read-only. They do not create, update, or delete data in your Sprinto workspace.

When you need additional information about a vendor, use a list query to retrieve the vendor's `pk`, then use `getVendorByPk` to retrieve its details.