# Categories


## List Categories {#get-apiv2my-datapoiscategoriesindex}

`GET /api/v2/my-data/pois/categories/index`

Lists every category available to the authenticated user's company. Each row is a
`{ value, text }` pair.

**Auth:** bearer token + `Accept: application/json`. Rate limit: read bucket (120
requests/min).

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | No | Optional free-text filter on the category name (case-insensitive contains). |

{{< tabs >}}

  {{< tab name="cURL" >}}
  ```bash
  curl "https://console.intuizi.com/api/v2/my-data/pois/categories/index" \
    -H "Authorization: Bearer <YOUR_TOKEN>" \
    -H "Accept: application/json"
  ```
  {{< /tab >}}

  {{< tab name="Python" >}}
  ```python
  import requests

  res = requests.get(
      "https://console.intuizi.com/api/v2/my-data/pois/categories/index",
      headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
  )
  categories = res.json()["data"]
  ```
  {{< /tab >}}

  {{< tab name="JavaScript" >}}
  ```javascript
  const res = await fetch(
    "https://console.intuizi.com/api/v2/my-data/pois/categories/index",
    { headers: { Authorization: "Bearer <YOUR_TOKEN>", Accept: "application/json" } }
  );
  const categories = (await res.json()).data;
  ```
  {{< /tab >}}

  {{< tab name="PHP" >}}
  ```php
  $res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
      ->get('https://console.intuizi.com/api/v2/my-data/pois/categories/index');
  $categories = $res->json('data');
  ```
  {{< /tab >}}

{{< /tabs >}}

### Response

```json
{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "value": 123,
      "text": "Demo Category"
    }
  ]
}
```

## Create Category {#post-apiv2my-datapoiscategoriescreate}

`POST /api/v2/my-data/pois/categories/create`

Creates a new category for the authenticated user's company under a segment.

**Auth:** bearer token + `Accept: application/json` + `Content-Type:
application/json`. Rate limit: write bucket (30 requests/min).

### Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | The category name. |
| `segment_id` | integer | Yes | The parent segment id. Must exist. |

{{< tabs >}}

  {{< tab name="cURL" >}}
  ```bash
  curl -X POST "https://console.intuizi.com/api/v2/my-data/pois/categories/create" \
    -H "Authorization: Bearer <YOUR_TOKEN>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
      "name": "Train Stations",
      "segment_id": 123
    }'
  ```
  {{< /tab >}}

  {{< tab name="Python" >}}
  ```python
  import requests

  res = requests.post(
      "https://console.intuizi.com/api/v2/my-data/pois/categories/create",
      headers={
          "Authorization": "Bearer <YOUR_TOKEN>",
          "Content-Type": "application/json",
          "Accept": "application/json",
      },
      json={"name": "Train Stations", "segment_id": 123},
  )
  category = res.json()["data"]
  ```
  {{< /tab >}}

  {{< tab name="JavaScript" >}}
  ```javascript
  const res = await fetch(
    "https://console.intuizi.com/api/v2/my-data/pois/categories/create",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer <YOUR_TOKEN>",
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({ name: "Train Stations", segment_id: 123 }),
    }
  );
  const category = (await res.json()).data;
  ```
  {{< /tab >}}

  {{< tab name="PHP" >}}
  ```php
  $res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
      ->post('https://console.intuizi.com/api/v2/my-data/pois/categories/create', [
          'name' => 'Train Stations',
          'segment_id' => 123,
      ]);
  $category = $res->json('data');
  ```
  {{< /tab >}}

{{< /tabs >}}

### Response

```json
{
  "status": "success",
  "code": 201,
  "message": "Resource created successfully.",
  "data": {
    "value": 123,
    "text": "Train Stations"
  }
}
```

Unlike [Create Brand](/api/v2/poi/brands#post-apiv2my-datapoisbrandscreate)
and the submission creates, which return `data` as a one-element array, this
create returns `data` as a single object: read the new category's id at
`data.value`.

Failed requests use the shared error envelope - see [Errors](/concepts/errors).