xMatix
Sign in Request demo
xMatix
PRODUCTS
SalesField Sales & SFACRMRewardsClaimsInventoryProcurementWarehouse ManagementField ServiceServiceSupportTelephony & MessagingFinance & AccountingPayrollExpense ManagementCommercePortalsAnalytics & ReportingData StudioMobile AppSee all products →
PLATFORM
Platform overviewApp BuilderAutomationIntegrationsSecurity & GovernanceChange ManagementDevelopers
SENSE AI
Sense AI overviewSense AssistSense ControlSense VisionAI StudioTrust & governanceIn Claude & ChatGPTUse cases
SOLUTIONS
Auto DMSConsumer Goods DMSSales Force Automation (SFA) FMCG & DistributionManufacturing & Dealer NetworksAutomotive & DealershipsPharma & HealthcareConsumer DurablesAgri-InputsBuilding MaterialsService NetworksWarehousing & 3PLFinancial AccountingERP SoftwareIndia GST ComplianceUAE VAT & e-InvoicingSaudi ZATCA & VATAll solutions →
RESOURCES
Knowledge CenterDeveloper & CLIBlogGuidesWhat is xMatix?Company facts
COMPANY
AboutCareersPartnersEventsContactAuthorsLegal
Sign in Request demo
Home/Docs/Entity Reference/Visit — entity reference
REFERENCE · Last reviewed

Visit — entity reference

One stop on a field executive's day: a call on one outlet, usually inside a visit plan. Visits are created when a visit plan is saved (one per approved stop of its visit route, one per member of its account group, or one per pending delivery order for an Order Delivery plan), by a van run, or by hand from the Visits list in the Field Sales app. The executive starts, optionally pauses, and ends the visit on the mobile app or on the visit's web record page. Ending always sets Visit Status to Completed; the outcome is shown by which reason is filled (none = Productive, Non-Productive Reason = Non-productive, Visit Cancellation Reason = Cancelled). Starting stamps the actual start, completing stamps the end time, and only the resource the plan is assigned to may start, pause or complete a visit. Tasks and activities are read live from the visit's task template and saved the first time the executive works them. The first order and the first service order raised against the visit are linked to it automatically. Open visits are cancelled when their plan is completed or lapses, or 48 hours after their planned date by default.

Fields

