[role="xpack"]
[[put-enrich-policy-api]]
=== Create enrich policy API
++++
<titleabbrev>Create enrich policy</titleabbrev>
++++

Creates an enrich policy.

////
[source,console]
----
PUT /users
{
  "mappings": {
    "properties": {
      "email": { "type": "keyword" }
    }
  }
}
----
////

[source,console]
----
PUT /_enrich/policy/my-policy
{
  "match": {
    "indices": "users",
    "match_field": "email",
    "enrich_fields": ["first_name", "last_name", "city", "zip", "state"]
  }
}
----
// TEST[continued]

////
[source,console]
--------------------------------------------------
DELETE /_enrich/policy/my-policy
--------------------------------------------------
// TEST[continued]
////


[[put-enrich-policy-api-request]]
==== {api-request-title}

`PUT /_enrich/policy/<enrich-policy>`


[[put-enrich-policy-api-prereqs]]
==== {api-prereq-title}

// tag::enrich-policy-api-prereqs[]
If you use {es} {security-features}, you must have:

* `read` index privileges for any indices used
* The `enrich_user` <<built-in-roles,built-in role>>
// end::enrich-policy-api-prereqs[]


[[put-enrich-policy-api-desc]]
==== {api-description-title}

Use the create enrich policy API to create a <<enrich-policy,enrich policy>>.

[WARNING]
====
include::../../enrich.asciidoc[tag=update-enrich-policy]
====


[[put-enrich-policy-api-path-params]]
==== {api-path-parms-title}

`<enrich-policy>`::
(Required, string)
Name of the enrich policy to create or update.

[role="child_attributes"]
[[put-enrich-policy-api-request-body]]
==== {api-request-body-title}

`<policy-type>`::
(Required, object)
Configures the enrich policy. The field key is the enrich policy type. Valid key
values are:
+
--
`geo_match`:::
Matches enrich data to incoming documents based on a
<<query-dsl-geo-shape-query,`geo_shape` query>>. For an example, see
<<geo-match-enrich-policy-type>>.

`match`:::
Matches enrich data to incoming documents based on a
<<query-dsl-term-query,`term` query>>. For an example, see
<<match-enrich-policy-type>>.

`range`:::
Matches a number, date, or IP address in incoming documents to a range in the
enrich index based on a <<query-dsl-term-query,`term` query>>. For an example,
see <<range-enrich-policy-type>>.
--
+
.Properties of `<policy-type>`
[%collapsible%open]
====
`indices`::
(Required, String or array of strings)
One or more source indices used to create the enrich index.
+
If multiple indices are specified, they must share a common `match_field`.

`match_field`::
(Required, string)
Field in source indices used to match incoming documents.

`enrich_fields`::
(Required, Array of strings)
Fields to add to matching incoming documents. These fields must be present in
the source indices.

`query`::
(Optional, <<query-dsl,Query DSL query object>>)
Query used to filter documents in the enrich index. The policy only uses
documents matching this query to enrich incoming documents. Defaults to a
<<query-dsl-match-all-query,`match_all`>> query.
====