FocusOne Logo
Public documentation

Masking Service API

A practical reference for masking JSON records and Excel workbooks.

API version v1Base URL /api/v1 API status Operational
OpenAPI JSON Postman collection

Getting started

Create a scoped key, send it as a Bearer token, and start with a copyable request.

1

Create an API key in Settings

2

Choose only the scopes you need

3

Send your first request with cURL

Use Authorization: Bearer <API_SECRET_KEY>. Never send a key in a query string.
Authorization: Bearer <API_SECRET_KEY>
Open API key settings

Authentication and errors

Every error uses an error.code and human-readable error.message. Use the code for programmatic handling.

The key stays in memory for this page only and is never added to the URL.
JSON accepts up to 50,000 records and 10 MiB per request. XLSX uploads are limited to 800 MiB. Presigned upload URLs expire after 15 minutes.
The current V3 result URL may be a directly readable public S3 path. Treat it as sensitive and share it carefully.

Quickstart

Choose a flow and follow the smallest working example.

EndpointsJSON API
POST/api/v1/json/mask

Mask JSON scalar fields

Replace selected values with generated IDs and save mappings for later unmasking.

Required scope: json:mask

Headers

Authorization: Bearer <API_SECRET_KEY>Content-Type: application/jsonIdempotency-Key: unique-request-id

Response

3 documented response variants

200400402

Request Schema

Example

FieldTypeRequiredDescriptionExampleConstraint
dataarray<object>YesRecords to transform.[{"customerCode":"C001","amount":120}]1–50,000 records; scalar values only.
config.fieldsstring[]YesColumn names to mask.["customerCode"]1–10 unique field names.
config.codeGeneration.modeenumYesID generation strategy.running_numberrunning_number or random_token.
config.codeGeneration.paddingLengthintegerNoRunning number width.81–32 when running_number is used.
config.codeGeneration.tokenLengthintegerNoRandom token length.108–32 when random_token is used.

Code samples

POST /json/mask

curl -X POST "$BASE_URL/json/mask" -H "Authorization: Bearer $MASKING_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: json-mask-001" --data '{
  "data": [
    {
      "customerCode": "C001",
      "amount": 120
    }
  ],
  "config": {
    "fields": [
      "customerCode"
    ],
    "codeGeneration": {
      "mode": "running_number",
      "paddingLength": 8
    }
  }
}'

Response

Every error uses an error.code and human-readable error.message. Use the code for programmatic handling.

200

Masking completed synchronously.

{
  "jobId": "5c6d2c85-5a70-4bd9-a8d5-3e2dba7d1f0c",
  "status": "ready",
  "expiresAt": "2026-09-10T12:00:00.000Z",
  "usage": {
    "records": 1,
    "maskedFields": 1,
    "creditsConsumed": 1
  },
  "data": [
    {
      "customerCode": "CU-00000001",
      "amount": 120
    }
  ]
}
400

The request body is invalid.

{
  "error": { "code": "VALIDATION_ERROR", "message": "Invalid JSON mask request." }
}
402

The account has insufficient credits.

{
  "error": { "code": "INSUFFICIENT_CREDITS", "message": "JSON masking could not be completed." }
}

Limits

JSON accepts up to 50,000 records and 10 MiB per request. XLSX uploads are limited to 800 MiB. Presigned upload URLs expire after 15 minutes.

Download