# Consent APIs

This API manages consents for clients on behalf of the requesting organization.\
It covers the following endpoints:

* [Consent Request](#consent-request)
* [Consent Status](#consent-status)
* [Consent Retry](#consent-retry)
* [Consent History](#consent-history)

### Consent Request

**Method:** POST\
**Path:** `/api/v1/consent/request`

**Description:** Creates a new consent request for a client.\
A JWT token is returned in the `consentToken` field, which can be used to fetch the status or retry the consent.

The optional `callback` object is used to receive asynchronous consent events (accept/decline/timeout). If no callback is specified, no event will be sent.

Values for `providerBusinessUnit`, `purpose`, `template`, and `templateData` can be retrieved from the [Supporting APIs](/askmefirst/supporting-apis.md).

#### Request

**Headers**

| Header                   | Value            | Required |
| ------------------------ | ---------------- | -------- |
| Authorization            | Bearer `<token>` | Yes      |
| x-requester-reference    | string           | Yes      |
| x-provider-business-unit | GUID             | Yes      |

**Header Field Descriptions**

<table><thead><tr><th width="233">Field</th><th width="124">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Bearer token</td><td>Yes</td><td>Auth Token retrieved from the <a href="/pages/BLkVVRJBLxODFOowClZ7">Authentication API</a></td></tr><tr><td><code>x-requester-reference</code></td><td>string</td><td>Yes</td><td>This is a unique reference in the Requester system to track the transaction</td></tr><tr><td><code>x-provider-business-unit</code></td><td>GUID</td><td>Yes</td><td>The Provider BusinessUnit selected for the Identity Provider, obtained from the <a href="/pages/9bFJsV3RShVBtWVAl9vh#list-identity-providers-api">Supporting APIs</a></td></tr></tbody></table>

**Body**

```json
{
  "candidate": {
    "firstName": "string",
    "lastName": "string",
    "identificationTypeId": 0,
    "identityNumber": "string"
  },
  "purpose": "00000000-0000-0000-0000-000000000000",
  "documentFromDate": "2026-05-07T09:23:26.786Z",
  "documentToDate": "2026-05-07T09:23:26.786Z",
  "template": {
    "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": ""
      }
    ]
  },
  "callback": {
    "url": "string",
    "headers": [
      {
        "key": "string",
        "value": "string"
      }
    ]
  }
}
```

**Request Field Descriptions**

<table><thead><tr><th width="277">Field</th><th width="100.39990234375">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>candidate.firstName</code></td><td>string</td><td>Yes</td><td>Client’s first name</td></tr><tr><td><code>candidate.lastName</code></td><td>string</td><td>Yes</td><td>Client’s last name</td></tr><tr><td><code>candidate.identificationTypeId</code></td><td>integer</td><td>Yes</td><td>Type of identification (e.g., passport, national ID)</td></tr><tr><td><code>candidate.identityNumber</code></td><td>string</td><td>Yes</td><td>Identification number</td></tr><tr><td><code>purpose</code></td><td>GUID</td><td>Yes</td><td>Purpose ID retrieved from the <a href="/pages/9bFJsV3RShVBtWVAl9vh#list-identity-providers-api">Supporting APIs</a></td></tr><tr><td><code>documentFromDate</code></td><td>DateTime</td><td>Yes</td><td>The date on which the document begins</td></tr><tr><td><code>documentToDate</code></td><td>DateTime</td><td>Yes</td><td>The date on which the document ends</td></tr><tr><td><code>template.id</code></td><td>GUID</td><td>Yes</td><td>Template ID from the <a href="/pages/9bFJsV3RShVBtWVAl9vh#provider-template-fields-api">Supporting APIs</a></td></tr><tr><td><code>template.text</code></td><td>string</td><td>Yes</td><td>Description of the template from the <a href="/pages/9bFJsV3RShVBtWVAl9vh#provider-template-fields-api">Supporting APIs</a></td></tr><tr><td><code>template.templateData</code></td><td>array</td><td>Yes</td><td>List of additional fields for the provider from the <a href="/pages/9bFJsV3RShVBtWVAl9vh#provider-template-fields-api">Supporting APIs</a>, update <code>value</code> with actual data</td></tr><tr><td><code>callback.url</code></td><td>string</td><td>No</td><td>URL to send consent event notifications</td></tr><tr><td><code>callback.headers</code></td><td>array</td><td>No</td><td>Optional custom headers for callback</td></tr><tr><td><code>callback.headers.key</code></td><td>string</td><td>Yes if callback is specified</td><td>Custom headers key for callback</td></tr><tr><td><code>callback.headers.value</code></td><td>string</td><td>Yes if callback is specified</td><td>Custom headers value for callback</td></tr></tbody></table>

#### Response

**Body**

```json
{
  "consentToken": "string"
}
```

**Response Field Descriptions**

<table><thead><tr><th width="140">Field</th><th width="90">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>consentToken</code></td><td>string</td><td>JWT token as described in <a href="https://datatracker.ietf.org/doc/html/rfc7519">RFC7519</a> representing the consent request; used for <a href="#consent-status">Consent Status</a> and <a href="#consent-retry">Consent Retry</a> APIs</td></tr></tbody></table>

***

### Consent Status

**Method:** POST\
**Path:** `/api/v1/consent/status`

**Description:** Retrieves the status of a consent request submitted via the [Consent Request](#consent-request) API.\
It also indicates if a retry of the consent is allowed, based on the status of the consent and how many retries have been attempted.

#### Request

**Headers**

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

**Header Field Descriptions**

<table><thead><tr><th width="136">Field</th><th width="122">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Bearer token</td><td>Yes</td><td>Auth Token retrieved from the <a href="/pages/BLkVVRJBLxODFOowClZ7">Authentication API</a></td></tr></tbody></table>

**Body**

```json
{
  "consentToken": "JWT"
}
```

**Request Field Descriptions**

<table data-full-width="true"><thead><tr><th width="126">Field</th><th width="87">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>consentToken</code></td><td>string</td><td>Yes</td><td>Consent Token retrieved from the <a href="#consent-request">Consent Request</a> API or <a href="#consent-retry">Consent Retry</a> API</td></tr></tbody></table>

#### Response

**Body**

```json
{
  "status": {
    "id": "00000000-0000-0000-0000-000000000000",
    "displayName": "string",
    "canRetry": true
  },
  "providerToken": "string"
}
```

**Response Field Descriptions**

| Field                | Type    | Description                                                                                     |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `status.id`          | GUID    | Unique ID of the current consent                                                                |
| `status.displayName` | string  | Human-readable status (e.g., Initial, Accepted, Declined)                                       |
| `status.canRetry`    | boolean | Indicates if retrying this consent is allowed                                                   |
| `providerToken`      | string  | Token issued by the Identity Provider for this consent request, only if the consent is Accepted |

**Status Field Descriptions**

<table><thead><tr><th width="331">Id</th><th width="238">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>13CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>Consent Granted</code></td><td>The client has granted explicit consent for the given request</td></tr><tr><td><code>23CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>Consent Declined</code></td><td>The client has explicity denied consent for the given request</td></tr><tr><td><code>33CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>No Response from customer</code></td><td>The client has failed to respond to the given request in time</td></tr><tr><td><code>43CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>Non Account Holder</code></td><td>The client does not hold an account with the chosen provider</td></tr><tr><td><code>53CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>Non mobile client</code></td><td>The client does not have a registered mobile device with the chosen provider</td></tr><tr><td><code>63CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>Request Failed</code></td><td>There was a failure submitting the given request with the provider</td></tr><tr><td><code>73CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>No Data Available</code></td><td>The provider does not have any data available for the client</td></tr><tr><td><code>83CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>Account Closed</code></td><td>The provider has indicated that the client's account is closed</td></tr><tr><td><code>93CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>Consent Sent</code></td><td>The request for consent has been successfully sent to the client and is awaiting a response</td></tr><tr><td><code>10CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>Business Account</code></td><td>The client holds a business account with the chosen provider</td></tr><tr><td><code>11CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>Identifier Not Found</code></td><td>The client identifier has not been captured in the provider system</td></tr><tr><td><code>90CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>IDP Offline</code></td><td>The provider is not reachable for the given request</td></tr><tr><td><code>91CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>Error at IDP</code></td><td>The provider has returned an error for the given request</td></tr><tr><td><code>99CD3DAD-FD28-4355-A156-0D7B01546EC6</code></td><td><code>System Error</code></td><td>An error has occurred within the AskMeFirst system</td></tr></tbody></table>

***

### Consent Retry

**Method:** POST\
**Path:** `/api/v1/consent/retry`

**Description:** Retries a prior consent request.\
This can only be used in specific scenarios (client did not respond or a recoverable error occurred).\
Maximum retries are defined per use case. And will be defined on onboarding.

A new, optional callback can be included in the body if the retry is an automated process and needs to be sent to a different endpoint. If no callback is provided, no callback will be sent.

#### Request

**Headers**

<table><thead><tr><th width="203">Header</th><th width="308">Value</th><th>Required</th></tr></thead><tbody><tr><td>Authorization</td><td>Bearer <code>&#x3C;Token></code></td><td>Yes</td></tr></tbody></table>

**Header Field Descriptions**

<table><thead><tr><th width="142">Field</th><th width="135">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Bearer token</td><td>Yes</td><td>Auth Token retrieved from the <a href="/pages/BLkVVRJBLxODFOowClZ7">Authentication API</a></td></tr></tbody></table>

**Body**

```json
{
  "consentToken": "JWT",
  "callback": {
    "url": "string",
    "headers": [
      {
        "key": "string",
        "value": "string"
      }
    ]
  }
}
```

**Request Field Descriptions**

<table><thead><tr><th width="213">Field</th><th width="81">Type</th><th width="109">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>consentToken</code></td><td>string</td><td>Yes</td><td>Consent Token retrieved from the <a href="#consent-request">Consent Request</a> or <a href="#consent-retry">Consent Retry</a> APIs</td></tr><tr><td><code>callback.url</code></td><td>string</td><td>No</td><td>URL to send consent event notifications</td></tr><tr><td><code>callback.headers</code></td><td>array</td><td>No</td><td>Optional custom headers for callback</td></tr><tr><td><code>callback.headers.key</code></td><td>string</td><td>Yes if callback is specified</td><td>Custom headers key for callback</td></tr><tr><td><code>callback.headers.value</code></td><td>string</td><td>Yes if callback is specified</td><td>Custom headers value for callback</td></tr></tbody></table>

#### Response

**Body**

```json
{
  "consentToken": "string"
}
```

**Response Field Descriptions**

<table><thead><tr><th width="135">Field</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>consentToken</code></td><td>string</td><td>New JWT token for the retried consent request</td></tr></tbody></table>

***

### Consent History

**Method:** GET\
**Path:** `/api/v1/consent/list`

**Description:** Lists all consent requests for the requesting organization (based on BusinessUnit in the auth token).

***

#### Request

**Headers**

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

**Header Field Descriptions**

<table><thead><tr><th width="137">Field</th><th width="125">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Bearer token</td><td>Yes</td><td>Auth Token retrieved from the <a href="/pages/BLkVVRJBLxODFOowClZ7">Authentication API</a></td></tr></tbody></table>

***

**Path Parameters**

<table><thead><tr><th width="140">Parameter</th><th width="140">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>page</code></td><td>number</td><td>The number of the page to fetch</td></tr><tr><td><code>pageSize</code></td><td>number</td><td>The number of entries to return for the given page</td></tr></tbody></table>

***

#### Response

**Body**

```json
{
  "pagination": {
    "page": 0,
    "pageSize": 0
  },
  "consents": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "purpose": {
        "id": "00000000-0000-0000-0000-000000000000",
        "displayName": "Example purpose"
      },
      "status": {
        "id": "00000000-0000-0000-0000-000000000000",
        "displayName": "Example status"
      },
      "provider": {
        "id": "00000000-0000-0000-0000-000000000000",
        "displayName": "Example provider"
      },
      "requester": {
        "id": "00000000-0000-0000-0000-000000000000",
        "displayName": "Example requester"
      },
      "requestedAt": "2026-01-27T08:11:30.557Z",
      "parentId": "00000000-0000-0000-0000-000000000000"
    },
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "purpose": {
        "id": "00000000-0000-0000-0000-000000000000",
        "displayName": "Example purpose"
      },
      "status": {
        "id": "00000000-0000-0000-0000-000000000000",
        "displayName": "Example status"
      },
      "provider": {
        "id": "00000000-0000-0000-0000-000000000000",
        "displayName": "Example provider"
      },
      "requester": {
        "id": "00000000-0000-0000-0000-000000000000",
        "displayName": "Example requester"
      },
      "requestedAt": "2026-01-27T08:11:30.557Z",
      "parentId": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
```

**Response Field Descriptions**

<table><thead><tr><th width="200">Field</th><th width="199">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>pagination</code></td><td>object</td><td>Pagination parameters of the request</td></tr><tr><td><code>id</code></td><td>GUID</td><td>Unique ID of the consent</td></tr><tr><td><code>purpose</code></td><td>object</td><td>Purpose of the consent request</td></tr><tr><td><code>status</code></td><td>object</td><td>Current status</td></tr><tr><td><code>provider</code></td><td>object</td><td>The provider involved</td></tr><tr><td><code>requester</code></td><td>object</td><td>The requesting organization</td></tr><tr><td><code>requestedAt</code></td><td>datetime</td><td>Timestamp when the consent was created</td></tr><tr><td><code>parentId</code></td><td>GUID</td><td>Unique ID of the parent consent</td></tr></tbody></table>

**Purpose Field Descriptions**

<table><thead><tr><th width="200">Field</th><th width="200">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>purpose.id</code></td><td>GUID</td><td>Unique ID of the purpose</td></tr><tr><td><code>purpose.displayName</code></td><td>string</td><td>A display-friendly name of the purpose</td></tr></tbody></table>

**Status Field Descriptions**

<table><thead><tr><th width="200">Field</th><th width="200">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>status.id</code></td><td>GUID</td><td>Unique ID of the status</td></tr><tr><td><code>status.displayName</code></td><td>string</td><td>A display-friendly name of the status</td></tr></tbody></table>

**Provider Field Descriptions**

<table><thead><tr><th width="200">Field</th><th width="200">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>provider.id</code></td><td>GUID</td><td>Unique ID of the provider</td></tr><tr><td><code>provider.displayName</code></td><td>string</td><td>A display-friendly name of the provider</td></tr></tbody></table>

**Requester Field Descriptions**

<table><thead><tr><th width="200">Field</th><th width="199">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>requester.id</code></td><td>GUID</td><td>Unique ID of the requester</td></tr><tr><td><code>requester.displayName</code></td><td>string</td><td>A display-friendly name of the requester</td></tr></tbody></table>

**Pagination Field Descriptions**

<table><thead><tr><th width="200">Field</th><th width="200">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>pagination.page</code></td><td>number</td><td>The number of the page to fetch.</td></tr><tr><td><code>pagination.pageSize</code></td><td>number</td><td>The number of entries to return for the given page.</td></tr></tbody></table>

***

### Notes

* Use the `consentToken` from Consent Request for Consent Status and Consent Retry.
* Values for `providerBusinessUnit`, `purpose`, `template`, and `templateData` must be fetched from [Supporting APIs](/askmefirst/supporting-apis.md).
* Callback URLs are optional and used for asynchronous consent events.
* All endpoints require Bearer authentication.


---

# 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/consent-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.