---
title: "Pin a subscriber's location"
method: POST
path: "/v4/subscribers/{subscriber_id}/location"
tags: ["Subscribers"]
---

# Pin a subscriber's location

`POST /v4/subscribers/{subscriber_id}/location`

## Request

- Base URL: `https://api.kit.com`
- URL: `https://api.kit.com/v4/subscribers/{subscriber_id}/location`
- Auth: one of:
  - API key in header `X-Kit-Api-Key`
  - OAuth 2
    - Authorization code: `https://api.kit.com/v4/oauth/authorize`
    - Token URL: `https://api.kit.com/v4/oauth/token`

Pins an explicit location to a subscriber, overriding any location Kit has inferred from open events. Provide `city`, `state_province`, `country_code` (ISO 3166-1 alpha-2, required), `latitude`, `longitude`, and `timezone` (IANA timezone name, e.g. `America/Denver`). Returns the subscriber's `id` and the pinned `location` on success.

If the subscriber already has a pinned location this replaces it. To replace the values on an existing pin, use [Update a subscriber's pinned location](/api-reference/subscribers/update-a-subscribers-pinned-location) (PATCH); to remove the pin, use [Delete a subscriber's location](/api-reference/subscribers/delete-a-subscribers-location). The pinned location is returned on [Get a subscriber](/api-reference/subscribers/get-a-subscriber). Returns `404` when the subscriber is not found, `422` when a required field is missing or invalid.

## Path parameters

- `subscriber_id` integer, required

## Request body

- object
  - `location` object, required
    - `city` string, required
    - `state_province` string, required
    - `country_code` string, required
    - `latitude` number, float, required
    - `longitude` number, float, required
    - `timezone` string, required

## Response `200`

Pins the location and returns it

- object
  - `subscriber` object, required
    - `id` integer, required
    - `location` object, required
      - `city` string, required
      - `state_province` string, required
      - `country_code` string, required
      - `latitude` number, float, required
      - `longitude` number, float, required
      - `timezone` string, required

## Other responses

- `401`: Returns a 401 if the token and/or account cannot be authenticated
- `404`: Returns 404 for an unknown subscriber
- `422`: Returns 422 and does not persist when country_code is missing

## Changes

- **2026-11-03** `f04308f83b63`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kit/apis/kit-api/changes/v4/subscribers/:subscriber_id/location/post.md)

---

[API](https://skmtc.dev/kit/apis/kit-api.md) - [All operations](https://skmtc.dev/kit/apis/kit-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kit/apis/kit-api/revisions/f04308f83b63?raw)