> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check-in Endpoint

> Allows customers to check in to the coworking space using various authentication methods including access codes, email/password, access cards, or MAC address.

# Check-in Endpoint

Allows customers to check in to the coworking space using multiple authentication methods. This endpoint is used by the Members Portal, self-service kiosks, and access control devices (such as WiFi authenticators and door locks) to verify customer identity and grant access.

## Authentication

This endpoint does **not** require a bearer token. Instead, authentication is performed using one of the check-in methods described below. The endpoint automatically determines the customer's location based on the account subdomain.

## Request Body

The request body is a JSON object using the `CheckInRequest` type. Not all fields are required — the endpoint accepts various combinations of parameters depending on the check-in method you want to use.

### CheckInRequest Fields

| Field          | Type    | Required    | Description                                                                                                                     |
| -------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `email`        | string  | Conditional | Customer's email address. Required for email/password and email/pincode check-in methods.                                       |
| `password`     | string  | Conditional | Customer's account password. Used with `email` for credential-based check-in.                                                   |
| `pincode`      | string  | Conditional | Customer's access pincode. Can be used with or without `email`.                                                                 |
| `mac`          | string  | Conditional | Device MAC address (minimum 8 characters). Used for device-based check-in and auto-check-in.                                    |
| `token`        | string  | Conditional | Access code token. Can be a shared access token or an approved visitor invitation code.                                         |
| `accessCardId` | string  | Conditional | Physical access card ID/number. Used for card-based check-in.                                                                   |
| `disconnect`   | boolean | Optional    | If `true`, disconnects the customer from the current session instead of checking in. Requires a valid `mac` address.            |
| `toggle`       | boolean | Optional    | If `true`, toggles check-in state (checks in if not checked in, checks out if already checked in).                              |
| `doNotCheckIn` | boolean | Optional    | If `true`, performs validation but does not create a check-in record. Useful for verifying access without actually checking in. |

## Check-in Methods

The endpoint supports **six** different check-in methods. Only **one** method needs to be used per request. The methods are evaluated in the following priority order:

### 1. Access Token Check-in

Uses a shared access code token assigned to the location.

**Required fields:**

* `token` — The access code token
* `mac` — Device MAC address (minimum 8 characters)

**Example:**

```json theme={null}
{
  "token": "ABC123XYZ",
  "mac": "AA:BB:CC:DD:EE:FF"
}
```

**Behavior:**

* Validates the token against the location's access tokens
* If the token is a visitor invitation code, verifies the visitor has been approved by their host
* Records the device MAC address against the token
* Returns the session expiration time and remaining minutes
* Fails if the token has been depleted (no remaining minutes)
* Fails if the visitor has not yet been approved by their host

**Response:**

```json theme={null}
{
  "wasSuccessful": true,
  "message": "2026-06-16T18:30:00 UTC",
  "value": {
    "tunnelId": "",
    "sessionExpire": "2026-06-16T18:30:00 UTC",
    "sessionTimeOut": 3600
  }
}
```

***

### 2. MAC Address Auto-Check-in (Token-Based)

Automatically checks in a customer based on their device's MAC address if they have an associated access token.

**Required fields:**

* `mac` — Device MAC address (minimum 8 characters)

**Example:**

```json theme={null}
{
  "mac": "AA:BB:CC:DD:EE:FF"
}
```

**Behavior:**

* Looks up the largest remaining access token associated with the MAC address
* If a valid token with remaining minutes is found, uses it for check-in
* This method is independent of email/password — it uses pre-configured access tokens

***

### 3. Email and Password Check-in

Uses the customer's email and account password.

**Required fields:**

* `email` — Customer's email address
* `password` — Customer's account password

**Example:**

```json theme={null}
{
  "email": "john@example.com",
  "password": "securePassword123"
}
```

**Behavior:**

* Validates the email and password against the system
* Finds the customer's member profile (coworker) associated with the location
* If the customer is not registered with this location but sign-up is enabled, automatically registers them
* Checks device limit (configurable per location, default 20 devices)
* Creates a check-in record

