Skip to main content
GET
/
health
Health Check
curl --request GET \
  --url https://api.example.com/health
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

FieldTypeDescription
statusstringAlways "ok" when service is running
servicestringService identifier: "kyc-health"
check_typestringType of check: "liveness"
timestampstringISO 8601 timestamp of the check
cold_startbooleantrue if this was a cold Lambda start
function_namestringAWS Lambda function name
function_versionstringLambda function version
request_idstringUnique request identifier

​
Status Codes

CodeDescription
200Service is healthy and responding
500Service 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

FieldTypeDescription
statusstringOverall status: "healthy" or "degraded"
servicestringService identifier: "kyc-health"
check_typestringType of check: "readiness"
timestampstringISO 8601 timestamp of the check
cold_startbooleantrue if this was a cold Lambda start
dependenciesobjectStatus of each dependency (S3, DynamoDB)

​
Dependency Status Fields

Each dependency includes:
FieldTypeDescription
statusstring"healthy" or "unhealthy"
servicestringService name ("s3" or "dynamodb")
messagestringHuman-readable status message
errorstringError code (only present if unhealthy)

​
Status Codes

CodeDescription
200Readiness check completed (may be healthy or degraded)
403Forbidden - Missing health:readiness_check permission
401Unauthorized - 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)