Developer Resources

Codata API Guide: Understanding Pet Request & Response Structure

Codata Technical Team

December 6, 2024

12 min read

A comprehensive technical guide on how to structure API requests for Codata's privacy-enhancing technologies, including detailed JSON examples for data columns, masking options, and chart analysis configurations.

Integrating with Codata's Privacy-Enhancing Technologies (PETs) API is straightforward but requires understanding the specific JSON structure for data submission and analysis configuration. This guide walks you through a complete request and response cycle, explaining how to send data for processing and how to interpret the results including masked data and statistical analysis.

API Request Structure

The API expects a JSON payload containing the raw data, the column-specific options for PETs application, and the desired chart analysis for visualization. Below is a complete example of a request body.

{
  "data": {
    "columns": [
      "name",
      "age",
      "credit_score",
      "transaction_amount"    
    ],
    "rows": [
      {
        "name": "Alice Green", 
        "age": 34, 
        "credit_score": 720, 
        "transaction_amount": 1500
      }
    ]
  },
  "column_options": [
    { "name": "name", "method": "Pseudonym" },
    { "name": "credit_score", "method": "Random Tokenization", "level": 2 },
    { "name": "transaction_amount", "method": "Generalization", "level": 3 }
  ],
  "column_analysis": {
    "age": "histogram",
    "credit_score": "line chart",
    "transaction_amount": "pie chart"
  }
}

Understanding Request Parameters

The request is divided into three main components:

data: Contains the "columns" array and the "rows" array with the actual dataset.

column_options: Specifies which privacy method (Pseudonym, Random Tokenization, Generalization) to apply to each column.

column_analysis: Defines which type of chart (histogram, line chart, pie chart) should be generated for specific columns.

API Response Structure

Upon successful processing, the API returns a JSON object containing the masked data, statistical analysis, and applied methods. Here is what the response looks like for the request above:

{
    "success": true,
    "message": "Data processed successfully with PETs (1 rows)",
    "processed_data": {
        "masked_data": {
            "columns": [
                "name",
                "age",
                "credit_score",
                "transaction_amount"
            ],
            "rows": [
                {
                    "name": "Shawn Wilson",
                    "age": 34,
                    "credit_score": "1b18fd06e92c... (truncated)",
                    "transaction_amount": "1500"
                }
            ]
        },
        "statistics": {
            "total_rows": 1,
            "total_columns": 4,
            "columns": {
                "name": {
                    "count": 1,
                    "null_count": 0,
                    "unique_count": 1,
                    "data_type": "categorical"
                },
                "age": {
                    "count": 1,
                    "null_count": 0,
                    "unique_count": 1,
                    "mean": 34.0,
                    "std": null,
                    "min": 34.0,
                    "max": 34.0,
                    "data_type": "numeric"
                },
                "credit_score": {
                    "count": 1,
                    "null_count": 0,
                    "unique_count": 1,
                    "mean": 720.0,
                    "std": null,
                    "min": 720.0,
                    "max": 720.0,
                    "data_type": "numeric"
                },
                "transaction_amount": {
                    "count": 1,
                    "null_count": 0,
                    "unique_count": 1,
                    "mean": 1500.0,
                    "std": null,
                    "min": 1500.0,
                    "max": 1500.0,
                    "data_type": "numeric"
                }
            }
        },
        "applied_methods": {
            "name": "Pseudonym",
            "credit_score": "Random Tokenization",
            "transaction_amount": "Generalization"
        },
        "processing_timestamp": "2025-12-06T17:47:42.518742",
        "rows_processed": 1,
        "status": "processed",
        "saved_to_database": false,
        "file_id": null,
        "analysis_id": null
    },
    "subscription_info": {
        "remaining_calls": 4,
        "calls_used": 1,
        "plan": "Business",
        "expires_at": "2026-06-04T13:04:10"
    }
}

Interpreting the Response

The response provides not just the secure data but also valuable metadata:

masked_data: The processed dataset safe for analytics or sharing.

statistics: Detailed distribution stats for each column (mean, min, max, null counts).

subscription_info: Real-time tracking of your API usage and plan limits.

applied_methods: Confirmation of which PETs were applied to which fields.

Conclusion

By structuring your requests according to this guide, you can leverage the full power of Codata's privacy engine. The API is designed to be self-documenting in its response, providing you with all the necessary statistical context alongside the secured data.

Ready to integrate? Check out our full API reference documentation or contact support for a dedicated integration session.

Share This Article

Privacy Technology

CodataSearch: Revolutionary Encrypted Search Technology for Sensitive Data

Learn how CodataSearch enables secure, encrypted search across sensitive data without ever decrypting it, maintaining complete privacy and PDPL compliance.