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

# Framework Health And Vendor Data Apis

---
description: >-
  Learn how to retrieve framework health metrics and vendor information using
  Sprinto's Developer 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**.

<figure><img src="../.gitbook/assets/Screenshot 2026-08-19 at 14.55.49.png" alt="" width="563"><figcaption></figcaption></figure>

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

{% hint style="info" %}
#### Note

Keep your API key secure. Treat it like a password and never commit it to source control.
{% endhint %}

### 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": {
    ...
  }
}
```

{% hint style="info" %}
#### Note

Responses key entities by their primary key (`pk`). Pair a list query with a detail query when you need readable entity names.
{% endhint %}

## 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

<table><thead><tr><th width="236.09765625">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>frameworkPk</code></td><td>Unique identifier of the framework.</td></tr><tr><td><code>controlsCount</code></td><td>Number of controls in the framework.</td></tr><tr><td><code>setupControlsCount</code></td><td>Number of controls that have been set up.</td></tr><tr><td><code>averageReadiness</code></td><td>Average framework readiness as a percentage from 0 to 100.</td></tr></tbody></table>

## 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

<table><thead><tr><th width="243.10546875">Parameter</th><th width="110.56640625">Type</th><th width="109.56640625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>first</code></td><td>Integer</td><td>No</td><td>Number of vendors to return.</td></tr><tr><td><code>after</code></td><td>String</td><td>No</td><td>Cursor for retrieving the next page.</td></tr><tr><td><code>searchQuery</code></td><td>String</td><td>No</td><td>Search vendors by name.</td></tr><tr><td><code>categories</code></td><td>Array</td><td>No</td><td>Filter vendors by category.</td></tr><tr><td><code>isArchived</code></td><td>Boolean</td><td>No</td><td>Filter vendors by their archived status.</td></tr><tr><td><code>includeDueDiligenceStatus</code></td><td>Boolean</td><td>No</td><td>Set to <code>true</code> to include the vendor's due-diligence status.</td></tr></tbody></table>

#### 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:

<table><thead><tr><th width="197.02734375">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>OPTIONAL</code></td><td>Due diligence is optional.</td></tr><tr><td><code>PENDING</code></td><td>Due diligence is pending.</td></tr><tr><td><code>COMPLETED</code></td><td>Due diligence has been completed.</td></tr><tr><td><code>COMPLETED_APPROVED</code></td><td>Due diligence has been completed and approved.</td></tr><tr><td><code>COMPLETED_REJECTED</code></td><td>Due diligence has been completed and rejected.</td></tr><tr><td><code>SKIPPED</code></td><td>Due diligence has been skipped.</td></tr><tr><td><code>NA</code></td><td>Due diligence is not applicable.</td></tr></tbody></table>

## 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:

<table><thead><tr><th width="308.68359375">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>entityCustomAttributeDefinitionPk</code></td><td>Unique identifier of the custom field definition.</td></tr><tr><td><code>definitionName</code></td><td>Name of the custom field.</td></tr><tr><td><code>type</code></td><td>Type of the custom field.</td></tr><tr><td><code>entityType</code></td><td>Entity type associated with the field.</td></tr><tr><td><code>entityPk</code></td><td>Unique identifier of the entity.</td></tr><tr><td><code>stringValue</code></td><td>Value for string-type fields.</td></tr><tr><td><code>dateValue</code></td><td>Value for date-type fields.</td></tr><tr><td><code>decimalValue</code></td><td>Value for decimal-type fields.</td></tr><tr><td><code>userValue</code></td><td>Value for user-type fields.</td></tr><tr><td><code>systemGroupValue</code></td><td>Value for system-group-type fields.</td></tr><tr><td><code>arrayValue</code></td><td>Value for array-type fields.</td></tr><tr><td><code>hasAttachment</code></td><td>Indicates whether files are present for attachment fields.</td></tr></tbody></table>

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:

<table><thead><tr><th width="180.1796875">Error</th><th>Description</th></tr></thead><tbody><tr><td><strong>401 Unauthorized</strong></td><td>API key is missing (<code>User login required!</code>).</td></tr><tr><td><strong>401 Unauthorized</strong></td><td>API key is invalid or inactive.</td></tr><tr><td><strong>Invalid parameters</strong></td><td>One or more request parameters are invalid. The response includes details about the invalid input.</td></tr></tbody></table>

{% hint style="info" %}
#### Note

These APIs are read-only. They do not create, update, or delete data in your Sprinto workspace.
{% endhint %}

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.