# InvokeRetrieve()

Invokes the Retrieve method on a Marketing Cloud Engagement API Object and returns the API status message and request ID.

## Availability

<table>
  <tr>
    <td>Marketing Cloud Engagement</td>
    <td>✅ Yes</td>
  </tr>
  <tr>
    <td>Marketing Cloud Next</td>
    <td>❌ No</td>
  </tr>
</table>

## Syntax

```
InvokeRetrieve(apiObject,
               statusMessage,
               requestId)
```

The `InvokeRetrieve()` function has three parameters:

- `apiObject` (API Object): Required. The API Object to invoke the Retrieve method on.
- `statusMessage` (AMPscript variable): An AMPscript variable that stores the API status message.
- `requestId` (AMPscript variable): An AMPscript variable that stores the request ID.

## Usage

This example creates a RetrieveRequest Object, sets a property, and adds an array item. It then creates a simple filter that finds matching email addresses. Finally, the function calls the `InvokeRetrieve()` function, outputting the status message and the request ID.

```
%%[
  Var @rr_1, @sfp, @statusMessage, @requestId, @emailAddress
  Set @emailAddress = "john.rosales@example.com"
  Set @rr_1=CreateObject("RetrieveRequest")

  SetObjectProperty(@rr_1,"ObjectType","Subscriber")
  AddObjectArrayItem(@rr_1,"Properties","EmailAddress")

  Set @sfp=CreateObject("SimpleFilterPart")

  SetObjectProperty(@sfp,"Property","EmailAddress")
  SetObjectProperty(@sfp,"SimpleOperator","equals")
  AddObjectArrayItem(@sfp,"Value",@emailAddress)
  SetObjectProperty(@rr_1,"Filter",@sfp)

  Set @sub=InvokeRetrieve(@rr_1, @statusMessage, @requestId)
]%%
<p>Status message: %%=v(@statusMessage)=%%</p>
<p>Request ID: %%=v(@requestId)=%%</p>
```