Privacy Policy API

This documentation provides comprehensive details for the Privacy Policy API endpoints. The API supports creating, retrieving, updating, and managing privacy policies and terms of conditions within the platform. Policies can be versioned, activated/deactivated, and managed by administrators.

Base URL: http://localhost:8080

Authentication

Most Policy endpoints require Bearer token authentication. Include the access token in the Authorization header:

Authorization: Bearer <your_access_token>

Policy Endpoints

Method	Endpoint	Description	Authentication Required
`GET`	`/api/v1/policies/{policyType}`	Retrieve latest active policy by type	No
`POST`	`/api/v1/admin/policies`	Create a new policy or version	Yes (Admin)
`GET`	`/api/v1/admin/policies/{type}/history`	Retrieve all versions of a policy type	Yes (Admin)

Endpoint Details

1. Get All Policies

GET /api/v1/policies/{policyType}

Retrieve a list of all policies including Privacy Policies and Terms & Conditions.

Headers

Header	Value	Required
`accept`	`application/json`	Yes

Example Request

curl -X 'GET' \
  'http://localhost:8080/api/v1/policies/PRIVACY_POLICY' \
  -H 'accept: application/json'

Example Response

[
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "PRIVACY_POLICY",
      "title": "Privacy Policy",
      "content": "This is our privacy policy...",
      "version": "1.0",
      "effectiveDate": "2023-01-01T00:00:00Z",
      "isActive": true,
      "createdAt": "2023-01-01T00:00:00Z",
      "updatedAt": "2023-01-01T00:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "type": "TERMS_CONDITIONS",
      "title": "Terms and Conditions",
      "content": "These are our terms and conditions...",
      "version": "1.0",
      "effectiveDate": "2023-01-01T00:00:00Z",
      "isActive": true,
      "createdAt": "2023-01-01T00:00:00Z",
      "updatedAt": "2023-01-01T00:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
`data`	array	Array of policy objects
`data[].id`	string	Unique identifier for the policy
`data[].type`	string	Policy type (PRIVACY_POLICY, TERMS_CONDITIONS)
`data[].title`	string	Title of the policy
`data[].content`	string	Full content of the policy
`data[].version`	string	Version number of the policy
`data[].effectiveDate`	string	ISO 8601 date when policy becomes effective
`data[].isActive`	boolean	Whether the policy is currently active
`data[].createdAt`	string	ISO 8601 timestamp of creation
`data[].updatedAt`	string	ISO 8601 timestamp of last update

2. Get Policy by Type

GET /api/v1/policies/{policyType}

Retrieve a specific policy by its type (PRIVACY_POLICY or TERMS_CONDITIONS).

Path Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Policy type (PRIVACY_POLICY or TERMS_CONDITIONS)

Headers

Header	Value	Required
`accept`	`application/json`	Yes

Example Request

curl -X 'GET' \
  'http://localhost:8080/api/v1/policies/PRIVACY_POLICY' \
  -H 'accept: application/json'

Example Response

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "PRIVACY_POLICY",
    "title": "Privacy Policy",
    "content": "This is our privacy policy...",
    "version": "1.0",
    "effectiveDate": "2023-01-01T00:00:00Z",
    "isActive": true,
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z"
  }
}

Response Fields

Field	Type	Description
`data.id`	string	Unique identifier for the policy
`data.type`	string	Policy type
`data.title`	string	Title of the policy
`data.content`	string	Full content of the policy
`data.version`	string	Version number of the policy
`data.effectiveDate`	string	ISO 8601 date when policy becomes effective
`data.isActive`	boolean	Whether the policy is currently active
`data.createdAt`	string	ISO 8601 timestamp of creation
`data.updatedAt`	string	ISO 8601 timestamp of last update

4. Create Policy

POST /api/v1/admin/policies

Create a new policy with specified type, title, content, version, and effective date.

Headers

Header	Value	Required
`accept`	`application/json`	Yes
`Authorization`	`Bearer <access_token>`	Yes
`Content-Type`	`application/json`	Yes

Request Body

Field	Type	Required	Description
`type`	string	Yes	Policy type (PRIVACY_POLICY or TERMS_CONDITIONS)
`title`	string	Yes	Title of the policy
`content`	string	Yes	Full content of the policy
`version`	string	Yes	Version number of the policy
`effectiveDate`	string	Yes	ISO 8601 date when policy becomes effective

Example Request

curl -X 'POST' \
  'http://localhost:8080/api/v1/admin/policies' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "PRIVACY_POLICY",
  "title": "Updated Privacy Policy",
  "content": "This is our updated privacy policy...",
  "version": "1.1",
  "effectiveDate": "2023-06-15T00:00:00Z"
}'

Example Response

{
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "type": "PRIVACY_POLICY",
    "title": "Updated Privacy Policy",
    "content": "This is our updated privacy policy...",
    "version": "1.1",
    "effectiveDate": "2023-06-15T00:00:00Z",
    "isActive": true
  }
}

Response Fields

