Partner onboarding applications

A Partner Onboarding record is the application a prospective partner makes to join your network: who the applicant is, the firm they trade through, their site and banking details, and where the application stands in your review. It sits between the enquiry and the trading relationship. A partner lead or opportunity usually comes first, and Activate Partner comes last: it turns the approved application into a partner account with its own branch, storage location and company set-up, so the new partner can start recording documents.

Overview

Each application is numbered automatically and starts at Draft. Your team fills it in over days or weeks, attaches the KYC documents your rules ask for, moves it into review, and records the outcome. One record type serves all four kinds of partner: Dealer, Distributor, Service Centre and Spare Parts. The Partner Type decides which requirements an application must meet before it can enter review.

The record page has a status timeline under the header, built from Onboarding Status, and five tabs:

A LOI / Agreement panel on the record page holds the letter of intent, the signed agreement and any other files you upload.

When to use it

Use a partner onboarding application whenever you appoint a new partner company that will own its own transactions in xMatix. If the firm is already a customer or supplier account, you can still use an application: activation adds the partner role to that account instead of creating a second one, provided activation can find it (see Business rules).

You do not need an application to add a branch to an existing partner, or to set up an existing partner account as a company. For those, see Branches and Accounts.

How xMatix handles it

• One status field drives the process. Onboarding Status is the stage. You move it yourself by editing the field on the record, or an approval process moves it for you. Only three steps have server logic behind them:
  • moving the record into Under Review, which checks the requirement set;
  • an approval decision, which sets Approved or Rejected;
  • Activate Partner, which creates the partner and sets Activated.
• Requirements are per partner type. An administrator lists what each partner type must provide: fields that must be filled, minimum facility sizes, and KYC documents. The list is checked when the application enters review. A partner type with no requirements has nothing checked.
• The letter of intent and the agreement are tracked by you. Record the dates in LOI Details, upload the documents to the LOI / Agreement panel, and log the steps as activities on the application. No action issues, extends or signs them.
• A legal hold is a flag, not a stage. While Legal Hold Reason has a value, Activate Partner is hidden and refused. The application keeps its status.
• Activation is the only step that creates records. It mints the partner code, creates or promotes the partner account and creates the branch and storage location. It also sets the account up as a company.

Prerequisites

• Access to the Partner Onboarding app. Its tabs are Leads, Opportunities and Partner Onboardings, then Reports, Dashboards, Analytics Dashboards and Settings.
• A security profile that can create and edit Partner Onboarding records and run its actions (see Permissions).
• For activation in an organisation that runs several companies: an understanding of how partner accounts become companies (see Accounts).
• Your administrator has set up the requirements for each partner type you appoint (see Configuration).

Procedure

Step 1 — Create the application

1. Open the Partner Onboarding app and select Partner Onboardings.
2. Select New. The form opens with an Applicant section and the Firm, Site, Banking and Commercials tabs.
3. Fill in what you know now. Nothing on this form is required, so a half-complete draft can be saved and finished later:
   • Applicant: Name Of Main Proprietor, Email, Mobile Number, Applicant Contact Number, PAN Number, Aadhar Number, Applicant Resence Address, Applicant Pincode.
   • Firm: Name Of The Firm, Firm PAN Number, GST Number, Firm Type, Date Of Establishment.
   • Site: City, State, Pin Code, Site Location Address, Workshop Pin Code.
   • Banking: Banker Name, A/C Number, Name In Bank Account.
   • Commercials: Security Deposit Amount, Credit Score (CIBIL).
4. Save. The application gets its number in the PO series, Onboarding Status is Draft and Partner Type is Dealer.

Partner Type is not on the standard forms. To appoint a distributor, service centre or spare-parts partner, your administrator must first add Partner Type to the create and record layouts. If KYC requirements are configured for the partner type, the matching KYC Documents rows are created as the application is saved.

Step 2 — Complete the details and the KYC documents

1. Open the application. Use the pencil next to a field to change it in place. The tabs hold many fields that the create form does not have, such as Firm Address, District, MSME Udyog Aadhar No, the site areas and the banker details.
2. Go to Approval Status and look at the KYC Documents list. For each document the applicant provides:
   • If a row for its type is already there, use the row's Upload Document action to attach the file. Otherwise select New, choose the Document Type and save.
   • When someone has checked the document against the original, edit the row and switch on Is Verified.
   • Every KYC document field is described in KYC documents.
3. Upload the letter of intent, the agreement and other files to the LOI / Agreement panel when you have them.

Step 3 — Send the application for review

