# sim_return

Returns objects of the specific resident from the sim.

```csharp
// See "LSL Helper Functions" page for this function
smartbotsAPI("sim_return", ["avatar", UUID, "scripted", TRUE]);
```

## Variables

The following table shows input values (you send them with the API call) and returned output values.

### Input basic parameters

| Variable | Required | Description |
|----------|----------|-------------|
| action   | yes      | = sim_return |
| apikey   | yes      | Your personal [developer's API key](/doc/developers-api-key-tw8bQj4LSJ). |
| botname  | yes      | Your bot's SL login. |
| secret   | yes      | [Bot access code](https://www.mysmartbots.com/docs/Bot_access_code) of your bot. |
| dataType | optional | Set to "json" to get JSON reply instead of URL-encoded string |
| custom   | optional | The custom data (string) to be passed back to caller script. This value will be returned back to the caller in HTTP response. |

### Input

| Variable | Required | Description |
|----------|----------|-------------|
| avatar   | yes      | the UUID of the avatar |
| scripted | optional | Set to TRUE (or 1) to return scripted object only |
| others   | optional | Set to TRUE (or 1) to return objects on others land |
| all_estates | optional | Set to TRUE (or 1) to return on all estates available for bot |

### Output

(to be received in `http_response` LSL event, see [docs](/doc/doing-http-api-calls-c6FSEMF7bP) for details)

| Variable | Description |
|----------|-------------|
| result   | OK - command completed successfully<br>FAIL - command failed |
| resulttext | Detailed reason for the failure. |
| custom   | The value from input "custom" parameter. See above. |

## Comments

* You have to teleport to the region first.
* To execute this function your bot needs to be an [Estate Manager](http://wiki.secondlife.com/wiki/Estate_Manager).
* You **don't** need a "Sim Governor" add-on to use this function.

## Examples

Teleport to DuoLife region and return all objects of BartenderJoe:

```csharp
// You need to adjust the vars below:
string sbApiKey = "...";
string sbBotName = "...";
string sbBotAccessCode = "...";

string myHome = "DuoLife/128/128/20";

// First, teleport to the desired region

string params = llDumpList2String([
  "action="  + "teleport",
  "location=" + llEscapeURL(myHome),
  "apikey="  + llEscapeURL(sbApiKey),
  "botname=" + llEscapeURL(sbBotName),
  "secret="  + llEscapeURL(sbBotAccessCode)
  ], "&");
 
llHTTPRequest("https://api.mysmartbots.com/api/bot.html",
  [HTTP_METHOD,"POST"], params);

// Now return avatar's objects, only the scripted ones

params = llDumpList2String([
  "action="  + "sim_return",
  "avatar=" + "bc3af7d6-f089-4b57-b78e-473334af01cb",
  "scripted=" + "1"
  ], "&");
 
llHTTPRequest("https://api.mysmartbots.com/api/bot.html",
  [HTTP_METHOD,"POST"], params);
```