Consent Verification API

Verify consents via email, magic links, and tokens

APIs for verifying customer consents through various methods including email resend, magic links, and token verification.

Available Operations

Resend Verification

POST /resend

Send Magic Link

POST /send-magic-link

Verify Token

GET /verify/{token}

Accept Consent

POST /consents/{type}

Endpoints

POST /api/v2.1/customer/individual/{customerId}/consents/terms
POST /api/v2.1/customer/individual/{customerId}/consents/privacy
POST /api/v2.1/customer/individual/{customerId}/consents/data-processing
POST /api/v2.1/customer/organization/{organizationId}/consents/terms
POST /api/v2.1/customer/organization/{organizationId}/consents/privacy
POST /api/v2.1/customer/organization/{organizationId}/consents/data-processing

Request Body

accepted boolean body required

Whether the consent is accepted

Example: true

version string body required

Consent version

Example: "1.0"

Headers

X-Tenant-ID string header required

Tenant identifier

Authorization string header required

Bearer token for authentication

Content-Type string header required

Must be application/json

X-Forwarded-From string header required

Source identifier for request origin tracking

User-Agent string header required

Client application identifier — required by the global request filter

platform string header required

Client platform identifier. Also accepted as sec-ch-ua-platform

deviceId string header required

Unique device identifier for session tracking. Also accepted as X-Device-Id or device-id

Code Example

cURL

bash

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/de645b7b-219a-4fdf-bd59-a7bf454a0586/consents/terms" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: e2e-test-device" \
  -d '{
    "accepted": true,
    "version": "1.0"
  }'

Response

Response example

200

json

{
  "code": 200,
  "data": {
    "verificationId": "f778e9d2-9097-4328-9b76-8f225d48c9aa",
    "status": "PENDING",
    "verificationType": "CONSENT",
    "updatedAt": "2026-03-10T07:10:04.068Z",
    "updatedBy": "7e14ae4c-1e6c-4792-83f0-2263f2d13bce"
  },
  "message": "Success"
}

Resend Verification

Request

Authorization string header required

Bearer token for authentication

X-Tenant-ID string header required

Tenant identifier

customerId string body required

Customer identifier

consentId string body required

Consent identifier to verify

channel string body

Delivery channel: EMAIL, SMS (default: EMAIL)

Code Examples

cURL

bash

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/consent/verification/resend" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "customerId": "cust_12345",
    "consentId": "cons_67890",
    "channel": "EMAIL"
  }'

JavaScript

javascript

const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/consent/verification/resend',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    },
    body: JSON.stringify({
      customerId: 'cust_12345',
      consentId: 'cons_67890',
      channel: 'EMAIL'
    })
  }
);

const { data } = await response.json();
console.log('Verification sent:', data.sentAt);

Python

python

import requests

response = requests.post(
    'https://sandbox.finhub.cloud/api/v2.1/consent/verification/resend',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {access_token}',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
    },
    json={
        'customerId': 'cust_12345',
        'consentId': 'cons_67890',
        'channel': 'EMAIL'
    }
)

data = response.json()['data']
print(f"Verification sent at: {data['sentAt']}")

Response example

200

json

{
  "success": true,
  "data": {
    "customerId": "cust_12345",
    "consentId": "cons_67890",
    "channel": "EMAIL",
    "sentAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-01-15T11:30:00Z"
  }
}

429

json

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many verification requests. Please wait before trying again.",
    "retryAfter": 300
  }
}

Send Magic Link

Request

customerId string body required

Customer identifier

consentId string body required

Consent identifier to verify

redirectUrl string body

URL to redirect after verification (must be whitelisted)

expiresInMinutes integer body

Link expiration time in minutes (default: 60, max: 1440)

Code Examples

cURL

bash

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/consent/verification/send-magic-link" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "customerId": "cust_12345",
    "consentId": "cons_67890",
    "redirectUrl": "https://your-app.com/consent-confirmed",
    "expiresInMinutes": 60
  }'

JavaScript

javascript

const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/consent/verification/send-magic-link',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    },
    body: JSON.stringify({
      customerId: 'cust_12345',
      consentId: 'cons_67890',
      redirectUrl: 'https://your-app.com/consent-confirmed',
      expiresInMinutes: 60
    })
  }
);

const { data } = await response.json();
console.log('Magic link sent, expires:', data.expiresAt);

Python

python

import requests

response = requests.post(
    'https://sandbox.finhub.cloud/api/v2.1/consent/verification/send-magic-link',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {access_token}',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
    },
    json={
        'customerId': 'cust_12345',
        'consentId': 'cons_67890',
        'redirectUrl': 'https://your-app.com/consent-confirmed',
        'expiresInMinutes': 60
    }
)

data = response.json()['data']
print(f"Magic link expires: {data['expiresAt']}")

Response example

200

json

{
  "success": true,
  "data": {
    "customerId": "cust_12345",
    "consentId": "cons_67890",
    "sentTo": "j***@example.com",
    "sentAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-01-15T11:30:00Z"
  }
}

400

json

{
  "success": false,
  "error": {
    "code": "INVALID_REDIRECT_URL",
    "message": "Redirect URL is not whitelisted for this tenant"
  }
}

Verify Token

Request

token string path required

Verification token from email or magic link

X-Tenant-ID string header required

Tenant identifier

Code Examples

cURL

bash

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/consent/verification/verify/eyJhbGciOiJIUzI1NiIs..." \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"

JavaScript

javascript

const token = 'eyJhbGciOiJIUzI1NiIs...';

const response = await fetch(
  `https://sandbox.finhub.cloud/api/v2.1/consent/verification/verify/${token}`,
  {
    headers: {
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    }
  }
);

const { data } = await response.json();
if (data.verified) {
  console.log('Consent verified successfully!');
  console.log('Redirect to:', data.redirectUrl);
}

Python

python

import requests

token = 'eyJhbGciOiJIUzI1NiIs...'

response = requests.get(
    f'https://sandbox.finhub.cloud/api/v2.1/consent/verification/verify/{token}',
    headers={
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
    }
)

data = response.json()['data']
if data['verified']:
    print('Consent verified successfully!')
    print(f"Redirect to: {data['redirectUrl']}")

Response example

200

json

{
  "success": true,
  "data": {
    "verified": true,
    "customerId": "cust_12345",
    "consentId": "cons_67890",
    "consentType": "TERMS",
    "verifiedAt": "2024-01-15T10:35:00Z",
    "redirectUrl": "https://your-app.com/consent-confirmed"
  }
}

400

json

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Verification token is invalid or malformed"
  }
}

410

json

{
  "success": false,
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Verification token has expired"
  }
}

Verification Flow

Request Verification

Call /resend or /send-magic-link to send verification to customer
Customer Clicks Link

Customer receives email and clicks the verification link
Token Validation

System validates the token via /verify/{token}
Consent Confirmed

Consent status updated to ACCEPTED and customer redirected

Delivery Channels

Channel	Description
`EMAIL`	Verification sent via email
`SMS`	Verification sent via SMS (if enabled)

Response Codes

Code	Description
`200`	Operation successful
`400`	Invalid request data or token
`401`	Not Authorized
`403`	Not Allowed
`404`	Consent or customer not found
`410`	Token expired
`429`	Rate limit exceeded
`500`	Internal server error