1. When the application is complete, change Onboarding Status to Under Review (in the Dealer Self Assesment panel) and save.
2. xMatix checks the requirements configured for the application's partner type, and reports every gap in one message:
   • a required field that is empty: "Label is required before the application can enter review.";
   • a facility norm that is not met: "Label must be at least n before the application can enter review.";
   • a missing KYC document: "KYC checklist incomplete — missing: …";
   • a document that must be verified but is not: "KYC documents attached but not yet verified: …".
3. Fix what is reported and save again. Once the record is at Under Review, later edits are not re-checked.

If your organisation uses an approval process for partner applications, the process may move the status for you when it submits the record. The same check runs either way.

Step 4 — Record the review outcome

• With an approval process. When the final approver approves, Onboarding Status becomes Approved and Approved On is stamped. When they reject, it becomes Rejected. If no Onboarding Rejection Reason was recorded, the approver's comment is copied there, or Criteria Not Fulfilled when there is no comment. The outcome is applied only while the application is still at Submitted or Under Review.
• Without an approval process. Set Onboarding Status to Approved or Rejected yourself, and pick an Onboarding Rejection Reason when you reject.
• Sign-off fields. Approval By RSM, Channel Head Approval, Approval By Legal Team and Approval Status By Legal on the Approval Status tab record individual sign-offs. They are for your records and reports. Nothing reads them, and they do not change the status.

Step 5 — Track the letter of intent and the agreement

1. On Dealership Details → LOI Details, record LOI Issue Date, LOI Expiry Date, Signatory Name and Signatory Designation.
2. Upload the documents to the LOI / Agreement panel and log the steps as activities.
3. If you track these stages in the status, set Onboarding Status to LOI Issued and then Agreement Sent.

Do not use the Issue LOI, Extend LOI or Send Agreement for Signature buttons that appear at these stages. They confirm with "Action Executed" but change nothing. Also avoid the statuses Agreement Signed and LOI Lapsed: the list offers them, but saving either is refused (see Common problems).

Step 6 — Place or release a legal hold

• To place a hold, pick a Legal Hold Reason on the Approval Status tab and save: Frontage Of The Showroom, Improper Document, Layouts or Showroom & Workshop Photographs. Do not use the Place Legal Hold button; it fails with "A legal hold reason is required." because it cannot send the reason.
• To release it, select Release Legal Hold in the header, or clear the field. The button appears only while a reason is set.

A hold blocks Activate Partner. It does not stop the application from entering review unless your administrator has added a validation rule for that.

Step 7 — Activate the partner

1. Make sure there is no legal hold. If your organisation requires the security deposit first, make sure Security Deposit Received On is filled in (see Configuration).
2. Set Onboarding Status to Setup In Progress and save. The header shows Activate Partner only at this status.
3. Select Activate Partner and confirm in the Activate Dealer dialog.
4. xMatix creates the partner and sets Onboarding Status to Activated and Activated On to now. What it creates is listed under Business rules. If an email address is on the application and email is set up, the applicant receives a welcome email with the partner code.

After activation, find the new account under Settings → Partner Masters → Accounts by the firm's name. Review it, then give it its account groups, price lists and other settings.

Step 8 — Close an application that will not go ahead

• Applicant withdraws: set Onboarding Status to Withdrawn, write the reason in Remarks, and save. The Withdraw button in the header refuses with "A withdrawal reason is required — type it into Remarks, or pass Reason.", because it cannot send the reason with the click.
• You decline: set Rejected and an Onboarding Rejection Reason, or let the approval process reject it.

Rejected and withdrawn applications are kept for your records. To reconsider a firm, create a new application.

Fields

The tables follow the record page. Fields marked not on the standard forms exist on the record, and an administrator can add them to a layout.

Status and provenance

Applicant and firm

Site and premises

Commercials, LOI and banking

Approval

Business rules

• Numbering. The application number comes from the PO series. The partner code comes from a second numbering setting for Partner Code, which is switched off as shipped. While it is off, activation uses a code of the form DLR- followed by the date and time and four characters of the record id.
• Status values. A save is refused if Onboarding Status holds a value outside Draft, Submitted, Under Review, Approved, LOI Issued, Agreement Sent, Setup In Progress, Activated, Rejected, Withdrawn, Suspended or Terminated.
• Entering review. The requirement check runs on the save that moves the record into Under Review, including a new record created at that status. It does not run again while the record stays there.
• KYC checklist. When an application is created, one KYC Documents row is added for each KYC requirement of its partner type that has no row yet. Each row has the document type and is not verified, with no file attached.
• Approval outcome. A final approval sets Approved and Approved On. A final rejection sets Rejected and fills an empty rejection reason. Recalls and reverts do not change the status. An outcome that arrives after the status has moved on, for example after you set Withdrawn, is ignored.
• Activation guard. Activate Partner runs only when all of these hold:
  • the application has no account yet;
  • the status is Approved, LOI Issued, Agreement Sent or Setup In Progress (the header shows the button only at Setup In Progress);
  • there is no legal hold;
  • when the deposit setting is on, Security Deposit Received On has a value.
