{"_id":"591a8a17b560ce1b00071dae","category":{"_id":"591e4c277f22100f00031521","project":"56008ba98c0c9d0d00dcaeb0","__v":0,"version":"5719767ec863120e0012a042","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-05-19T01:36:39.888Z","from_sync":false,"order":4,"slug":"rules","title":"Rules"},"project":"56008ba98c0c9d0d00dcaeb0","parentDoc":null,"__v":0,"user":"564a46904fa1460d00780c0d","version":{"_id":"5719767ec863120e0012a042","hasDoc":true,"project":"56008ba98c0c9d0d00dcaeb0","__v":7,"hasReference":true,"createdAt":"2016-04-22T00:55:26.295Z","releaseDate":"2016-04-22T00:55:26.295Z","categories":["5719767ec863120e0012a043","5719767ec863120e0012a044","5719767ec863120e0012a045","5719767ec863120e0012a046","5719767ec863120e0012a047","5719767ec863120e0012a048","5719767ec863120e0012a049","57f45a18da14e71700d12e4a","582b71b15403840f008c0410","58c060cf3eee111b00a8b210","591e4c277f22100f00031521","591e4c3d094c5b0f006769fe","591e4c461e0dc20f0047b58b"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-05-16T05:11:51.236Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"curl -XPOST 'https://api.thisdata.com/v1/rules?api_key=API_KEY' -d'\n{\n  \"name\": \"IP Blacklist for Guests\",\n  \"description\": \"Blacklist for guest account users\",\n  \"type\": \"blacklist\",\n  \"target\": \"location.ip\",\n  \"source\": \"guest-123\",\n  \"filters\": [\"123.123.123.123\"]\n}'\n","language":"text","name":"curl"}]},"method":"post","results":{"codes":[{"status":201,"name":"","code":"{\n  \"id\": \"816677874491720987\",\n  \"name\": \"IP Blacklist for Guests\",\n  \"description\": \"Blacklist for guest account users\",\n  \"type\": \"blacklist\",\n  \"target\": \"location.ip\",\n  \"source\": \"guest-123\",\n  \"filters\": [\"123.123.123.123\"]\n}\n","language":"json"},{"name":"","code":"","language":"json","status":400},{"language":"text","code":"","status":401}]},"settings":"","auth":"required","params":[{"_id":"591a7fc4064b8319004caae9","ref":"","in":"query","required":false,"desc":"Your ThisData API key","default":"","type":"string","name":"api_key"},{"_id":"591a8a17b560ce1b00071db4","ref":"","in":"body","required":true,"desc":"The name of this rule","default":"","type":"string","name":"name"},{"_id":"591a8a17b560ce1b00071db3","ref":"","in":"body","required":false,"desc":"Optional description of why this rule exists","default":"","type":"string","name":"description"},{"_id":"591a8a17b560ce1b00071db2","ref":"","in":"body","required":true,"desc":"The type of rule from the list below","default":"","type":"string","name":"type"},{"_id":"591a8a17b560ce1b00071db1","ref":"","in":"body","required":true,"desc":"The event attribute to apply the rule against","default":"","type":"string","name":"target"},{"_id":"591a8a17b560ce1b00071db0","ref":"","in":"body","required":false,"desc":"Optional source to filter rules by team or customer","default":"","type":"string","name":"source"},{"_id":"591a8a17b560ce1b00071daf","ref":"","in":"body","required":true,"desc":"Array of values relevant to the given rule type. See below for rule types.","default":"","type":"array_string","name":"filters"}],"url":"/v1/rules"},"isReference":true,"order":0,"body":"### Authentication\n\nYour API Key must be provided in the URL's query string. [Learn more about Authentication & your API Key](doc:authentication-api-key).\n\n### Rule Type\nThe `type` parameter specifies the type of rule that will be created. Currently the following types are supported:\n\n* `blacklist` - If an event contains a value in a blacklist the risk score will always be `1.0` (HIGH). \n* `whitelist` - A white list value will override a blacklist with the same `target` parameter. \n\n### Target\nThe target parameter that will be used when evaluating the rule against an incoming event. Currently the following targets are supported:\n\n* `location.ip` \n* `location.address.country_name`\n* `location.address.country_iso_code` \n\n### Source\nThe source can be used to scope rules to a specific team or customer. It matches against the `source.id` parameter that you can send with a [Event](doc:apiv1events)  or [Verify](doc:apiv1verify) API request. \n\ne.g.\nIn a multi tenant scenario you might want to allow customers to blacklist certain IP addresses. You could achieve this by creating a blacklist rule containing the IP address and setting the source to your own unique ID for that customer. \n\nYou can also use it to whitelist/override global blacklist rules. For example you create a blacklist on certain bad IP addresses and don't specify `source`. Because one customer/tenant needs access from a blacklisted IP you would create a `whitelist` rule containing that IP and the set the source to the customer ID. \n\n### Filters\nAn array of string values to evaluate against each event. It could be a list of IP addresses or country code or name. \n\n#### IP Address\nAn IPv4 or IPv6 address or CIDR range. \n\ne.g.\n```\n{\n    \"target\": \"location.ip\",\n    \"filters\": [\"123.123.123.123\", \"192.168.2.1/24\", \"2001:db8::/32\"]\n}\n```\nNote: If you want to blacklist every possible address you can create rule using IPv4 `0.0.0.0/0` and IPv6 `::/0`. You could then whitelist particular IPs or ranges. \n\n#### Country Code\nThe [ISO 3166 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1) for the country. \ne.g.\n```\n{\n    \"target\": \"location.address.country_iso_code\",\n    \"filters\": [\"NZ\"]\n}\n```\n \n\n#### Country Name\nA case sensitive free form country name. \n\ne.g.\n```\n{\n    \"target\": \"location.address.country_name\",\n    \"filters\": [\"New Zealand\"]\n}\n```\n\n### Response Messages\n\n* 201 - Success. Returns the new rule including it's ID\n* 400 - Invalid rule attribute. Validation errors are returned in the response body. \n* 401 - Invalid API Key","excerpt":"Create a custom rule to gain more control over the risk scoring of events","slug":"v1rules-1","type":"endpoint","title":"Create a rule"}

