# Supporting APIs

These APIs are used to fetch supporting data required when creating a consent request.\
They provide information about providers and the additional fields needed for each provider and purpose.

It covers the following endpoints:

* [List Identity Providers API](#list-identity-providers-api)
* [Provider Template Fields API](#provider-template-fields-api)

### List Identity Providers API

**Method:** GET\
**Path:** `/api/v1/provider/list`\
**Description:** Fetches an exhaustive list of providers on the AMF platform. If your business unit is allowed to use the given provider, it will be indicated with the `canRequestConsent` flag.

#### Request

**Headers**

| Header        | Value            | Required |
| ------------- | ---------------- | -------- |
| Authorization | Bearer `<token>` | Yes      |

**Body**

Body is an array of provider objects:

```json
[
  {
    "providerDescription": "Supported provider",
    "providerBusinessUnitId": "00000000-0000-0000-0000-000000000000",
    "purposeDescription": "Bank statements",
    "purposeId": "00000000-0000-0000-0000-000000000000",
    "canRequestConsent": true
  },
  {
    "providerDescription": "Supported provider",
    "providerBusinessUnitId": "00000000-0000-0000-0000-000000000000",
    "purposeDescription": "Know your customer",
    "purposeId": "00000000-0000-0000-0000-000000000000",
    "canRequestConsent": true
  },
  {
    "providerDescription": "Unsupported provider",
    "providerBusinessUnitId": "00000000-0000-0000-0000-000000000000",
    "purposeDescription": "Know your customer",
    "purposeId": "00000000-0000-0000-0000-000000000000",
    "canRequestConsent": false
  }
]
```

**Response Field Descriptions**

| Field                    | Type    | Description                                                                                  |
| ------------------------ | ------- | -------------------------------------------------------------------------------------------- |
| `providerDescription`    | string  | Name or description of the provider                                                          |
| `providerBusinessUnitId` | GUID    | Unique ID of the provider’s business unit                                                    |
| `purposeDescription`     | string  | Description of the purpose for which consent can be requested                                |
| `purposeId`              | GUID    | Unique ID of the purpose                                                                     |
| `canRequestConsent`      | boolean | Indicates whether the Requesting business unit can request consent for this provider/purpose |

***

### Provider Template Fields API

**Method:** GET\
**Path:** `/api/v1/provider/{id}/templates/{purposeId}`\
**Description:** Fetches a list of required additional fields for the given provider and purpose (from the previous API). Only primitive types are supported.

**Path Parameters:**

| Parameter   | Type | Description                                      |
| ----------- | ---- | ------------------------------------------------ |
| `id`        | GUID | `providerBusinessUnitId` from List Providers API |
| `purposeId` | GUID | `purposeId` from List Providers API              |

#### Request

**Headers**

| Header        | Value            | Required |
| ------------- | ---------------- | -------- |
| Authorization | Bearer `<token>` | Yes      |

#### Response

**Body**

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "text": "Additional fields for provider",
  "templateData": [
    {
      "key": "CUSTOM_FIELD_NAME_1",
      "validation": "string",
      "value": ""
    },
    {
      "key": "CUSTOM_FIELD_NAME_2",
      "validation": "string",
      "value": ""
    },
    {
      "key": "CUSTOM_FIELD_NAME_3",
      "validation": "string",
      "value": ""
    }
  ]
}
```

**Response Field Descriptions**

| Field                     | Type   | Description                                                                |
| ------------------------- | ------ | -------------------------------------------------------------------------- |
| `id`                      | GUID   | Unique ID of Template                                                      |
| `text`                    | string | Description text for Template                                              |
| `templateData`            | array  | List of additional fields required for this Template                       |
| `templateData.key`        | string | Name of the custom field                                                   |
| `templateData.validation` | string | Validation type or rules for the field in the form of a regular expression |
| `templateData.value`      | string | Default or empty value for the field                                       |

***

### Notes

* First, call **List Providers API** to get available providers and purposes.
* Use the `providerBusinessUnitId` and `purposeId` from that response to call **Provider Additional Fields API**.
* Only fields with primitive types (string, number, boolean) are returned.
* Include the Bearer token in all requests to authorize your calls.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.comcorp.co.za/askmefirst/supporting-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.