FieldLabelTypeRequiredWhat it does
AccountGroupIdAccount GroupLookup → AccountGroupAn account group reference on the visit. Not filled when a plan builds visits from an account group, and not read by visit execution.
AccountIdAccountLookup → AccountThe outlet being visited. Copied from the route stop, account group member or delivery order when the plan builds its visits. The Outlet Info tab, directions and the order captured on the visit all use this account.
AssignedLocationAssigned LocationGeoLocationThe planned map position of the outlet, stamped when the plan builds the visit from the route stop's coordinates or the account's stored location. Used for directions, the off-site warning, distances on the agenda and route optimisation. Hand-created visits have none.
BranchIdBranchLookup → BranchThe branch the visit belongs to. Only branches of the chosen Partner Account can be picked. Visits built by a visit plan leave it empty. Hidden on tenants that run a single location.
CreatedByIdCreated ByLookup → UserAccountYes
CreatedDateTimeCreated DateDateAndTimeYes
DeliveryOrderIdDelivery OrderLookup → DeliveryOrderThe delivery order this visit delivers, set when an Order Delivery plan builds one visit per pending delivery order.
DocumentDateDocumentDateDateAndTimeThe actual start as a date and time (UTC), stamped the first time the visit is started and kept when a paused visit resumes. Not on the delivered forms; reports use it as the visit's actual start.
EndTimeEnd TimeTimeOnlyThe actual end time, stamped on the tenant's clock when the visit is completed.
GeofencingToleranceGeofencing Tolerance (KM)NumberHow far from the outlet's planned position the executive may start the visit before the app warns that the start is off-site. Copied from the route stop. Despite the KM label, the web and mobile apps read the number in metres, and an empty or zero value means 100 metres. The warning never blocks the start.
IdIdGuidYes
InvoiceIdInvoiceLookup → InvoiceAn invoice reference on the visit. Not filled automatically; invoices raised on the visit appear on the mobile Related tab through their own visit reference.
LatitudeLatitudeDecimalNot stored any more. The visit's position is held in Visit Location and Assigned Location.
LongitudeLongitudeDecimalNot stored any more. The visit's position is held in Visit Location and Assigned Location.
ModifiedByIdModified ByLookup → UserAccountYes
MostlyFollowedSequenceMostly Followed SequenceNumberThe position learned from how earlier days on the route were actually walked. Empty when the route has no history.
NameNameTextThe visit's number. Visits are numbered by the delivered Visit document name setting (series V with a six-digit counter and the date). Visits built for a van run are named after the run, for example the run name followed by -V1, -V2.
NonProductiveReasonNon-Productive ReasonPickListWhy the visit produced no business, written when the executive ends the visit as Non-productive. The apps offer Store closed, Owner away and Other plus an optional note, joined with a dash. Also set to Carried to tomorrow by the mobile day-end Carry to tomorrow action. Stored as text; the delivered picklist has no values.
OptimizedSequenceOptimized SequenceNumberThe road-optimised position copied from the route's stored optimised order when the plan was built, and rewritten by Optimise Route on the plan.
OrderIdOrderLookup → OrderThe visit's own sales order: set automatically when the first order is created against the visit and never replaced. Later orders for the same visit stay linked through the order's own visit reference.
OwnerIdOwnerLookup → UserAccountYes
PartnerAccountIdPartner AccountLookup → AccountThe distributor or company the visit is made for. Only partner accounts that are active can be picked. Visits built by a visit plan leave it empty. Hidden on tenants that run a single company.
PaymentIdPaymentLookup → PaymentA payment reference on the visit. Not filled automatically.
PlannedDatePlanned DateDateThe day the visit is planned for. Plans copy their Plan Start Date onto route and delivery visits; visits built from an account group get no planned date, so the stale-visit cleanup never cancels them. Carry to tomorrow on mobile moves it to the next day.
PlannedDurationPlanned DurationCalculated (calculated)Calculated: minutes between Planned Start Time and Planned End Time, 0 until both are set. Read-only.
PlannedEndTimePlanned End TimeTimeOnlyThe planned departure time. Copied from the route stop's end time, or one hour after the scheduled delivery time.
PlannedSequencePlanned SequenceNumberThe position the route stop had on the beat when the plan was built. Reordering the mobile agenda and Optimise Route on the plan also rewrite it.
PlannedStartTimePlanned Start TimeTimeOnlyThe planned arrival time. Copied from the route stop's start time, or the delivery order's scheduled delivery time. Visit Time Deviation compares the actual start against it.
ProductDemoIdAppointmentLookup → ProductDemoAn appointment (product demo) reference on the visit. Not filled automatically.
RecordTypeIdRecord TypeGuid, hidden
RemarksRemarksMultiLineTextFree-text notes on the visit. On mobile the note button on a running visit writes here.
SequenceNumberSequence NumberNumberThe visit's current position in the plan's day: copied from the route stop and rewritten when the executive reorders the agenda or applies an optimised or mostly-followed order.
ServiceOrderIdService OrderLookup → ServiceOrderThe visit's own service order: set automatically when the first service order is created against the visit and never replaced.
ShowAcceptRejectOptionShow Accept/Reject OptionBooleanYesWhen ticked, a visit that has not started shows Reject and Accept & start instead of Start Visit, on the web and mobile. Reject ends the visit with status Completed and cancellation reason Rejected by rep. Not set by plan generation.
ShowGetDirectionOptionShow Get Direction OptionBooleanYesStored only. The directions button is always shown, whatever this is set to.
ShowProgressPanelShow Progress PanelBooleanStored only. No screen reads it.
ShowRescheduleOptionShow Reschedule OptionBooleanYesStored only. No screen reads it.
ShowVisitStartEndOptionShow Visit Start/End OptionBooleanYesStored only. No screen reads it; the start and end buttons are always shown.
StartTimeStart TimeTimeOnlyThe actual start time, stamped by the server on the tenant's clock (Org Settings default time zone) the first time the visit is started. Resuming a paused visit keeps the original start.
UIPropsUI PropsTextInternal display settings. Not used by visit execution.
UpdatedDateTimeModified DateDateAndTimeYes
VisitCancellationReasonVisit Cancellation ReasonPickListWhy the visit did not happen, written when the executive ends the visit as Cancelled (Store closed, Owner away, Other plus an optional note) or rejects it (Rejected by rep). The visit's status is still Completed. Choosing a value on the web form does not cancel the visit. Values: Insufficient Information, Non Availability.
VisitCityVisit CityPickListCity of the visit address, chosen from the Visit City picklist. The delivered list is short and is meant to be extended by an administrator. Values: Pune, Chandigarh, Mumbai.
VisitContactAddressIdVisit AddressLookup → ContactAddressThe customer address the visit is at. The list is not narrowed to the outlet's addresses, and choosing one does not fill the street, city, state or postal code fields.
VisitCountryVisit CountryPickListCountry of the visit address, chosen from the Visit Country picklist. Values: India.
VisitDateVisit DateDateA date field in the Actual section. Starting the visit does not fill it (the actual start is recorded in Start Time); only van-run visits get it, set to the delivery date.
VisitDurationVisit DurationCalculated (calculated)Calculated: minutes between Start Time and End Time, 0 until both are set. Read-only.
VisitLocationVisit LocationGeoLocationThe map position captured from the executive's device when the visit was started. Empty when location access was denied and the start was allowed without it.
VisitPlanIdVisit PlanLookup → VisitPlanThe visit plan (field day) this visit belongs to. Its assigned resource is the only person who can execute the visit, and the plan must be started before the visit can be started on the web or mobile app. Leave it empty for a standalone visit.
VisitPostalCodeVisit Postal CodeTextPostal code of the visit address.
VisitPurposeVisit PurposePickListWhy the outlet is visited: Order Capture, Courtesy Visit, Order Delivery, Field Service, Product Demo, Service Touch or Payment Collection. Copied from the route stop, or set to Order Delivery for delivery-order visits. Descriptive only; nothing in visit execution reads it. Values: Payment Collection, Order Capture, Order Delivery, Field Service, Product Demo, Courtesy Visit, Service Touch.
VisitRegionVisit RegionTextRegion of the visit address. Copied from the delivery order for delivery visits.
VisitRouteIdVisit RouteLookup → VisitRouteThe visit route (beat) the visit relates to. Not filled by plan generation, which links the visit to its route stop instead.
VisitRouteStopIdVisit Route StopLookup → VisitRouteStopThe route stop this visit was built from. Empty for visits built from an account group, a delivery order, a van run or by hand.
VisitStateVisit StatePickListState of the visit address, chosen from the Visit State picklist. The delivered list is short and is meant to be extended by an administrator. Values: Maharashtra, Punjab, New Delhi, Haryana.
VisitStatusVisit StatusPickListWhere the visit is in its life. Visits built for a plan start with no status (van-run visits start as Planned). Starting sets Started, pausing sets Paused, and ending sets Completed whatever the outcome. The day-end Carry to tomorrow action on mobile sets Rescheduled; plan completion, plan lapse and the stale-visit cleanup set Cancelled. Paused is written by the apps but is not in the delivered picklist. Only the resource the plan is assigned to can move a visit into Started, Paused or Completed. Values: Planned, Assigned, Started, Completed, Rescheduled, Cancelled.
VisitStreetVisit StreetTextStreet of the visit address, typed by hand or copied from the delivery order for delivery visits. Used for the directions link when the visit has no map position.
VisitTaskTemplateIdVisit Task TemplateLookup → VisitTaskTemplateThe checklist of tasks and activities to do at the outlet. Copied from the plan. The visit's task cards are read live from this template; changing it later removes the tasks already started under the old template and creates nothing in their place.
VisitTimeDeviationVisit Time DeviationCalculated (calculated)Calculated: Planned Start Time minus Start Time, in minutes. Positive means the visit started early, negative means late, 0 until both are set. Read-only.

Actions

ActionLabelTypeWhat it does
BulkDeleteDeleteDeleteDelete
CloneCloneServerAction (Clone)Create a copy of this record
ConvertLeadConvert Lead 2ServerAction (serverActionConvert)asdf
DeleteDeleteDeleteDelete
DeleteInListDeleteDeleteDelete
EditEditEditEdit
EditInLineEditEditInlineEdit
EditInListEditEditInlineEdit In List Header
EditPopupEditEditEdit
GetNearbyToOnboardGet Nearby To OnboardServerAction (GetNearbyToOnboard), hiddenRead-only feed for the mobile agenda: returns existing Accounts within a radius of the visit's location that are not yet on the plan or route, plus not-yet-onboarded ProspectPlace rows, both ranked by geodesic distance. Origin is the supplied currentLocation, else the visit's captured location, else its assigned location - with none of these it fails validation. Args radiusMeters (default 3000, max 100000) and maxResults (default 8, max 50). Creates nothing and calls no external provider.
NewNewNewNew

Lookup filters

FilterLookup fieldNotes
Branch For Partner AccountBranchId
Only Partner AccountPartnerAccountId