# Turn it on

> Who can turn the Map API on, what is charged at that moment, how later months are billed, what turning it off does, and the errors this flow can return.

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

## Who can turn it on

Any paying business account. There is no application and no review. An account on the free trial cannot turn it on: add a payment method first. To build before paying, use [test mode](https://offendersearch.app/docs/map/test-mode.md).

## How to turn it on

In the dashboard, open Map API and turn it on. Or call `POST /v1/map/enable` with a secret key or an account admin’s dashboard session.

POST /v1/map/enable

```bash
curl -X POST https://api.offendersearch.app/v1/map/enable \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"acceptMinimum": true}'
```

1. `acceptMinimum` must be `true`. It is your agreement to the monthly minimum.
2. The account needs a payment method on file.
3. We charge the $300 minimum to the card at that moment. If the charge fails, nothing is turned on.
4. The plan is active at once, on the same key. A confirmation email is sent.

The response is the same object `GET /v1/map/status` returns, plus `changed` and a `charged` object with the amount, the month it covers and the invoice.

## What the charge covers

Any paying account can turn the Map API on. Turning it on charges the $300 minimum that day, and it covers the rest of that calendar month.

The $300 monthly minimum is applied toward everything the account uses that month, search included. A month with $110 of usage is billed $300; a month with $1,100 is billed $1,100.

- **It is a floor, not a fee on top.** The $300 is applied toward everything the account uses that month: map requests, record opens and search.
- **The first month.** The $300 is paid on the day you turn it on. At month end that month is invoiced as `max(total usage, 300) − 300 already paid`. With $110 of usage the month-end invoice adds nothing. With $1,100 of usage it adds $800.
- **Later months.** From the next month the minimum is settled on the month-end invoice: you pay your usage, or the minimum if usage is lower.
- **The day of the month does not change the amount.** The minimum covers the calendar month it is paid in, whichever day that is.

See [Billing](https://offendersearch.app/docs/map/billing.md) for the rates and worked months.

## If the card is declined

Nothing is turned on and nothing is charged. The call answers `402 payment_failed`. Fix or replace the card and call it again.

## Turning it off

Turn it off at any time and the map routes stop at once. A minimum already paid is not refunded, and turning it back on in the same month costs nothing more.

POST /v1/map/disable

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

- The map routes answer `403 map_not_enabled` from that moment. Test mode still works.
- The month it was on in stays a minimum month.
- Calling `enable` on an account that is already on changes nothing and charges nothing.

## Checking the plan

`GET /v1/map/status` is free and works whether the plan is on or off. It is how a client finds out which.

GET /v1/map/status

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

## Negotiated accounts

An account with a negotiated plan, such as a trial period with the minimum waived, is turned on by us. Nothing is charged at that point, and the minimum starts the month after the waiver ends. Contact us to arrange one.

## Errors in this flow

| Code | Status | Cause | What to do |
| --- | --- | --- | --- |
| `minimum_not_accepted` | 422 | `acceptMinimum` was not `true`. | Send `{"acceptMinimum": true}`. |
| `payment_method_required` | 402 | There is no card on the account, or it is on the free trial. | Add a payment method in the dashboard under Billing, then try again. |
| `payment_failed` | 402 | The card was declined. Nothing was turned on and nothing was charged. | Fix or replace the card, then try again. |
| `business_account_required` | 403 | The account is a personal account. | Use a business account. |
| `admin_required` | 403 | The dashboard seat is not an admin of the account. | Ask an account admin to turn it on, or use a secret key. |

---

## Related

- Previous: [Quickstart](https://offendersearch.app/docs/map/quickstart.md)
- Next: [Access & keys](https://offendersearch.app/docs/map/access.md)
- Index: [Map API reference](https://offendersearch.app/docs/map.md)