***

### 4. Email and Pincode Check-in

Uses the customer's email and a numeric access pincode.

**Required fields:**

* `email` — Customer's email address
* `pincode` — Customer's access pincode

**Example:**

```json theme={null}
{
  "email": "john@example.com",
  "pincode": "1234"
}
```

**Behavior:**

* Validates the email exists in the system
* Looks up the customer's profile(s) for the location (or network-wide) where `AllowNetworkCheckin` is enabled and the `AccessPincode` matches
* If the customer is not registered with this location but sign-up is enabled, automatically registers them
* Creates a check-in record

***

### 5. Pincode-Only Check-in

Uses only a numeric access pincode without an email address.

**Required fields:**

* `pincode` — Customer's access pincode

**Example:**

```json theme={null}
{
  "pincode": "1234"
}
```

**Behavior:**

* Searches for customers with the matching pincode across the location
* **Exactly one** customer must have the pincode — if multiple customers share the same pincode, the request is rejected for security
* Automatically enables unique pincode generation for all locations in the network to prevent future conflicts
* If the customer is not registered with this location but sign-up is enabled, automatically registers them
* Creates a check-in record

**Note:** This method is typically used on self-service kiosks where customers prefer to enter only a pincode.

***

### 6. Access Card Check-in

Uses a physical access card number.

**Required fields:**

* `accessCardId` — The card ID/number

**Example:**

```json theme={null}
{
  "accessCardId": "CARD-98765"
}
```

**Behavior:**

* Looks up the customer associated with the access card ID
* Validates that the card ID matches one of the customer's registered cards (supports multiple cards separated by commas)
* If the customer is not registered with this location but sign-up is enabled, automatically registers them
* Creates a check-in record

***

### 7. MAC Address Auto-Check-in (User-Based)

Automatically checks in a customer based on their device's MAC address without requiring credentials.

**Required fields:**

* `mac` — Device MAC address (minimum 8 characters)

**Optional fields:**

* `email` — Customer's email (helps disambiguate if multiple users have the same MAC)

**Example:**

```json theme={null}
{
  "mac": "AA:BB:CC:DD:EE:FF"
}
```

**Behavior:**

* Only works if `DisableAutoChecking` is **not** enabled for the location
* Looks up the user by MAC address (optionally filtered by email)
* If both email and MAC are provided, looks up the user by both criteria
* If the customer is not registered with this location but sign-up is enabled, automatically registers them
* Creates a check-in record

**Note:** This method is typically used by WiFi access points and door controllers that automatically detect device MAC addresses.

***

### 8. Disconnect / Check-out

Disconnects a customer from the current session.

**Required fields:**

* `disconnect`: `true`
* `mac` — Device MAC address (minimum 8 characters)

**Example:**

```json theme={null}
{
  "disconnect": true,
  "mac": "AA:BB:CC:DD:EE:FF"
}
```

**Behavior:**

* Finds the largest access token associated with the MAC address
* Calculates remaining minutes since last access
* If no token is found, performs a full check-out by MAC address
* Returns immediately without creating a check-in record

***

### 9. Toggle Check-in

Toggles the customer's check-in state — checks in if not checked in, checks out if already checked in.

**Required fields:**

* `toggle`: `true`

**Optional fields:**

* Any check-in method fields (email/password, pincode, mac, etc.)

**Example:**

```json theme={null}
{
  "toggle": true,
  "email": "john@example.com",
  "password": "securePassword123"
}
```

**Behavior:**

* First authenticates the customer using the provided credentials
* If the customer is already checked in, checks them out
* If the customer is not checked in, checks them in
* Uses the customer's MAC address if provided

***

## Response

Returns an `ActionConfirmation` object.

### Success Response

```json theme={null}
{
  "wasSuccessful": true,
  "message": "2026-06-16T18:30:00 UTC",
  "value": {
    "fullName": "John Doe",
    "coworkerId": 12345,
    "tunnelId": "abc-def-ghi",
    "checkedIn": true,
    "sessionExpire": "2026-06-16T18:30:00 UTC",
    "sessionTimeOut": 3600
  }
}
```