Field	Type	Description
`data.id`	string	Unique identifier for the created policy
`data.type`	string	Policy type
`data.title`	string	Title of the policy
`data.content`	string	Full content of the policy
`data.version`	string	Version number of the policy
`data.effectiveDate`	string	ISO 8601 date when policy becomes effective
`data.isActive`	boolean	Whether the policy is currently active (defaults to true)

6. Get Policy History

GET /api/v1/admin/policies/{type}/history

Get policy version history

Path Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Policy type (PRIVACY_POLICY or TERMS_CONDITIONS)

Headers

Header	Value	Required
`accept`	`application/json`	Yes
`Authorization`	`Bearer <access_token>`	Yes

Example Request

curl -X 'GET' \
  'http://localhost:8080/api/v1/admin/policies/PRIVACY_POLICY/history' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Example Response

{
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "type": "PRIVACY_POLICY",
    "title": "Updated Privacy Policy v2",
    "content": "This is our further updated privacy policy...",
    "version": "1.2",
    "effectiveDate": "2023-07-01T00:00:00Z",
    "isActive": false
  }
}

Response Fields

Field	Type	Description
`data.id`	string	Unique identifier of the deactivated policy
`data.type`	string	Policy type
`data.title`	string	Title of the policy
`data.content`	string	Content of the policy
`data.version`	string	Version number
`data.effectiveDate`	string	Effective date
`data.isActive`	boolean	Whether the policy is active (will be false)

Method	Endpoint	Description	Authentication Required
`POST`	`/api/v1/policy-consents/consent`	Create a new policy consent record	Yes

POST /api/v1/policy-consents/consent

Create a new consent record when a user agrees to a privacy policy. This endpoint captures the policy ID and user information for audit purposes.

Headers

Header	Value	Required
`Authorization`	`Bearer <access_token>`	Yes
`Content-Type`	`application/json`	Yes

Request Body

Field	Type	Required	Description
`policyId`	string	Yes	UUID of the policy being consented to

Example Request

curl -X 'POST' \
  'http://localhost:8080/api/v1/policy-consents/consent' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
  "policyId": "550e8400-e29b-41d4-a716-446655440000"
}'

Example Response

{
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "userId": "a67fd0cc-3d92-4259-bbd4-1e0ba49dece4",
    "policyId": "550e8400-e29b-41d4-a716-446655440000",
    "ipAddress": "127.0.0.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "consentedAt": "2023-06-15T10:30:00Z"
  }
}

Response Fields

Field	Type	Description
`id`	string	Unique identifier for the created consent record
`userId`	string	UUID of the user who provided consent
`policyId`	string	UUID of the policy that was consented to
`ipAddress`	string	IP address from which consent was given
`userAgent`	string	Browser user agent when consent was provided
`consentedAt`	string	ISO 8601 timestamp when consent was recorded

Error Handling

This API follows industry-standard error handling patterns (Stripe, GitHub, OpenAI):

Success Responses

HTTP status code indicates success (200, 201, 204)
Response body contains data directly (no wrapper object)
No isSuccess or statusCode fields needed

Error Responses

Standard Error (400/401/403/404/500):

{
  "message": "Error description"
}

Validation Error (400):

{
  "message": "Validation failed",
  "errors": [
    {"field": "email", "message": "Invalid email format"},
    {"field": "password", "message": "Password must be at least 8 characters"}
  ]
}

Common Error Codes

Status Code	Description	Example Message
`400`	Bad Request	`"Invalid email or password"`
`401`	Unauthorized	`"Authentication required"`
`403`	Forbidden	`"Insufficient permissions"`
`404`	Not Found	`"Product not found"`
`409`	Conflict	`"User already exists with this email"`
`500`	Internal Server Error	`"Internal server error"`

All error messages are centralized and consistent across all endpoints.

Business Rules

Policy ID must reference an existing policy in the system
User consent is automatically linked to the authenticated user
IP address and user agent are captured automatically from the request
Duplicate consent records for the same policy may be prevented

Data Privacy

Consent records serve as legal documentation for compliance
IP addresses and user agents are stored for audit purposes
Consent timestamps use ISO 8601 format in UTC

Policy Types

Common policy types supported by the system:

Policy Type	Description
`PRIVACY_POLICY`	Privacy policy consent
`TERMS_OF_SERVICE`	Terms of service agreement
`COOKIE_POLICY`	Cookie usage consent
`MARKETING_CONSENT`	Marketing communication consent

Privacy Policy API

Authentication

Policy Endpoints

Endpoint Details

1. Get All Policies

Headers

Example Request

Example Response

Response Fields

2. Get Policy by Type

Path Parameters

Headers

Example Request

Example Response

Response Fields

4. Create Policy

Headers

Request Body

Example Request

Example Response

Response Fields

6. Get Policy History

Path Parameters

Headers

Example Request

Example Response

Response Fields

Policy Consent Endpoints

Policy Consent Endpoints Table

7. Create Policy Consent

Headers

Request Body

Example Request

Example Response

Response Fields

Error Handling

Success Responses

Error Responses

Common Error Codes

Business Rules

Consent Creation

Data Privacy

Policy Types