• Which account activation uses. If the application's opportunity has an account, that account is promoted. This is the usual case after a partner lead is converted, because conversion creates the firm's account as an inactive partner account. Otherwise a new account is created from Name Of The Firm. Activation never takes the account from the lead.
• What activation writes.
  • Account: the account is marked as a partner account and made active, and its other roles are kept. Account code, GSTIN, PAN, MSME number, email, phone and billing city, state and postal code are filled only where the account has none. Billing street is joined from Flat / Door / Building, Road / Street and Area / Locality / Sector, which are not on the standard forms.
  • Contact: a primary contact is created unless the account already has one.
  • Branch: a branch named code-HO, labelled firm — Head Office, of type Sales Branch, active and allowing purchase, sales, inventory and service. An account that already has a branch keeps it, and it is made active with all four permissions switched on.
  • Storage location: a location named code-MAIN, labelled Main, in that branch, unless the branch already has one.
  • Company set-up: the account is set up as a company. Its default branch is the head-office branch, its document name prefix is the first 10 characters of the partner code, and finance is not enabled.
  • Address: a default Both address from the site details, country India, when the application has a city or street and the account has no default address yet.
• Welcome email. It is sent after the activation is saved, so a failed activation sends nothing. A delivery failure does not undo the activation.

Example

A two-wheeler brand appoints a new dealer in Pune.

1. A sales executive creates an application. Name Of Main Proprietor is the applicant, Name Of The Firm is Kestrel Two Wheels, City is Pune, State is Maharashtra and Security Deposit Amount is 500000. It is saved with a PO number, at Draft, as a Dealer.
2. The Dealer requirements are two Field rows: GST Number and Firm PAN Number must be filled. The executive enters both, uploads the PAN card and GST certificate to the KYC Documents list, and switches on Is Verified for each.
3. They set Under Review. The organisation's approval process routes the application to the regional manager, who approves it, and the status becomes Approved.
4. The LOI is issued and signed. The dates go into LOI Details and the files into LOI / Agreement.
5. The deposit arrives. The executive sets Setup In Progress and selects Activate Partner. The status becomes Activated, and Partner Code is a DLR- code. A partner account Kestrel Two Wheels now exists with a head-office branch and a Main storage location.

Training

Practice exercise

In a sandbox, create a Dealer application with a firm name, city, state and email. Add a Field requirement for Dealer that demands GST Number. Set the application to Under Review without a GST number and note the message. Fill in the GST number and save again. Then set Approved, then Setup In Progress, and select Activate Partner.

