Key Format

List key formats

get

Returns all configured key formats used by API-side key validation. Each item describes a keyId and its constraints: formatType (CPF, TITULO, REGEX, ALPHANUMERIC, ALPHABETIC, NUMERIC), optional regex (when formatType=REGEX), and optional minLength/maxLength. Use this endpoint to inspect which formats are currently enforced by the API during enroll/update when key-format validation is enabled.

Responses

200

OK

application/json

get

/keyFormat

HTTPcURLJavaScriptPython

GET /gbds/v2/keyFormat HTTP/1.1
Host: <ip>:8085
Accept: */*

200

OK

{
  "httpResponse": {
    "httpCode": 1,
    "body": "text"
  },
  "data": [
    {
      "keyId": "text",
      "formatType": "TITULO",
      "regex": "text",
      "minLength": 1,
      "maxLength": 1
    }
  ]
}

Create or update key formats

post

Creates or updates one or more key-format definitions. Required fields are keyId and formatType. When formatType=REGEX, the regex field is required. minLength and maxLength are optional. Newly created definitions return 201 Created, while existing definitions return 202 Accepted. These formats are used when key-format validation is enabled for enroll/update.

Body

application/json

keyIdstringOptional

formatTypestring · enumOptionalPossible values:

regexstringOptional

minLengthinteger · int32Optional

maxLengthinteger · int32Optional

Responses

201

CREATED

application/json

202

ACCEPTED

application/json

post

/keyFormat

HTTPcURLJavaScriptPython

POST /gbds/v2/keyFormat HTTP/1.1
Host: <ip>:8085
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "keyId": "text",
  "formatType": "TITULO",
  "regex": "text",
  "minLength": 1,
  "maxLength": 1
}

{}

Get key format

get

Retrieves the configured key-format definition for a specific keyId. The response includes the formatType and any additional constraints (regex, minLength, maxLength). Use this to validate client payloads against server-side requirements and to understand how a specific key will be checked during enroll/update.

Path parameters

keyIdstringRequired

Responses

200

OK

application/json

get

/keyFormat/{keyId}

HTTPcURLJavaScriptPython

GET /gbds/v2/keyFormat/{keyId} HTTP/1.1
Host: <ip>:8085
Accept: */*

200

OK

{
  "httpResponse": {
    "httpCode": 1,
    "body": "text"
  },
  "data": {
    "keyId": "text",
    "formatType": "TITULO",
    "regex": "text",
    "minLength": 1,
    "maxLength": 1
  }
}

Delete key format

delete

Deletes the key-format definition for the given keyId. If the format exists and is removed, server-side validation for that key will no longer be applied (unless the format is re-added). Returns 204 No Content on success.

Path parameters

keyIdstringRequired

Responses

204

NO CONTENT (deleted)

application/json

delete

/keyFormat/{keyId}

HTTPcURLJavaScriptPython

DELETE /gbds/v2/keyFormat/{keyId} HTTP/1.1
Host: <ip>:8085
Accept: */*

204

NO CONTENT (deleted)

{}

Validate keys (oneKeyOnly + format)

post

Validates a list of keys according to the active key-validation settings. When the oneKeyOnly setting is enabled, payloads containing more than one key are rejected. When the keyFormat setting is enabled, each key must satisfy its configured key_format rules (formatType, regex, minLength, maxLength). The endpoint returns 200 OK if all validations pass, or 400 Bad Request if any rule is violated. Use this to pre-check client requests before enroll/update.

Bodyobject[]

application/json

idstringOptional

Name of entity identifier.

valuestringOptional

Value of entity identifier.

Responses

200

OK

application/json

Responseobject

400

BAD REQUEST

application/json

post

/keyFormat/validate

HTTPcURLJavaScriptPython

POST /gbds/v2/keyFormat/validate HTTP/1.1
Host: <ip>:8085
Content-Type: application/json
Accept: */*
Content-Length: 30

[
  {
    "id": "text",
    "value": "text"
  }
]

{}

Validate a single key value

get

Validates a single key value against its configured format outside of the enroll/update flow. It returns 200 OK if the value passes all checks (format type, regex pattern, and optional length constraints) or 400 Bad Request with type=VALIDATION_ERROR and code=INVALID_KEY if validation fails. This endpoint only evaluates a single (keyId, keyValue) pair and does not modify state.

Path parameters

keyIdstringRequired

keyValuestringRequired

Responses

200

OK

application/json

Responseobject

400

BAD REQUEST

application/json

get

/keyFormat/validate/{keyId}/{keyValue}

HTTPcURLJavaScriptPython

GET /gbds/v2/keyFormat/validate/{keyId}/{keyValue} HTTP/1.1
Host: <ip>:8085
Accept: */*

{}

Validate keys for potential inconsistencies

post

Checks a list of keys for inconsistencies that would invalidate an update/enroll under the inconsistentKeys setting. Inconsistent cases include multiple keys matching different existing people or a payload key that matches an existing person while another key of the same id has a different value. The endpoint returns 200 OK if the keys are consistent, or 400 Bad Request when inconsistencies are detected.

Bodyobject[]

application/json

idstringOptional

Name of entity identifier.

valuestringOptional

Value of entity identifier.

Responses

200

OK

application/json

Responseobject

400

BAD REQUEST

application/json

post

/keyFormat/validate/inconsistentKeys

HTTPcURLJavaScriptPython

POST /gbds/v2/keyFormat/validate/inconsistentKeys HTTP/1.1
Host: <ip>:8085
Content-Type: application/json
Accept: */*
Content-Length: 30

[
  {
    "id": "text",
    "value": "text"
  }
]

{}