# External references

> Link a line of one Layerz model to a line of another, the way linked Excel workbooks work, then refresh, inspect or unlink it over the REST API.

An external reference makes an assumption mirror a line of another Layerz model: a group model reading each entity's plan, a fund model reading its portfolio. The linked line holds a snapshot of the source series, refreshed on demand.

| Method and path                          | Does                                                                                       |
| ---------------------------------------- | ------------------------------------------------------------------------------------------ |
| `GET /models/:id/external-refs`          | Every link with its status (`ok`, `model_missing`, `item_missing`) and whether it is stale |
| `POST /models/:id/external-refs`         | Create a link, or up to 200 in one call                                                    |
| `POST /models/:id/external-refs/refresh` | Refresh snapshots: all, some `uids`, or those of one source model                          |
| `DELETE /models/:id/external-refs/:uid`  | Unlink: the line keeps its values and becomes an ordinary assumption                       |

## Link

**Form 1**

| Field | Type | Required | Description |
|---|---|---|---|
| `source_model_id` | `string` | yes |  |
| `source_uid` | `string` | yes |  |
| `uid` | `string` |  |  |
| `parent` | `string` |  |  |
| `name` | `string` |  |  |
| `timeline_ref` | `"constant" \| "monthly" \| "yearly" \| "quarterly"` |  |  |

**Form 2**

| Field | Type | Required | Description |
|---|---|---|---|
| `links` | `object[]` | yes |  |

You must be able to read the source model. A refresh that changes values saves a version first, so it can be undone.

## Refresh

| Field | Type | Required | Description |
|---|---|---|---|
| `uids` | `string[]` |  |  |
| `source_model_id` | `string` |  |  |