Expected result: the first save is refused with "GST Number is required before the application can enter review." (or your requirement's label). After activation the status is Activated, Partner Code and Account are filled, and the account has a head-office branch and a Main storage location.

Quick reference

• Status moves by editing Onboarding Status; only review entry, approval outcome and activation have logic.
• Requirements are checked once, when the application enters Under Review.
• KYC documents count only when their Document Type matches the requirement; verification counts only when Is Verified is on.
• A Legal Hold Reason blocks activation; Release Legal Hold clears it.
• Activate Partner shows at Setup In Progress with no hold.
• Withdraw by setting Withdrawn and writing the reason in Remarks.
• Avoid Agreement Signed and LOI Lapsed, and the Issue LOI, Extend LOI and Send Agreement buttons.
• Activation promotes the opportunity's account if there is one; otherwise it creates one.

Permissions

New, Edit and Delete follow the security profile's access to the Partner Onboarding entity. The standard SystemAdmin, SalesManager, StandardUser and SalesExecutive profiles have full access. The record's actions also need a grant on the profile's Actions tab:

A user without the grant cannot run the action. Changing Onboarding Status or Legal Hold Reason in place needs only edit access, so restrict those fields with field permissions if only certain roles may move an application forward. See Security profiles.

Configuration

• Partner type requirements. Partner Onboarding → Settings → Onboarding Rules → Partner Type Requirements. Each row has:
  • Partner Type: the type it applies to;
  • Requirement Kind: Field, Facility Norm or KYC Document;
  • Requirement: for a field or facility norm, the field's internal name, such as GSTNumber or TotalShowroomAreaSqFt;
  • Document Type: for a KYC document, the type it needs; when blank, Requirement is used;
  • Minimum Value: for a facility norm, the number the field must reach;
  • Require Verified: the document must be marked Is Verified;
  • Active: switch it off to retire a requirement without deleting it.

  Changes apply to the next application that enters review. KYC rows are created only for applications created after the requirement exists. See the caution in Common problems about requirement kinds.

  • Deposit before activation. Setup → Feature Hub → Sales → Settings, group Partner Onboarding: Require security deposit before activation, off by default. When on, activation is refused until Security Deposit Received On is filled. That field is not on the standard forms, so add it to the record layout before switching this on.
  • Approval process. None is shipped. To route applications for sign-off, create a process on Partner Onboarding that submits when Onboarding Status becomes Under Review, for example with auto-submit on update and that condition. The outcome is written back automatically, so you do not need final field updates. The standard record page has no approval panel, so add one if users should submit by hand. See Approval processes.
  • Validation rules. No format checks are shipped for PAN, GSTIN, Aadhaar or pincodes, and no rule stops a held application from entering review. Add them as validation rules if you need them. See Business rules.
  • Numbering. The PO series for applications and the Partner Code series (off as shipped) are document numbering settings. See Document numbering.
  • Welcome email. Create an email template named partner.onboarding.activated to control the wording. Without it, a short default message is sent.
  • Layouts. Add Partner Type, Security Deposit Received On and the address parts to the record or create layout if your process uses them. See Design a form layout.
  • Masters. The same Settings page lists Accounts, Branches, Contacts and Contact Addresses under Partner Masters, and Storage Locations under Logistics, so you can finish a new partner's set-up without leaving the app.

  Common problems

  "Invalid OnboardingStatus 'Agreement Signed'."

  The status list offers Agreement Signed and LOI Lapsed, but the server does not accept them. Choose Agreement Sent or Setup In Progress instead. To record that the LOI lapsed, keep the status and note it in Remarks, or reject or withdraw the application.

  Withdraw says "A withdrawal reason is required"

  The Withdraw button cannot send a reason. Set Onboarding Status to Withdrawn, type the reason in Remarks, and save.

  Place Legal Hold says "A legal hold reason is required."

  Pick the Legal Hold Reason on the Approval Status tab and save instead. The hold takes effect as soon as the field has a value.

  Issue LOI or Send Agreement for Signature does nothing

  These buttons have no server action behind them. They report "Action Executed" without changing anything. Track the LOI and agreement as described in Step 5.

  I cannot see Activate Partner

  The header shows it only when Onboarding Status is Setup In Progress and Legal Hold Reason is empty, and only to users whose profile has the grant. Clear the hold, set the status and reload the record.

  "The security deposit must be received before activation …"

  The deposit setting is on and Security Deposit Received On is empty. Ask your administrator to add the field to the layout, fill it in, and try again.

  "A partner account has already been created for this application."

  The application has already been activated: its Account is set. Open that account. Activation never runs twice on one application.

  A KYC Document or Facility Norm requirement is not checked

  When you pick KYC Document or Facility Norm from the list, the requirement is saved under an internal value that the review check does not recognise. Such a requirement is ignored, and its KYC rows are not created on new applications. Field requirements are not affected. Test each requirement in a sandbox by moving an application that does not meet it to Under Review. If the save goes through, the requirement is not enforced; contact support, and meanwhile check that requirement by hand before you approve.

  "Partner Application" on a partner opportunity does nothing

  This button appears on partner opportunities in the mobile app. The standard opportunity screens do not run the server step that raises an application from a won opportunity, so the button only reports "Action Executed". Create the application with New and fill in the Opportunity field so that activation promotes the opportunity's account.

  Common questions

  Does activation create a customer account?

  No. Activation marks the account as a partner account and makes it active, and it leaves the account's other roles as they were. A newly created account has no customer or supplier role. If the new partner will also buy from you, switch on the customer role on the account, then give it its price lists, account groups and credit limit as you would for any customer.

  What happens to the account if an application is rejected?

  When converting a partner lead creates a new account, that account is created as an inactive partner account, and documents naming an inactive partner are refused. If the application is then rejected or withdrawn, that account stays inactive and unused. You can reuse it for a later application from the same opportunity, or deactivate it for good in your records.

  Can one partner type ask for different documents from another?

  Yes. Requirements are kept per partner type, so a service centre can be asked for a workshop size and a dealer for a showroom frontage, each with its own KYC list. A partner type with no requirements is not checked at all, so set up every type you appoint before applications start arriving.

  Does placing a legal hold stop the review?

  Not by itself. The hold blocks activation only. The application keeps its status, can still be approved, and can still enter review. If you want a hold to stop the move into Under Review, ask your administrator to add a validation rule that refuses that status while Legal Hold Reason has a value.

  Related topics

  • Leads and Opportunities: the partner funnel before the application
  • Accounts: partner accounts and setting them up as companies
  • Branches and Storage locations
  • Contact addresses
  • Approval processes
  • Partner Onboarding field reference