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

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-enrich[Enrich APIs].
--

Executes an existing <<enrich-policy,enrich policy>>.

////

[source,console]
----
PUT /users/_doc/1?refresh
{
  "email": "mardy.brown@asciidocsmith.com",
  "first_name": "Mardy",
  "last_name": "Brown",
  "city": "New Orleans",
  "county": "Orleans",
  "state": "LA",
  "zip": 70116,
  "web": "mardy.asciidocsmith.com"
}

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

[source,console]
--------------------------------------------------
PUT /_enrich/policy/my-policy/_execute?wait_for_completion=false
--------------------------------------------------
// TEST[s/\?wait_for_completion=false//]

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


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

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

`POST /_enrich/policy/<enrich-policy>/_execute`


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

include::put-enrich-policy.asciidoc[tag=enrich-policy-api-prereqs]


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

Use the execute enrich policy API
to create the enrich index for an existing enrich policy.

// tag::execute-enrich-policy-def[]
The _enrich index_ contains documents from the policy's source indices.
Enrich indices always begin with `.enrich-*`,
are read-only,
and are <<indices-forcemerge,force merged>>.

[WARNING]
====
Enrich indices should only be used by the <<enrich-processor,enrich processor>>
or the <<esql-enrich,{esql} `ENRICH` command>>. Avoid using enrich indices for
other purposes.
====
// end::execute-enrich-policy-def[]

// tag::update-enrich-index[]
Once created, you cannot update 
or index documents to an enrich index.
Instead, update your source indices
and <<execute-enrich-policy-api,execute>> the enrich policy again.
This creates a new enrich index from your updated source indices. 
The previous enrich index will deleted with a delayed maintenance job. 
By default this is done every 15 minutes. 
// end::update-enrich-index[]

By default, this API is synchronous: It returns when a policy has been executed.
Because executing a policy performs several operations, it may take a while to
return a response, especially when the source indices are large. This can lead
to timeouts. To prevent timeouts, set the `wait_for_completion` parameter to
`false`. This runs the request asynchronously in the background, and returns a
task ID. You can use the task ID to manage the request with the <<tasks,task
management API>>.

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

`<enrich-policy>`::
(Required, string)
Enrich policy to execute.

[[execute-enrich-policy-api-query-params]]
==== {api-query-parms-title}

`wait_for_completion`::
(Optional, Boolean)
If `true`, the request blocks until execution is complete. If `false`, the
request returns immediately and execution runs asynchronously in the background.
Defaults to `true`.