Usage Info

Use this endpoint when creating a metadata type and its fields definition. The metadata type is used to capture metadata details for entities like Business, Person, BandAccount & Location.

Request

Authentication: KSig1-HMAC-SHA256

Parameters

Parameter	Type	Required	Description
account_id	string	Yes	The account where the metadata type will be created. The Account ID is supplied to you when you receive your credentials.
metadata_type	string	Yes	Identifier for the metadata category being defined (e.g. ip_address, device_info).
description	string	No	Explanation of what the metadata_type represents.
fields	object	Yes	A dynamic object defining the schema of metadata details. Each key represents a metadata field name, and its value is a field definition object The field definition parameters is defined in the tables below
max_count	integer	No	Maximum number of metadata details entries of this type allowed per subject record. Allowed values are: `-1` or any positive integer. Notes: - Defaults to `-1`. - Value `-1` represents no limit.

Field Definition Parameters

Parameter	Type	Required	Description
type	string	Yes	Data type of the field value. Allowed types are: `string`, `integer` and `boolean`.
required	boolean	No	Whether the field is mandatory.
description	string	No	Explanation of what the field represents.
format	string	No	Additional formatting constraint supported for the field. Must be one of METADATA_DEFINITION_FIELDS_FORMAT .

Example

{
  "metadata_type": "IP_ADDRESS",
  "description": "Metadata for IP address",
  "fields": {
    "ip_address_v4": {
      "type": "string",
      "format": "ipv4",
      "description": "The IPv4 address.",
      "required": true
    },
    "ip_address_v6": {
      "type": "string",
      "format": "ipv6",
      "description": "The IPv6 address."
    },
    "event_source": {
      "type": "string",
      "description": "Source of the event."
    }
  },
  "max_count": -1
}

Response

Data

An empty data object is returned when the completion is successful.

Example

{
  "meta": {
    "status": "SUCCESS",
    "trace_id": "trc_6zNzQZHSf26V83BO3uW6dS",
    "version": "2025-03-24"
  },
  "data": {}
}

Errors

Error Code	HTTP Code	Possible Cause
BAD_REQUEST	400	Required parameters not provided or attributes are invalid. Metadata type is already defined for the account or is defined at SYSTEM/INTERNAL level.
ENTITY_NOT_FOUND	400	Any of the provided Ids do not exist.