import { Aside, Steps } from '@astrojs/starlight/components';

The Track integration verifies the applicant of each qualifying reservation in your Track account automatically. You connect once, choose the workflow the verification runs and the [verification timing](/guides/integrations/verification-timing), and each qualifying reservation starts a verification for the applicant when its verification opens (by default, as soon as the integration reads it), without any manual step. The verification's status is written onto the reservation as a tag, and the applicant's verification link and an internal review link are written on as private notes, so your team sees them where they already work.

This page covers the Track integration specifically. For the full list of available integrations and how connections work in general, see the [Integrations overview](/guides/integrations).

## When to use

Connect Track when you want reservations to trigger identity verification on their own, instead of adding each applicant by hand or through the API. It suits teams that:

- Take reservations in Track and want every confirmed applicant verified before arrival.
- Want the verification status and links visible on the reservation, so reviewers and front-desk staff do not switch tools.
- Want to control which reservations get verified (for example, skip held reservations, or run some on a different workflow) with routing rules rather than code.

If you only verify applicants occasionally, or you drive verification from your own system, the [API](/reference) or a [bulk CSV import](/guides/verification/bulk-import-csv) may fit better. You can use the integration alongside either.

## How it works

Track has no webhooks, so the integration cannot be notified the instant a reservation changes. Instead, once connected, it checks Track for new and updated reservations on its own schedule:

1. **The integration checks Track.** This happens every few minutes, so a reservation is typically picked up within about 5 minutes of being created or updated in Track.
2. **The reservation status decides the action.** The integration reads the reservation and acts on its status (see the table below). A confirmed, checked-in, or checked-out reservation gets its verification link, and starts a verification when its verification opens if it does not already have one; a held reservation is skipped; a canceled reservation withdraws a verification still waiting on the guest or on your account's funds, and one already being checked or decided keeps its result.
3. **A verification is started.** For a reservation that should be verified, the integration starts a verification bound to the default workflow you chose when connecting, or to the workflow a routing rule selects for it. It starts when the reservation's verification opens. Before then, the applicant's link shows when they can start. The reservation's contact details are carried onto the applicant so reviewers can identify them in the console, and Track's reservation number is stored as the applicant's external reference.
4. **The applicant is invited, if the invite is on.** A new connection, including one you connect again after a disconnect, starts with **Send the verification invite** off. Turn it on to have the platform email the applicant their verification link; leave it off if you would rather send the link yourself from Track using the note field described below. A connection that already exists keeps its setting, which the connection's **Edit** drawer shows.
5. **The status and links are written back.** The verification's status is kept in step as a tag on the reservation. The verification link is written as a private note as soon as the reservation qualifies, before any verification starts, and an internal review link is written as a private note when the verification starts.

### What each reservation status does

The integration decides what to do from the reservation's status. This is the default behavior for a new connection:

| Track status | Console record status | What happens                                                                                                                                |
| ------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Hold         | Inquiry               | Skipped by default. This is a held or pre-commitment booking, not a committed stay.                                                         |
| Confirmed    | Confirmed             | Starts a verification if the reservation does not already have one.                                                                         |
| Checked In   | Confirmed             | Starts a verification if the reservation does not already have one; leaves an existing verification as is.                                  |
| Checked Out  | Confirmed             | Starts a verification if the reservation does not already have one; leaves an existing verification as is, never withdrawing it.            |
| Cancelled    | Canceled              | A verification still waiting on the guest, or on your account's funds, is withdrawn; one already being checked or decided keeps its result. |

A reservation that starts a verification gets its verification link as soon as it qualifies. The verification itself starts when the reservation's verification opens, which with the default timing is at once.

<Aside type="note" title="Which reservations create a verification">
  The skip for Hold reservations comes from a routing rule that is added for you when you connect,
  matching **Record status: Inquiry**. You own that rule: you can edit or remove it, and you can add
  rules of your own (for example, to skip a particular booking source). Confirmed, Checked In, and
  Checked Out reservations all share the one console record status, **Confirmed**, so a routing rule
  cannot target just one of them; together they are always verified, if not verified already, unless
  one of your routing rules skips them, and they run on the default workflow unless a routing rule
  selects another workflow. Cancelled reservations are handled without a rule: a cancellation
  withdraws a matching verification that is still waiting on the guest or on your account's funds,
  rather than starting a new one; one already being checked or decided keeps its result.