### Check-out Response

```json theme={null}
{
  "wasSuccessful": true,
  "message": "OK",
  "value": {
    "fullName": "John Doe",
    "coworkerId": 12345,
    "checkedIn": false,
    "sessionExpire": "2026-06-16T16:00:00 UTC",
    "sessionTimeOut": 0
  }
}
```

### Error Response

```json theme={null}
{
  "wasSuccessful": false,
  "message": "Invalid card number.",
  "errors": [
    {
      "propertyName": "EventCheckIn",
      "message": "INVALID_CARD_NUMBER"
    }
  ]
}
```

### Error Codes

| Error Code                  | Message                                          | Description                                         |
| --------------------------- | ------------------------------------------------ | --------------------------------------------------- |
| `INVALID_REQUEST_DATA`      | "Invalid request data"                           | Request body is null or malformed                   |
| `INVALID_ACCOUNT_SUBDOMAIN` | "You passed a invalid account subdomain"         | Account subdomain could not be resolved             |
| `INVALID_ACCESS_TOKEN`      | "Access token is not valid."                     | Token does not exist or has expired                 |
| `VISITOR_NOT_APPROVED`      | "Visitor has not yet been approved by host."     | Visitor invitation token is not yet approved        |
| `MAC_NOT_RECEIVED`          | "MAC address was not received."                  | MAC address is required but missing or too short    |
| `TOKEN_DEPLETED`            | "This token has been used completely."           | Token has no remaining minutes                      |
| `INVALID_CARD_NUMBER`       | "Invalid card number."                           | Card ID not found or does not match customer        |
| `INVALID_CREDENTIALS`       | "Invalid username or password"                   | Email/password or email/pincode validation failed   |
| `MISSING_CUSTOMER`          | "This user does not have a member linked to it." | User exists but has no member (coworker) profile    |
| `DEVICE_LIMIT_REACHED`      | "You can't register a new device..."             | Customer has exceeded the device registration limit |
| `NO_ACCESS_TO_SPACE`        | "Coworker does not have access to this space"    | Customer is not registered with this location       |

## Common Use Cases

### Self-Service Kiosk Check-in

Kiosks typically use pincode-only or email/password check-in for customer convenience:

```json theme={null}
{
  "pincode": "1234"
}
```

### WiFi Access Point Authentication

WiFi access points use MAC address auto-check-in:

```json theme={null}
{
  "mac": "AA:BB:CC:DD:EE:FF"
}
```

### Shared Access Code for Guests

Locations can share access tokens with visitors or partners:

```json theme={null}
{
  "token": "GUEST-ACCESS-2026",
  "mac": "AA:BB:CC:DD:EE:FF"
}
```

### Door Controller with Card Reader

Physical access points use card-based check-in:

```json theme={null}
{
  "accessCardId": "CARD-98765"
}
```

## Configuration

The check-in behavior can be customized per location using business settings:

| Setting                          | Default | Description                                                                                             |
| -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `Checkin.DeviceCountLimit`       | `20`    | Maximum number of devices a customer can register                                                       |
| `Checkin.DailyCutOffTime`        | `0`     | Daily cutoff time for pass calculations                                                                 |
| `Security.GenerateUniquePincode` | `false` | When enabled, pincode-only check-in generates unique codes                                              |
| `DisableAutoChecking`            | `false` | When true, disables MAC address auto-check-in                                                           |
| `MembersSignUp`                  | `false` | When true, automatically registers customers who check in but are not yet registered with this location |

## Related Documentation

* [Check-in Methods](/platform/access-control/check-in-methods) — Overview of all check-in methods available in the Nexudus platform
* [Check-in Metrics](/api/endpoints/checkins/checkin-metrics) — Retrieve aggregate check-in metrics
* [WiFi Configuration](/platform/access-control/wifi) — Configure WiFi access control