postCreate a rule

Create a custom rule to gain more control over the risk scoring of events

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Query Params

api_key:
string
Your ThisData API key

Body Params

name:
required
string
The name of this rule
description:
string
Optional description of why this rule exists
type:
required
string
The type of rule from the list below
target:
required
string
The event attribute to apply the rule against
source:
string
Optional source to filter rules by team or customer
filters:
required
array of strings
Array of values relevant to the given rule type. See below for rule types.

Examples


Result Format


Documentation

### Authentication Your API Key must be provided in the URL's query string. [Learn more about Authentication & your API Key](doc:authentication-api-key). ### Rule Type The `type` parameter specifies the type of rule that will be created. Currently the following types are supported: * `blacklist` - If an event contains a value in a blacklist the risk score will always be `1.0` (HIGH). * `whitelist` - A white list value will override a blacklist with the same `target` parameter. ### Target The target parameter that will be used when evaluating the rule against an incoming event. Currently the following targets are supported: * `location.ip` * `location.address.country_name` * `location.address.country_iso_code` ### Source The source can be used to scope rules to a specific team or customer. It matches against the `source.id` parameter that you can send with a [Event](doc:apiv1events) or [Verify](doc:apiv1verify) API request. e.g. In a multi tenant scenario you might want to allow customers to blacklist certain IP addresses. You could achieve this by creating a blacklist rule containing the IP address and setting the source to your own unique ID for that customer. You can also use it to whitelist/override global blacklist rules. For example you create a blacklist on certain bad IP addresses and don't specify `source`. Because one customer/tenant needs access from a blacklisted IP you would create a `whitelist` rule containing that IP and the set the source to the customer ID. ### Filters An array of string values to evaluate against each event. It could be a list of IP addresses or country code or name. #### IP Address An IPv4 or IPv6 address or CIDR range. e.g. ``` { "target": "location.ip", "filters": ["123.123.123.123", "192.168.2.1/24", "2001:db8::/32"] } ``` Note: If you want to blacklist every possible address you can create rule using IPv4 `0.0.0.0/0` and IPv6 `::/0`. You could then whitelist particular IPs or ranges. #### Country Code The [ISO 3166 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1) for the country. e.g. ``` { "target": "location.address.country_iso_code", "filters": ["NZ"] } ``` #### Country Name A case sensitive free form country name. e.g. ``` { "target": "location.address.country_name", "filters": ["New Zealand"] } ``` ### Response Messages * 201 - Success. Returns the new rule including it's ID * 400 - Invalid rule attribute. Validation errors are returned in the response body. * 401 - Invalid API Key