</Aside>

<Aside type="note" title="The integration is forward-only">
  The integration only reads a reservation that is created or changes after you connect; it does not
  use the date a reservation was originally created to choose which reservations to read. A
  reservation that has not changed since you connected is never read, no matter how old it is. But
  an old reservation that changes for the first time after you connect, for example because it
  checks in, is read and treated like a new one: if it does not already have a verification, one
  starts, and you are billed for it. To keep a specific old reservation from starting a verification
  this way, add a routing rule that matches its **Reservation ID** (the reservation's Track number)
  before it next changes. A verification you start yourself for that reservation, through the API or
  a bulk CSV import, is not linked to it: the integration still starts its own when the reservation
  changes, and neither one gets the tag or the notes.
</Aside>

Only the verification status and the two link notes are ever written back to Track. No applicant personal data is sent to Track.

### Reservation fields you can use in routing rules

Routing rules match on the fields the integration reads from each Track reservation. On a Track connection, the rule builder names most of these fields the way Track does. The first column below is the name that you look for in the rule builder. The table lists the rows in alphabetical order, the same order as the rule builder. The other columns show where the value comes from on the reservation, and how **is one of** compares it:

| Rule field        | Taken from the Track reservation                                                                            | How **is one of** compares it                                  |
| ----------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Arrival           | The reservation's arrival time, exactly as Track stores it.                                                 | Exactly, so enter the full value Track stores, not just a day. |
| Channel           | The channel the booking came through. A separate field from Sub-channel below, not its parent.              | Ignoring capitalization.                                       |
| Confirmation code | The reservation number, the same value as Reservation ID below. Track keeps no separate booking code.       | Ignoring capitalization.                                       |
| Currency          | Reservation currency.                                                                                       | Ignoring capitalization.                                       |
| Departure         | The reservation's departure time, exactly as Track stores it.                                               | Exactly, so enter the full value Track stores, not just a day. |
| Email             | Contact primary email, falling back to the secondary email when the primary is empty.                       | Ignoring capitalization.                                       |
| First name        | Contact first name.                                                                                         | Ignoring capitalization.                                       |
| Full name         | Contact name.                                                                                               | Ignoring capitalization.                                       |
| Grand total       | Guest breakdown grand total.                                                                                | By value, so 1557 matches 1557.00.                             |
| Last name         | Contact last name.                                                                                          | Ignoring capitalization.                                       |
| Lead time (days)  | The whole days between the day the reservation was booked and its arrival day.                              | As a whole number of days, so +03 matches 3.                   |
| Node ID           | The node the reservation's unit belongs to, as a number.                                                    | Exactly, including capitalization.                             |
| Phone             | Contact cell phone, falling back to home, other, then work.                                                 | Digits only, so any punctuation you use is fine.               |
| Rate type code    | The code of the reservation's rate type, not its name and not its id.                                       | Ignoring capitalization.                                       |
| Rate type name    | The name of the reservation's rate type. This is the one the reservation screen shows.                      | Ignoring capitalization.                                       |
| Record status     | The reservation's status, normalized to the values in the table above.                                      | Exactly, from the fixed list above.                            |
| Reservation ID    | The reservation number. The value the integration writes back against.                                      | Exactly, including capitalization.                             |
| Reservation type  | The reservation's type in Track, by name, such as Guest Direct or Owner.                                    | Ignoring capitalization.                                       |
| Sub-channel       | The booking's sub-channel. A separate field from Channel above, empty on most reservations.                 | Ignoring capitalization.                                       |
| Unit address      | The unit's address, joined into one line: street, extended address, city, region, postal code, and country. | Ignoring capitalization, and the whole line must match.        |
| Unit ID           | The reservation's unit.                                                                                     | Exactly, including capitalization.                             |
| Unit time zone    | The unit's time zone.                                                                                       | Ignoring capitalization.                                       |

**is not one of** and **is not one of, or empty** ignore invisible characters and treat different forms of the same character as equal, such as a full-width `Ａ` and `A`. On the fields marked Exactly, they also ignore capitalization and spaces at the start and end.

A few rows are worth a second look:

- **Record status is ours, not Track's.** It is the reservation's Track status put through the table above, so a rule on it picks from Confirmed, Inquiry, Pending, Canceled, and Excluded, never from Hold, Checked In, or Checked Out. A Track reservation only ever carries Confirmed, Inquiry, or Canceled. That is why this one field keeps a platform name in the drawer while the rest use Track's.
- **Confirmation code and Reservation ID are the same number.** Track has no guest-facing booking code separate from the reservation number, so a rule on either compares the same value. Use Reservation ID, which is also the value every write-back is addressed to.
- **Channel and Sub-channel are two separate fields, and one does not contain the other.** The names suggest a hierarchy and the data does not have one: a reservation can carry a channel with no sub-channel, a sub-channel with no channel, both, or neither. Most reservations that come through a channel carry no sub-channel at all, and some reservations carry only a sub-channel. So a rule on one of them does not cover the other, and to skip everything from a given booking source you may need a value on each. To exclude a whole channel, start with Channel. Where you connect an OTA through a channel manager, Track usually records the channel manager as the Channel and the OTA itself as the Sub-channel, so that case needs the rule on Sub-channel.
- **Neither Channel nor Sub-channel is the rate type.** To match the rate instead, use Rate type code or Rate type name, which are separate fields. If you need to route on something this table does not list, tell us which Track field it is and we will look at adding it.
- **Rate type code and Rate type name are both available, because Track shows different ones in different places.** A Track rate type has a short code and a longer name, and the reservation screen shows the NAME. If you read a rate on a reservation, use Rate type name. Enter the name the way that it appears there, for example `Standard Rate`. Use Rate type code, for example `R1`, when you are working from the rate type itself in Track. If you enter the name in the code field, or the code in the name field, the value equals nothing. Then **is one of** never matches, and **is not one of** leaves nothing out.
- **Reservation type is how you skip owner stays.** Track marks a reservation type as an owner type in that type's own settings, and a routing rule matches the type's NAME as the reservation screen shows it. So list the type names your account uses for owner stays, for example `Owner` and `Owner Guest`, rather than looking for a single owner switch. Check the names first: an account can have an owner type whose name does not contain the word owner, and that one has to be listed too. We do not offer the owner setting itself as a rule field because it is a checkbox on the reservation type rather than a value you can read on a reservation, so there would be nothing for you to enter.
- **Node ID is a number.** Track gives a node no code and no short name, so a rule on this field takes the numeric id. Read that id off the node in Track. Use Node ID to skip every unit under one node at once, and Unit ID to skip a single unit.
- **Lead time (days) is worked out from two dates, on the unit's calendar.** It counts the calendar days from the day the reservation was booked to its arrival day. A reservation booked at 9:30 PM the evening before it arrives has a lead time of `1`, not `0`. `0` is the same day. A reservation booked after its arrival day has a negative lead time. The arrival day is the arrival date that Track stores, or the day of the arrival time when there is no arrival date. The booking time is the one that Track records, or the creation time when Track records no booking time. The booking time, and an arrival time, are placed on the calendar of the unit's time zone (the value of the Unit time zone field). An arrival date is not converted. The count uses Track's own dates and never the day the integration read the reservation. The rule builder also offers **is less than**, **is at most**, **is greater than**, and **is at least** for this field. The [Integrations overview](/guides/integrations#routing-rules) describes them.
- **A reservation with no lead time matches no condition on it.** A reservation with no unit assigned has no unit time zone, so it has no lead time. The same is true if the unit's time zone is not a valid time zone name, if Track sends no booking time and no creation time, or if Track sends neither an arrival date nor an arrival time. Whatever the operator, no condition on Lead time (days) matches such a reservation. So a **Skip verification** rule on this field never skips it.
- **Owner stays have a lead time like any other reservation.** To keep a rule on Lead time (days) off owner stays, add a second condition to the same rule: the Reservation type field with the operator **is not one of, or empty**, and the names of your account's owner types, as described above.

Only Arrival and Departure need the value in Track's own format. A rule on either compares the stored value as-is, so copy it from the reservation rather than typing a calendar date.

A field that is empty on the reservation is empty to the rule as well. A condition that uses **is one of** or **is not one of** never matches an empty field. A condition that uses **is not one of, or empty** matches it. If a rule has no effect, first make sure that its fields are not empty on the reservation.

A rule can have more than one condition, and it matches a reservation only when all of them match. For example, a rule can have two conditions: Unit ID **is one of** `L-100`, and Sub-channel **is not one of, or empty** `Example Channel`. That rule matches each reservation at unit `L-100` that does not have the Sub-channel `Example Channel`, in any capitalization. Sub-channel is empty on most reservations, so with **is not one of** the rule would not match most of them. A **Skip verification** rule with these two conditions also skips the reservations at `L-100` whose Sub-channel is empty. The rule builder shows no warning for this rule, because Unit ID uses **is one of**. The [Integrations overview](/guides/integrations#routing-rules) describes each operator.

## Status tag and notes on the reservation

Track has no custom fields on reservations, so the integration writes back using a status tag and two private notes instead.

### Status tag

The integration keeps exactly one of eight tags on the reservation, replacing it as the screening progresses. The tags say **Guest screening** rather than naming one kind of check, because a workflow may run an ID check, a background check, or neither: the tag reports how far the applicant's screening has progressed, whatever checks it contains.

| Tag                                        | When it is applied                                                                                       |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| Guest screening: Pending                   | The screening has started and has not yet reached review.                                                |
| Guest screening: In review                 | The screening is awaiting your team's review, or finished with no outcome recorded yet.                  |
| Guest screening: Approved                  | The screening was approved.                                                                              |
| Guest screening: Declined                  | The screening was declined.                                                                              |
| Guest screening: Not completed             | The screening expired, or was canceled without reaching an outcome.                                      |
| Guest screening: Not yet open              | Screening for the reservation has not opened yet.                                                        |
| Guest screening: Not started               | Screening for the reservation is open, and no screening is in progress for the guest.                    |
| Guest screening: Not completed by deadline | The screening deadline passed before the guest finished, or too little time was left to start screening. |

These eight names are managed by the integration. It creates all eight in your Track account the first time it needs to apply one to a reservation, not when you connect. Do not reuse one of these eight names for your own tags: the integration treats any tag with a matching name as its own, and the next status change replaces or recreates whichever one the current status needs.

### Applicant link and review link

The integration adds two private notes to the reservation:

- **Screening link for the guest** carries the reservation's verification link. It is added as soon as the reservation qualifies, before any verification starts. Share this with the applicant if you send invites yourself.
- **Screening review link** carries an internal link your team uses to open the verification in the console. It is added when the verification starts. Not for the applicant.

Both notes are created as private folio notes, marked to keep them from the reservation's guest. A note is not edited or recreated afterward, so a note you remove by hand stays removed. The reservation's verification link stays the same for the whole verification window. If it changes, because the reservation is restored in Track after a cancellation or its contact changes, the integration adds a new **Screening link for the guest** note, and the link in the earlier note stops working. A canceled reservation's link stops working, and no new note is added. You can always find both links by opening the verification directly in your Applicants list, whether or not the note is still there.

An applicant can open their verification link again after finishing. They then see where their verification stands (for example, submitted and under review) instead of an error. The link never reopens a finished verification. An applicant whose earlier verification lapsed before any paid check can start again from the same link while verification is open.

## Connecting Track

You need the **Owner** or **Admin** role, an active organization, and at least one [workflow template](/guides/workflows/workflow-templates-create) to bind the connection to. Create a workflow first if you do not have one; the connect form links you to the workflow editor when none exist.

You connect using your **account domain** and a Track server key: an **API key** and an **API secret**.

<Steps>

1. In Track, open **Configuration → Company Setup → API Keys** and create a **server key**. Track also offers channel keys, which only see channel-enabled reservations and reach no write-back endpoint, so create a server key, not a channel key.

2. In the console, open **Integrations** and choose **Track**.

3. Enter your **account domain**, the address you sign in to, for example `yourcompany.trackhs.com`.

4. Enter the server key's **API key** and **API secret**.

5. Choose the **default workflow** the integration runs for each reservation. This is required. Every verification the connection creates uses this workflow unless a routing rule skips it or selects another workflow. The list shows your active workflows, with your organization default marked.

6. (Optional) Add **routing rules** to change which reservations are verified. The connection starts with a rule that skips Hold reservations by matching **Record status: Inquiry**. You can keep it, edit it, or remove it, and add rules of your own. Each rule has one or more conditions, and each condition compares a field (such as Record status or Sub-channel) with one or more values. When all of its conditions match, the rule either skips the reservation or selects the workflow it runs.

7. (Optional) Turn on the **Send the verification invite** toggle to have the platform email each applicant their verification link. It is off for a new connection. Leave it off if you plan to send the link yourself from Track using the note described above.

8. (Optional) Set the **Verification timing**. By default, verification opens when a reservation reaches Checktiv and is due at the first verification's own deadline. To open it later or make it due at another time, see [Verification timing](/guides/integrations/verification-timing).

9. Select **Connect**. The button stays disabled until a workflow is chosen and the account domain, API key, and API secret are all filled.

</Steps>

When you select Connect, the platform first checks that the server key can read reservations and manage tags; once that check passes, the connection appears in your Integrations list. Tags are created the first time the integration needs to apply one, not at connect.

## While Track needs reconnecting

If Track rejects the stored server key, for example because it was revoked or regenerated, the connection shows **Reconnect needed** and stops reaching Track: it stops checking for new and updated reservations, and any status tag or note that would be written back is held instead. Nothing already written to Track is undone.

Once you reconnect with a working server key, the integration picks up where it left off: it resumes checking Track from before the interruption, so reservations that changed while it needed reconnecting are still read. It also rebuilds the status tag and both notes for every verification that was waiting, as long as it had been waiting less than 14 days; reconnect promptly, since one waiting longer is not rebuilt automatically. For a reservation that has a screening window, the 14-day limit does not apply to the reservation's status tag and its **Screening link for the guest** note. They are rebuilt until 30 days after the latest of these dates: the day screening opens, the screening deadline, and the check-out date. For a canceled reservation, they are rebuilt until 30 days after the cancellation. You do not need to do anything else beyond reconnecting.

<Aside type="tip" title="Reconnecting">
  Open the integration and choose to reconnect. Your **account domain** is already shown and cannot
  be changed, so all you enter is a fresh **API key** and **API secret**; both are required. Your
  workflow choice, routing rules, and invite setting are preserved through a reconnect. You cannot
  use reconnect to point the connection at a different Track account: to connect a different
  account, add a new connection instead.
</Aside>

## If you see "Some updates from the connected system could not be read"

When an unusually large or fast-changing batch of reservations cannot be fully read after repeated attempts, the integration sets that period aside instead of getting stuck on it, and shows this notice on the connection:

> Some updates from the connected system could not be read. Check recent records and send verification links if needed, then dismiss this notice.

For the period the notice covers, the integration may have missed more than a status update: a new reservation that should have started a verification, and a cancellation that should have withdrawn one (so you could be billed for a verification you no longer need). Reservations outside that period are unaffected, and the connection keeps working normally afterward.

If you see this notice, compare your recent reservations in Track against your Applicants list for the affected period and act on anything missing: start a verification for a reservation that should have one, or cancel one you no longer need. If your workflow's document prints the transaction amount, currency, or location, starting a verification by hand or through a bulk CSV import will not carry those details; use the API with the `metadata` object instead.

Once you have checked, select **Dismiss** on the notice to clear it. Entering a new API key and API secret for the connection, with **Reconnect** or **Edit**, also clears it. It does not clear on its own.

## Troubleshooting

**The connection did not go through.**
Check, in order:

- The API key or API secret was not accepted. Check them against Track's API Keys page. The console shows: "These credentials were not accepted. Check the values you entered and try again."
- You entered a channel key. Create a server key instead, under **Configuration → Company Setup → API Keys**.
- The account domain could not be reached, or is not a Track address. It must end in `trackhs.com`, for example `yourcompany.trackhs.com`; a pasted sign-in URL also works, as long as it points to that address.
- Track was temporarily unavailable. Wait a moment and try connecting again.

**The connection shows "Reconnect needed."**
The stored server key is no longer valid, usually because it was revoked or regenerated in Track. Open the integration, choose to reconnect, and enter a fresh API key and API secret; your account domain is already shown and cannot be changed. See [While Track needs reconnecting](#while-track-needs-reconnecting) above for what happens to reservations and write-backs in the meantime.

**The connection shows "Not responding. We will keep retrying automatically."**
Track has been unreachable or timing out for a while. This clears on its own once Track responds normally again; you do not need to do anything.

**The connection is paused and shows "The saved credentials are no longer accepted. Use Edit to enter working credentials to resume."**
Edit the connection and enter a working API key and API secret; your account domain is already shown and cannot be changed. Saving working credentials returns the connection to active on its own; there is no separate step after that. Trying to resume the connection before that is done shows: "Enter working credentials for this integration to resume."

**A reservation did not create a verification.**
Check, in order:

- **The verification timing.** A reservation whose verification has not opened yet already has its link note, and its tag is **Guest screening: Not yet open**. Its verification starts when verification opens. See [Verification timing](/guides/integrations/verification-timing).
- **The reservation status.** Only Confirmed, Checked In, and Checked Out reservations start a verification, and only when the reservation does not already have one. A Hold reservation is skipped until it is confirmed, and a Cancelled reservation never starts one. See the [status table](#what-each-reservation-status-does) above.
- **Routing rules.** A reservation that matches a Skip rule is intentionally not verified, and one that matches a Select workflow rule runs that rule's workflow instead of the default. Review the connection's rules, including the rule that skips Hold reservations (Record status: Inquiry), against the reservation's fields (for example, its record status or sub-channel).
- **The check schedule.** The integration checks Track roughly every 5 minutes, so a very recently changed reservation may not have been picked up yet.
- **Whether the reservation has changed since you connected.** The integration only reads a reservation that changes after you connect; one that has not changed is never read, however old it is. See [The integration is forward-only](#what-each-reservation-status-does) above.
- **The workflow.** The connection must be bound to an active workflow. A workflow an integration uses cannot be deactivated or deleted from the console or the API, but a connection set up before that protection can still point at an inactive default workflow. The connection's form flags it; edit the connection and choose an active one.

**An applicant did not receive their invite.**
Confirm the **Send the verification invite** toggle is on for the connection. A new connection starts with it off, and while it is off the platform does not email the applicant; you are expected to send the link yourself using the note the integration wrote onto the reservation. Turning it on invites each applicant whose verification opens after the change. To invite an applicant whose verification already started, open it in your **Applicants** list and select **Send invite** (see [Resend or revoke](/guides/verification/send-an-invite#resend-or-revoke)). If their verification has not started yet, share the link in the note the integration wrote onto the reservation. Also confirm the reservation carried an email address for the applicant, since there is no address to send to otherwise. If that email address reached the [per-recipient invite limit](/developers/rate-limits#per-recipient-invite-limit) of three invite emails in an hour, the verification starts but Checktiv sends no invite. Open that verification in your **Applicants** list and select **Send invite**.

**The status tag is missing or looks wrong.**
The eight status tag names are managed by the integration; see [Status tag](#status-tag) above. If a tag is simply absent, the next status change replaces it with the correct one. If the verification has already reached its final status and will not change again, the tag stays as it is; this does not affect the verification itself.

**A note is missing from the reservation.**
The integration adds the screening link note when the reservation qualifies and the review link note when the verification starts, and does not recreate a note removed afterward. You can still find both links by opening the verification directly in your Applicants list.

**You want to stop the integration.**
Pausing stops the integration from checking Track for new and updated reservations, but it does not stop a write-back already under way: a verification that was already in progress keeps updating its status tag as it moves through review, since that happens independently of the check schedule. Reservations that change while paused are not read once you resume, unless they change again afterward; resuming does not catch up the way reconnecting does. Disconnecting removes the connection entirely and stops all future write-backs. Verifications that already started continue either way, but disconnecting also makes the verification links on your reservations stop working. While a connection is paused, an applicant who opens their link is asked to try again later. To start again later, resume a paused connection, or connect again if you disconnected it; after you connect again, a reservation gets a new link the next time it changes in Track.

## Related

- [Integrations overview](/guides/integrations)
- [Create a verification workflow template](/guides/workflows/workflow-templates-create)
- [Glossary](/glossary)