Quickstart

In this guide, you create an API key in the Flowmask console. Then you send a text with a name, a phone number, and an email address to the Check API. The Check API marks the text UNSAFE and returns a masked copy.

To run the samples, you need one of these tools:

• curl
• Python 3 with the requests package
• Node.js 18 or later

Sign in to the console of your regionCopy Anchor Link

Open the console of the region that holds your workspace.

On your first sign-in, the console creates your account. Then you create your workspace.

1. Enter your email, then click Continue.
2. Enter the code from the email, then click Continue. The code is valid for 10 minutes.
3. Enter a display name, or leave it empty, then click Continue.
4. Enter a workspace name, then click Create workspace.

The person who creates a workspace is its Owner.

Create an API keyCopy Anchor Link

Only an Owner of the workspace can create an API key. If you are a Member, ask an Owner to create a key for you.

1. In the sidebar, click API keys.
2. Click Create API key.
3. In Key name, enter a name that says where the key runs, such as billing-server. The name can have up to 50 characters.
4. Click Create.
5. In the API key created dialog, click Copy key.

Set the environment variableCopy Anchor Link

The samples send the request to https://api.jp.flowmask.ai/api/v1/check and read the key from the FLOWMASK_API_KEY environment variable. Set it in the shell where you run the samples. Replace the value with your key.

export FLOWMASK_API_KEY="fm_key_xxxxxxxx"

Keep the key on your server. The Check API sends no CORS headers, so a browser blocks every call from a web page. Authentication explains how to keep the key safe.

Send your first requestCopy Anchor Link

The sample sends a text that contains a name, a phone number, and an email address. All three are fake.

curl -sS -X POST https://api.jp.flowmask.ai/api/v1/check \
  -H "Authorization: Bearer $FLOWMASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Contact Nguyễn Văn An at 0912 345 678 or [email protected]."}'

To run the Python sample, install requests with python3 -m pip install requests, then run python3 check.py. To run the JavaScript sample, run node check.mjs.

The Python and JavaScript samples read the body as JSON only when the Content-Type of the response is application/json. The network in front of the Check API can answer with a body that is not JSON, such as a 403 or an HTML 502. The samples then print the status and the start of the body. See Answers outside the envelope.

Read the resultCopy Anchor Link

The Check API answers 200. The body looks like this sample.

{
  "data": {
    "result": "UNSAFE",
    "confidence": 0.97,
    "findings": [
      {
        "text": "Nguyễn Văn An",
        "start": 8,
        "end": 21,
        "type": "person",
        "group": "BASIC"
      },
      {
        "text": "0912 345 678",
        "start": 25,
        "end": 37,
        "type": "phone_number",
        "group": "BASIC"
      },
      {
        "text": "[email protected]",
        "start": 41,
        "end": 62,
        "type": "email_address",
        "group": "BASIC"
      }
    ],
    "maskedText": "Contact [PERSON] at [PHONE] or [EMAIL].",
    "inputTokens": 66,
    "characters": 63,
    "requestId": "req_01M6JY9PD89FTH4BSM8NACAEYY",
    "region": "JP",
    "apiVersion": "v1"
  },
  "code": "http.200",
  "message": "OK"
}

• result is UNSAFE, because the text contains personal data.
• findings has one item for the name, one for the phone number, and one for the email address. start and end count Unicode code points from the start of the text.
• maskedText replaces each finding with the mask label of its type.
• inputTokens is the number that the monthly quota counts for this request.

Your requestId is different. Your region is JP if your workspace is in Japan. The model decides the findings, so your findings and confidence can differ from the sample.

Choose the data types to look forCopy Anchor Link

A new workspace looks for 7 data types. An Owner changes the list on the Settings page. In the Detection section, click Edit data types, turn types on or off, then click Save. The list applies to every key of the workspace. A change reaches the Check API within 1 minute.

Data types lists all 48 types and the 7 that are on in a new workspace.

Next stepsCopy Anchor Link

• Check text describes every field of the request and the response.
• Errors lists each error and what your app should do about it.
• Rate limits and quota explains the limits that all keys of a workspace share.