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

# Core concepts

> The handful of objects the whole API is built on.

Everything in Vizito hangs off a **location**. Get that one right and the rest of the API follows.

## Location

A location is one reception: an office, a plant, a site. In the API it is called `company_id` and it is a 24-character id.

Your API key is pinned to a set of locations. `GET /api/companiesList` lists them, and any request naming a location outside that set is refused with `403`.

<Note>
  Historically a location is called a "company" in the API paths and payloads. Read `company_id` as "location id" everywhere.
</Note>

## Visit type

A visit type is the flow a visitor goes through: which questions are asked, which agreements have to be signed, whether a badge is printed, who gets notified and what the confirmation email says.

Every location has at least one and one of them is the default. If you sign a visitor in without naming a visit type, the location's default is used.

Visit types matter to you for one practical reason: **the questions asked, and therefore the fields you may send, are defined per visit type**. See [Visit types](/api-reference/visit-types/listing-visit-types).

## Visitor

A visitor is one visit — a single sign-in event, not a person. Signing the same person in twice creates two visitors.

A visitor is signed in when `signed_in` is set, and still inside as long as `signed_out` is absent.

| Field                                | Meaning                                           |
| ------------------------------------ | ------------------------------------------------- |
| `first_name`, `last_name`, `company` | Who is visiting                                   |
| `email`, `phone`                     | How they can be reached                           |
| `recipient`, `recipient_mail`        | The host they came to see                         |
| `visit_type`                         | Id of the visit type used                         |
| `signed_in`, `signed_out`            | Timestamps of the visit                           |
| `signed_in_source`                   | `0` Backoffice/API · `1` kiosk · `2` contactless  |
| `known_visitor_id`                   | Set when the visit came from a registered visitor |
| `entrypoint_id`                      | Which entrance the visitor used                   |

On top of that, every custom field the visit type defines is stored on the visitor under its own `field_name`.

## Registered visitor

A registered visitor (`knownvisitor` in the API) is an **expected** visitor: someone you pre-register before they arrive. It carries the same personal details as a visitor, plus:

| Field         | Meaning                                                                  |
| ------------- | ------------------------------------------------------------------------ |
| `visiting_on` | The day, or a `{ startDate, endDate }` range, the visit is expected      |
| `persistent`  | Keep the record after the visit — a contractor who comes back every week |
| `visit_type`  | The flow they will go through when they arrive                           |
| `language`    | Language of the invitation email                                         |

When they arrive and sign in, a **visitor** is created from them and the registered visitor stays as it was. That is the link `known_visitor_id` records.

## Host

A host (`visitee` in the API) is a person who can be visited: the list reception picks from, and the autocomplete a visitor types into on the kiosk.

Hosts come in two flavours:

* **Managed hosts** — created in the Backoffice or through `POST /api/visitees`, edited one by one.
* **External hosts** — pushed in bulk from your directory with `POST /api/visitees/external/upload/{company_id}`. They are replaced as a set on every push and are deliberately kept out of the regular host list endpoint.

## Entry point

An entry point is a door or a desk within a location — "Main entrance", "Loading bay". Kiosks are assigned to one, and every visit records the entry point it came through, so you can report per entrance.

## Agreement

An agreement is a document a visitor has to read and sign: an NDA, a safety instruction, a video. Agreements are attached to visit types, and the signed result can be downloaded as a PDF per visit.

## How they fit together

```mermaid theme={null}
flowchart LR
  L[Location] --> VT[Visit type]
  L --> H[Hosts]
  L --> EP[Entry points]
  VT --> A[Agreements]
  RV[Registered visitor] -->|arrives| V[Visitor]
  VT -.defines fields of.-> V
  H -.recipient of.-> V
  EP -.recorded on.-> V
```


## Related topics

- [Quickstart](/documentation/quickstart.md)
- [Introduction](/index.md)