---
title: "Create Field Event"
method: POST
path: "/api/v1/events"
tags: ["Events"]
---

# Create Field Event

`POST /api/v1/events`

Record a field sales event such as a check-in or check-out at an outlet.
Only `event`, `event_timestamp`, and `user_id` are required. All other fields are optional.

## Fields

| Payload Field        | Reference Field                                  | Type                   |
|----------------------|--------------------------------------------------|------------------------|
| `event`              | determines `tcpl_checkIn__c`/`tcpl_checkOut__c`  | Enum                   |
| `event_timestamp`    | `tcpl_checkIn__c` or `tcpl_checkOut__c`          | DateTime (ISO 8601 UTC)|
| `user_id`            | `tcpl_salesRep__c`                               | String                 |
| `outlet_id`          | `tcpl_beatPlanOutlet__c`                         | String                 |
| `latitude`           | `tcpl_GeolocationCaptured__Latitude__s`          | String (Decimal 18,15) |
| `longitude`          | `tcpl_GeolocationCaptured__Longitude__s`         | String (Decimal 18,15) |
| `visit_type`         | `tcpl_visitType__c`                              | Picklist               |
| `geo_adherence`      | `tcpl_Geo_Adherence__c`                          | Boolean                |
| `beat_id`            | `tcpl_Beat_Master__c`                            | String                 |
| `outlet_geo_change`  | `tcpl_OultetGeoChange__c`                        | String                 |

## IMPORTANT: Latitude and Longitude must be STRINGS
Send coordinates as quoted strings to preserve full decimal precision.
- Correct:   `"latitude": "28.613929500000000"`
- Incorrect: `"latitude": 28.613929500000000` (precision lost due to float conversion)

## Visit Type Allowed Values (case-sensitive)
- `Joint Visit`
- `Visit`
- `Sub DB Check-In`
- `Pragati DB Check-In`
- `RPD DB Check-In`
- `DB Check-In`
- `Super DB Check-In`
- `Jump call`

## Example Request
```json
{
  "event": "CHECK_IN",
  "event_timestamp": "2026-02-12T08:00:55.944Z",
  "user_id": "+91 2222222222",
  "outlet_id": "a1JTE000000cU1w2AE",
  "latitude": "13.0378136",
  "longitude": "77.6167799",
  "visit_type": "Visit",
  "geo_adherence": false,
  "beat_id": "a10TE000000fQeTYAU",
  "outlet_geo_change": "RequestBypass"
}
```

## Request body

- EventCreateRequest — Request model for field sales events (check-in / check-out). Reference field mapping: user_id -> tcpl_salesRep__c event -> determines tcpl_checkIn__c or tcpl_checkOut__c event_timestamp -> tcpl_checkIn__c / tcpl_checkOut__c value outlet_id -> tcpl_beatPlanOutlet__c beat_id -> tcpl_Beat_Master__c visit_type -> tcpl_visitType__c geo_adherence -> tcpl_Geo_Adherence__c latitude -> tcpl_GeolocationCaptured__Latitude__s longitude -> tcpl_GeolocationCaptured__Longitude__s outlet_geo_change -> tcpl_OultetGeoChange__c
  - `event` 'CHECK_IN' | 'CHECK_OUT', required — Supported field event types.
  - `event_timestamp` string, date-time, required — ISO 8601 date-time in UTC. Examples: '2026-02-11T09:08:18.000Z', '2024-01-15T10:30:00Z'
  - `user_id` string, required — DSR / sales rep identifier (phone number with country code). Example: '+91 1234123412'
  - `outlet_id` string, nullable — Beat plan outlet identifier.
  - `latitude` string, nullable — Latitude coordinate as STRING to preserve precision. Decimal(18,15): up to 3 digits before decimal, up to 15 after. Example: '28.613929500000000'
  - `longitude` string, nullable — Longitude coordinate as STRING to preserve precision. Decimal(18,15): up to 4 digits before decimal, up to 15 after. Example: '77.209015500000000'
  - `visit_type` 'Joint Visit' | 'Visit' | 'Sub DB Check-In' | 'Pragati DB Check-In' | 'RPD DB Check-In' | 'DB Check-In' | 'Super DB Check-In' | 'Jump call' — Allowed visit types. Maps to tcpl_visitType__c picklist. Case-sensitive.
  - `geo_adherence` boolean, nullable — Whether the visit location is within allowed geo radius.
  - `beat_id` string, nullable — Beat master identifier.
  - `outlet_geo_change` string, nullable — Outlet geo-fence change request status. Example: 'RequestBypass'
  - `mavic_user_id` string, nullable — Mavic platform user identifier.

## Response `200`

Successful Response

- EventCreateResponse — Response model for event creation.
  - `success` boolean — Event logged successfully
  - `message` string, required — Confirmation message
  - `neo_user_id` string, nullable — Resolved NeoSapien user ID. Present for CHECK_IN/CHECK_OUT events.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/neosapien/apis/neocore.md) · [All operations](https://skmtc.dev/neosapien/apis/neocore/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/neosapien/neocore/revisions/8b94ef58f2cf/schema)