# Open a record

> Open the complete record behind a marker: when a record open is charged, when it is free, how long marker ids last, and saved references for shared links.

- **HTML:** https://offendersearch.app/docs/map/open-a-record
- **Base URL:** https://api.offendersearch.app
- **Authentication:** `X-API-Key` request header
- **Map API reference as markdown:** https://offendersearch.app/docs/map.md

## The request

`GET /v1/map/records/{markerId}` returns the complete record behind a marker. It accepts a marker id, `mk_…`, or a saved reference, `mr_…`.

GET /v1/map/records/{markerId}

```bash
curl https://api.offendersearch.app/v1/map/records/mk_Zb3… \
  -H "X-API-Key: $OFFENDERSEARCH_KEY"
```

200 OK

```json
{
  "record": { "…the same record object POST /v1/search returns…" },
  "recordRef": "mr_k2P…",
  "billing": {
    "billed": true,
    "unit": "map_record_open",
    "reason": "first_open_of_this_marker"
  },
  "notice": "A pin shows a registered address, not a person's current location."
}
```

| Field | Meaning |
| --- | --- |
| `record` | The same record object `POST /v1/search` returns. See [The Record object](https://offendersearch.app/docs/record-object.md). |
| `recordRef` | A lasting reference to this record, `mr_…`, for bookmarks and shared links. |
| `billing.billed` | `true` when this call was charged as a record open. |
| `billing.reason` | Why. For example `first_open_of_this_marker` or `marker_already_opened`. |
| `notice` | A sentence to show with the record. |

## When a record open is charged

A record open is the complete record behind one marker. Opening the same marker again is free. A new map request returns new marker ids, so opening that person from the new result is a new charge.

- **One charge for each person in each map response.** Opening a marker for the first time is one record open, $0.015.
- **The same marker id again is free.** Close the panel, open it again, reload the page: no charge. The response says `"reason": "marker_already_opened"`.
- **Two pins of one person are one charge.** A person with a home pin and a work pin in the same response is charged once.
- **A new map response gives new ids.** Every viewport or groups response carries new marker ids. Opening the same person from the new response is a new charge.
- **A `304` gives no new ids.** An unchanged view keeps the ids you already have, so re-opening from it stays free.

To keep opens free while a person browses, keep the marker ids from the response you drew and reuse them. Do not call the viewport route again just to open a record.

## How long ids last

Marker ids and group ids work for 24 hours, and only for the account they were issued to. After that the route answers `410 marker_expired` or `410 group_expired`. Request the view again for new ids.

Do not store a marker id in a database or a link. Store the `recordRef`.

## Saved links: recordRef

Every opened record comes with a `recordRef`. It does not expire. Put it in a bookmark, a shared link or your own database, and open it later with the same route.

GET /v1/map/records/{markerId}

```bash
curl https://api.offendersearch.app/v1/map/records/mr_k2P… \
  -H "X-API-Key: $OFFENDERSEARCH_KEY"
```

- Opening by reference is one record open. It is then free for 24 hours.
- A record you just opened from a marker is also free by its reference for 24 hours.
- A reference works only for the account it was issued to.

## Photos

Photo links on hosted photos are signed. A link works in an `<img>` tag for one hour. Use it as it is, and do not store it: open the record again for a new link.

## Reports

The record carries the `recordId` that the report route takes. See [Verification reports](https://offendersearch.app/docs/reports.md).

## Errors

| Code | Status | Cause | What to do |
| --- | --- | --- | --- |
| `unknown_marker` | 404 | The id is not one this account was given. | Use an id from your own map responses, with the key of the same account. |
| `marker_expired` | 410 | The marker id is older than 24 hours. | Request the view again for a new id, or use the `recordRef`. |
| `record_no_longer_listed` | 410 | The registry no longer lists the person. Not billed. | Remove the pin and tell the user the record is no longer listed. |

---

## Related

- Previous: [The click sequence](https://offendersearch.app/docs/map/click-sequence.md)
- Next: [Near an address](https://offendersearch.app/docs/map/near-an-address.md)
- Index: [Map API reference](https://offendersearch.app/docs/map.md)