# IRPCExternalLocationsAdmin.AddExternalLocation

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation/

Badges: `Administration API / specialized` `admin` `session`

Creates an external location.

- **Service:** [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md) `MFiles.IRPCExternalLocationsAdmin`
- **gRPC method:** `/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-external-location`
- **Request:** [`AddExternalLocationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation/index.md#request)
- **Response:** [`AddExternalLocationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `manage_external_locations`; a file source also requires the server right `run_code`.
- For a mail source without `run_code`, `update_interval` must be at least 60 seconds.
- A file source cannot both link files (`file_source.link_files`) and convert them to
  searchable PDF (`file_source.convert_to_searchable_pdf`): invalid-argument error.
- With `test_access` true, the server connects to the location and rolls the addition back if
  that fails. With false, a location that does not work yet (for example a mail server that is
  down) can be saved.

<a id="request"></a>

## Request: AddExternalLocationRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `json_ext_loc` | [`ExternalLocation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLocation/index.md) | The new location. `id` is ignored and assigned by the server. |
| `json_ext_loc.id` | `int32` | External location ID. |
| `json_ext_loc.description` | `string` | Description. |
| `json_ext_loc.object_acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | ACL for new documents. |
| `json_ext_loc.object_acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `json_ext_loc.object_acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `json_ext_loc.object_acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `json_ext_loc.object_acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `json_ext_loc.object_acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `json_ext_loc.object_acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `json_ext_loc.object_type` | `int32` | Object type. |
| `json_ext_loc.object_properties[]` | repeated [`DefaultProperty`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DefaultProperty/index.md) | The properties. |
| `json_ext_loc.object_properties[].property_def` | `int32` | PropertyDef ID. |
| `json_ext_loc.object_properties[].allow_retaining_previous_value` | `bool` | True if the user is allowed to use/retain previous value |
| `json_ext_loc.object_properties[].type` | [`DefaultPropertyType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DefaultPropertyType/index.md) | Default property type. Values: `DEFAULT_PROPERTY_TYPE_UNDEFINED` (0), `DEFAULT_PROPERTY_TYPE_FIXED_VALUE` (1), `DEFAULT_PROPERTY_TYPE_FROM_HP_DSS_XML` (2), `DEFAULT_PROPERTY_TYPE_FROM_XML` (3), `DEFAULT_PROPERTY_TYPE_FROM_EMAIL` (4), `DEFAULT_PROPERTY_TYPE_FROM_EMAIL_HEADER` (5), `DEFAULT_PROPERTY_TYPE_FROM_OCR` (6), `DEFAULT_PROPERTY_TYPE_FROM_FILE_PROPERTY` (7), `DEFAULT_PROPERTY_TYPE_STATE_TRANSITION_TIME` (8). |
| `json_ext_loc.object_properties[].data` | [`DefaultPropertyUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DefaultPropertyUnion/index.md) | The details as a union. |
| `json_ext_loc.options` | [`EXTLOCFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EXTLOCFLAGS/index.md) | Flags. |
| `json_ext_loc.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `json_ext_loc.options.disabled` | `bool` | Present if the external location is disabled. If not present, the external location is enabled. |
| `json_ext_loc.options.monitor` | `bool` | Present if the server should keep monitoring the external location. |
| `json_ext_loc.update_interval` | `uint32` | The delay between automatic monitoring rounds in seconds. |
| `json_ext_loc.type` | [`ExtLocType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtLocType/index.md) | The type of the source. Values: `EXT_LOC_TYPE_NONE` (0), `EXT_LOC_TYPE_FILE_SOURCE` (1), `EXT_LOC_TYPE_MAIL_SOURCE` (2). |
| `json_ext_loc.data` | [`ExtLocUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtLocUnion/index.md) | The type-specific data as a union. |
| `json_ext_loc.data.file_source` | [`FileSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileSource/index.md) (oneof data) | File source definition. |
| `json_ext_loc.data.mail_source` | [`MailSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MailSource/index.md) (oneof data) | Mail source definition. |
| `json_ext_loc.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `test_access` | `bool` | True to test access to the external location before accepting the changes. |

<a id="response"></a>

## Response: AddExternalLocationResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the new location. |