Health Check

Health Check

curl --request GET \
  --url https://api.example.com/health

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/health",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/health"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/health")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

GET

health

Health Check

curl --request GET \
  --url https://api.example.com/health

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/health",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/health"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/health")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

The health check endpoint provides a quick way to verify that the KYC API service is running and responsive.

Endpoint

GET /health

Authentication

No authentication required. This endpoint is publicly accessible for monitoring purposes.

Description

This endpoint performs a basic liveness check. It’s suitable for:

Service availability monitoring
Integration health verification
Uptime monitoring
Deployment verification

Request Example

curl https://stg.kyc.legaltalent.ai/health

Response Format

Success Response

{
  "status": "ok",
  "service": "kyc-health",
  "check_type": "liveness",
  "timestamp": "2024-11-22T10:30:00Z",
  "cold_start": false,
  "function_name": "kyc-health-develop",
  "function_version": "$LATEST",
  "request_id": "abc-123-def"
}

Response Fields

Field	Type	Description
`status`	string	Always `"ok"` when service is running
`service`	string	Service identifier: `"kyc-health"`
`check_type`	string	Type of check: `"liveness"`
`timestamp`	string	ISO 8601 timestamp of the check
`cold_start`	boolean	`true` if this was a cold Lambda start
`function_name`	string	AWS Lambda function name
`function_version`	string	Lambda function version
`request_id`	string	Unique request identifier

Status Codes

Code	Description
200	Service is healthy and responding
500	Service is unavailable (should not occur if service is running)

Use Cases

Load Balancer Configuration

Configure your load balancer to poll this endpoint:

Health Check URL: /health
Interval: 30 seconds
Timeout: 5 seconds
Healthy Threshold: 2
Unhealthy Threshold: 3

Monitoring Integration

Use this endpoint with monitoring tools:

# Example monitoring script
while true; do
  response=$(curl -s -o /dev/null -w "%{http_code}" https://stg.kyc.legaltalent.ai/health)
  if [ "$response" != "200" ]; then
    echo "Health check failed: HTTP $response"
    # Send alert
  fi
  sleep 60
done

Deployment Verification

After integration, verify the service is accessible:

curl -f https://stg.kyc.legaltalent.ai/health || echo "Service unavailable"

Readiness Check

The readiness endpoint performs a deeper health check that verifies dependencies (S3, DynamoDB) are accessible.

Endpoint

GET /health/ready

Authentication

Requires health:readiness_check permission. Include your Bearer token in the Authorization header.

Description

This endpoint performs a readiness check that verifies:

S3 bucket accessibility (watchlist snapshots)
DynamoDB table accessibility (watchlists)
Overall service readiness

Use this endpoint for:

Pre-deployment verification
Dependency health monitoring
Service readiness confirmation

Request Example

curl https://stg.kyc.legaltalent.ai/health/ready \
    -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "status": "healthy",
  "service": "kyc-health",
  "check_type": "readiness",
  "timestamp": "2024-11-22T10:30:00Z",
  "cold_start": false,
  "dependencies": {
    "s3": {
      "status": "healthy",
      "service": "s3",
      "bucket": "kyc-watchlists-snapshots-develop",
      "message": "S3 bucket accessible"
    },
    "dynamodb": {
      "status": "healthy",
      "service": "dynamodb",
      "table": "kyc-watchlists-develop",
      "message": "DynamoDB table accessible"
    }
  },
  "function_name": "kyc-health-develop",
  "function_version": "$LATEST",
  "request_id": "abc-123-def"
}

Degraded Status Response

If any dependency is unhealthy, the overall status will be "degraded":

{
  "status": "degraded",
  "service": "kyc-health",
  "check_type": "readiness",
  "timestamp": "2024-11-22T10:30:00Z",
  "dependencies": {
    "s3": {
      "status": "healthy",
      "service": "s3",
      "bucket": "kyc-watchlists-snapshots-develop",
      "message": "S3 bucket accessible"
    },
    "dynamodb": {
      "status": "unhealthy",
      "service": "dynamodb",
      "table": "kyc-watchlists-develop",
      "error": "ResourceNotFoundException",
      "message": "DynamoDB table not accessible: ResourceNotFoundException"
    }
  }
}

Response Fields

Field	Type	Description
`status`	string	Overall status: `"healthy"` or `"degraded"`
`service`	string	Service identifier: `"kyc-health"`
`check_type`	string	Type of check: `"readiness"`
`timestamp`	string	ISO 8601 timestamp of the check
`cold_start`	boolean	`true` if this was a cold Lambda start
`dependencies`	object	Status of each dependency (S3, DynamoDB)

Dependency Status Fields

Each dependency includes:

Field	Type	Description
`status`	string	`"healthy"` or `"unhealthy"`
`service`	string	Service name (`"s3"` or `"dynamodb"`)
`message`	string	Human-readable status message
`error`	string	Error code (only present if unhealthy)

Status Codes

Code	Description
200	Readiness check completed (may be healthy or degraded)
403	Forbidden - Missing `health:readiness_check` permission
401	Unauthorized - Missing or invalid token

Use Cases

Pre-Deployment Verification

# Verify service is ready before deployment
curl -f https://stg.kyc.legaltalent.ai/health/ready \
  -H "Authorization: Bearer YOUR_TOKEN" || exit 1

Monitoring Integration

# Check readiness in monitoring script
response=$(curl -s https://stg.kyc.legaltalent.ai/health/ready \
  -H "Authorization: Bearer YOUR_TOKEN")
status=$(echo $response | jq -r '.status')

if [ "$status" != "healthy" ]; then
  echo "Service degraded: $response"
  # Send alert
fi

Implementation Notes

No Caching: Each request performs a fresh check
Public Access: /health endpoint requires no authentication (by design for monitoring)
Authenticated Access: /health/ready requires health:readiness_check permission
Always Available: Returns 200 OK when the service is operational (status may be healthy or degraded)

Overview

Compliance Screening

AI Analysis

Batch Processing

KYC Workflows & Sessions

Webhooks

Tenant Management

Watchlists

Reporting & Analytics

Monitoring

Endpoint

Authentication

Description

Request Example

Response Format

Success Response

Response Fields

Status Codes

Use Cases

Load Balancer Configuration

Monitoring Integration

Deployment Verification

Readiness Check

Endpoint

Authentication

Description

Request Example

Response Format

Degraded Status Response

Response Fields

Dependency Status Fields

Status Codes

Use Cases

Pre-Deployment Verification

Monitoring Integration

Implementation Notes

​Endpoint

​Authentication

​Description

​Request Example

​Response Format

​Success Response

​Response Fields

​Status Codes

​Use Cases

​Load Balancer Configuration

​Monitoring Integration

​Deployment Verification

​Readiness Check

​Endpoint

​Authentication

​Description

​Request Example

​Response Format

​Degraded Status Response

​Response Fields

​Dependency Status Fields

​Status Codes

​Use Cases

​Pre-Deployment Verification

​Monitoring Integration

​Implementation Notes

Endpoint

Authentication

Description

Request Example

Response Format

Success Response

Response Fields

Status Codes

Use Cases

Load Balancer Configuration

Monitoring Integration

Deployment Verification

Readiness Check

Endpoint

Authentication

Description

Request Example

Response Format

Degraded Status Response

Response Fields

Dependency Status Fields

Status Codes

Use Cases

Pre-Deployment Verification

Monitoring Integration

Implementation Notes