# POI


Manage your own POI data. The taxonomy nests segments, then categories, then
brands. Segments already exist: pick one with `poi segments list`, then create
categories under it and brands under those.

[Conventions](/cli/reference#conventions) apply here, with these exceptions.
The POI creates take no `--dry-run` or `--wait`, and none takes a JSON
`--file`: `poi submissions create` takes its JSON body through `--list`, and
lets `--name`, `--brand-id`, `--key`, `--update`, and `--remove` override that
body, with a note on stderr for each value it replaces. Every id flag takes a
number, not a name. Only `poi locations list` pages.

The segment, category, and brand lists show each id under `value` and its name
under `text`. The category, brand, and submission creates print the new one's
id and name the same way. With `--json`, the brand and submission creates
return `data` as a one-element array, but the category create returns it as a
single object, so read the new category's id at `.data.value`, not
`.data[0].value`. The table and `--quiet` handle both.

To pick POI values while building an audience, use `intuizi reference poi`
([Catalogs](/cli/reference/catalogs#poi)) instead.
[Dataset Types - POI](/api/v2/reference/poi) describes those catalogs. These
commands manage the data itself.

## Segments list

Read the available POI segments, the top of the taxonomy.
See [List Segments](/api/v2/poi/segments#get-apiv2my-datapoissegmentsindex).

| Flag | Input |
| --- | --- |
| `--search` | contains match on the name |

## Categories list

Read your own POI categories.
See [List Categories](/api/v2/poi/categories#get-apiv2my-datapoiscategoriesindex).

| Flag | Input |
| --- | --- |
| `--search` | contains match on the name |

## Categories create

Add a category under one of the available segments.
See [Create Category](/api/v2/poi/categories#post-apiv2my-datapoiscategoriescreate).

| Flag | Input | Lookup |
| --- | --- | --- |
| `--name` | the category name | |
| `--segment-id` | the parent segment | `poi segments list` |

```bash
intuizi poi categories create --name "Coffee shops" --segment-id <id>
```

## Brands list

Read your own POI brands.
See [List Brands](/api/v2/poi/brands#get-apiv2my-datapoisbrandsindex).

| Flag | Input |
| --- | --- |
| `--search` | contains match on the name |

## Brands create

Add a brand under one of your categories.
See [Create Brand](/api/v2/poi/brands#post-apiv2my-datapoisbrandscreate).

| Flag | Input | Lookup |
| --- | --- | --- |
| `--name` | the brand name | |
| `--category-id` | the parent category | `poi categories list` |

```bash
intuizi poi brands create --name "Example Coffee" --category-id <id>
```

## Locations list

Read your own POI locations.
See [List POIs](/api/v2/poi/pois#list-pois).

| Flag | Input | Lookup |
| --- | --- | --- |
| `--search` | matches name, address, city, state, zip, DMA, external id, and placekey id | |
| `--brands` | your own brand ids to filter by, repeatable or comma-separated | `poi brands list` |
| `--countries` | an ISO-3 (alpha-3) country code, such as `USA`, repeatable. Locations are stored with alpha-3 codes even when they were submitted with alpha-2 ones | `reference common countries` |
| `--geometry` | `polygon` (locations that carry a polygon) or `coordinates` (locations that carry a lat/lon point) | |
| `--page` `--per-page` | page through the results | |

## Locations show

Read one location by id.
See [Get POI](/api/v2/poi/pois#get-poi).

## Submissions create

Send locations to Intuizi, from a CSV, an upload, or a JSON list.
See [Create Submission by File](/api/v2/poi/submissions#post-apiv2my-datapoissubmissionscreate-by-file),
[by Upload](/api/v2/poi/submissions#post-apiv2my-datapoissubmissionscreate-by-upload),
or
[by List](/api/v2/poi/submissions#post-apiv2my-datapoissubmissionscreate-by-list),
depending on which source flag is given.

Exactly one source: `--file`, `--upload-reference`, or `--list`.

| Flag | Input | Lookup |
| --- | --- | --- |
| `--name` | the submission name | |
| `--brand-id` | the brand these locations belong to | `poi brands list` |
| `--file` | a `.csv` or `.txt` of locations. Does not read stdin | |
| `--upload-reference` | a reference from an upload with `--purpose poi_submission` | `uploads put` (or `uploads reserve`) |
| `--list` | a JSON file with the Create Submission by List body (`name`, `brand_id`, `locations[]`, and optionally `country_isocode` and the backfill fields), or `-` for stdin | |
| `--key` | how each listed location is matched to the brand's existing POIs, `gps-coordinates` when left out. Required with `--update` or `--remove`. `location-id` matches a location's `location_id` to the id of one of the brand's POIs | |
| `--update` | update the brand's existing POIs that a listed location matches | |
| `--remove` | archive the brand's existing POIs that no listed location matches, and keep the matched ones, updated only with `--update`. Applied once, over the whole submission | |

A listed location that matches an existing POI is never added a second time,
with or without `--update`, and one that matches nothing is added as a new
POI. `--remove` keeps the POIs you list and archives every other POI the brand
had, once the whole submission has been matched, however many locations it
has. A submission whose locations carry values for the key but match no POI
archives every POI the brand had. One that holds no location at all, or in
which no location has a value for the key (a `location_id`, `store_id`,
`master_id`, or `external_id`, a blank value counting as none), archives
nothing. So to use `--remove`, list every location the brand should keep, in
one submission, not the ones to drop. Both take effect only when Intuizi
approves the submission (see below). If an approval is interrupted part way,
its locations are still imported but `--remove` is not applied. Send the
submission again to apply it.

A `location_id` must be the id of one of your POIs, the `id` column of
`poi locations list`, as a whole number (`101` or `101.0`). With
`--key location-id`, a location matches the brand's POI whose id is its
`location_id`. A location with no `location_id`, or with one that is not the
id of one of the brand's POIs, is added as a new POI. A `--remove` submission
in which no location has a `location_id` archives nothing. See the
[matching note](/api/v2/poi/submissions#post-apiv2my-datapoissubmissionscreate-by-file)
on Create Submission by File.

With `--list`, `--name` and `--brand-id` are optional. The body's `name` and
`brand_id` are sent unless the flags override them, so one file can serve
several brands. `--key`, `--update`, and `--remove` replace the body's `key`,
`update`, and `remove` the same way, and `--update=false` or `--remove=false`
turns off a `true` in the body. A flag that replaces a different value in the
body says so on stderr, such as
`note: --brand-id 12 replaces brand_id 9 from the --list body`.

The accepted `--key` values and the CSV column headers are on
[Create Submission by File](/api/v2/poi/submissions#post-apiv2my-datapoissubmissionscreate-by-file).
The `locations[]` fields are on
[Create Submission by List](/api/v2/poi/submissions#post-apiv2my-datapoissubmissionscreate-by-list).
Alpha-2 `locations[].country` codes need `country_isocode` set to `alpha_2` in
the body.

A [backfill](/api/v2/poi/submissions#backfill) can be requested only through
`--list`, by putting its fields in the JSON body. The `--file` and
`--upload-reference` forms take no backfill fields. Backfills require
additional permissions which need to be approved by your Account Manager. The
backfill starts as soon as Intuizi has read the submission's locations, before
they are imported, so it covers the locations the brand already had, not the
ones in this submission. Deleting the submission does not cancel it.

```bash
intuizi poi submissions create --name my-locations \
  --brand-id <id> --file locations.csv
intuizi poi submissions create --list locations.json
```

The create prints the new submission's id (as `value`) and name at once.
Processing continues after it, so follow it with
`intuizi poi submissions show <id>`. A submission starts as `Importing` and
moves to `Waiting` on its own once Intuizi has read its locations. From
`Waiting`, Intuizi reviews it by hand. An approved submission becomes
`Imported`, and only then do its locations appear in `poi locations list`. A
declined one becomes `Disabled`. The review is not automatic, so do not script
a wait for `Imported`.

Only the `--upload-reference` form sends an `Idempotency-Key`. If it ends with
no response, run it again with the `--idempotency-key` the CLI printed. The
`--file` and `--list` forms send no key, and neither do the category and brand
creates, so check the matching list before running one again. See
[Idempotency](/concepts/idempotency).

See [Submit POI Data](/guides/submit-poi-data).

## Submissions list

List your submissions and their processing state. The list is not paginated:
every submission comes back in one response.
See [List Submissions](/api/v2/poi/submissions#get-apiv2my-datapoissubmissionsindex).

| Flag | Input |
| --- | --- |
| `--search` | contains match on the name |
| `--sort-by` | `name`, `status`, `created_at`, or `updated_at` |
| `--order` | `asc` or `desc` |

## Submissions show

Read one submission by id.
See [Get Submission](/api/v2/poi/submissions#get-apiv2my-datapoissubmissionsid).

## Submissions delete

Remove a submission whose status is `Waiting`. A new submission is not
`Waiting` yet: it reaches that status once Intuizi has read its locations, so a
delete sent straight after the create is refused. Check with
`intuizi poi submissions show <id>`. Once Intuizi has approved it (`Imported`)
or declined it (`Disabled`), it can no longer be deleted. Deleting a
submission does not cancel a backfill it requested.
See [Delete Submission](/api/v2/poi/submissions#post-apiv2my-datapoissubmissionsdelete-by-id).

| Flag | Input |
| --- | --- |
| `--yes` | skip the confirmation prompt |

{{< cards >}}
  {{< card link="/developers/cli/reference/projects/" title="Projects" subtitle="The folders everything is filed under." >}}
  {{< card link="/developers/cli/reference/uploads/" title="Uploads" subtitle="Send a file to Intuizi." >}}
{{< /cards >}}