# Create Vendor

The first thing you should do when integration the vendor onboarding process is implement the Create vendor call below. Vendors can be created with or without pre-populating additional onboarding fields.

Pre populating onboarding fields makes the onboarding process easier for your vendors. Send some of the onboarding fields while creating the vendor (using same API call).  
In most cases, some of the information we require for the vendor onboarding is already collected by your platform.

## Create vendor without pre-populating any onboarding fields

Make a [`POST /vendors`](https://docs.unipaas.com/reference/vendorcontroller_createvendor) request to create a new vendor, provide the information you have and the rest will be collected later on in the onboarding process:

```curl
curl --location --request POST 'https://sandbox.unipaas.com/platform/vendors' \
--header 'accept: application/json' \
--header 'Authorization: Bearer <PLATFORM_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "businessName": "Better Delivery",
    "type": "company",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "country": "GB",
    "reference" : "Qiuysdxv5shs", // The unique user id on your system
    "createOnboardingLink": true
    }'
```

In the response, you'll get the created vendor object, as shown in the example below

```json
{
  "id": "61829cf9db1fb65b94f1acf8",
  "businessName": "Better Delivery",
  "email": "john.doe@example.com",
  "createdAt": "2021-11-03T14:30:17.120Z",
  "updatedAt": "2021-11-03T14:30:17.120Z",
  "merchantId": "616d3e7faba71b9e13a2f7b7",
  "acceptPayments": false,
  "receivePayouts": false,
  "onboardingLink": "https://sandbox-hosted.unipaas.com/vendors/6162aff7d7eb80d6982c18bf/I45f0ooz7CkuOsPJ7s4v"
}
```

## Create vendor and pre-populate onboarding fields

Make a [`POST /vendors`](https://docs.unipaas.com/reference#vendorcontroller_createvendor) request to create a new vendor, provide the information you have, and the rest will be collected later on in the onboarding process:

```curl
curl --location --request POST 'https://sandbox.unipaas.com/platform/vendors' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <PLATFORM_SECRET_KEY>' \
--data-raw '{
    "businessName": "Better Delivery",
    "type": "company",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "country": "GB",
    "url": "http://example.com",
    "serviceDescription": "service description",
    "birthDate": "1980-01-01",
    "phone": "+447911123456",
    "category": "CHILD_CARE_SERVICES",
    "createOnboardingLink": true
}'
```

> 📘 Onboarding type
>
> The onboarding type defines if your vendor is an individual / sole trader (`individual`) or a registered company (`company`) or an association (`non-profit`) .

In the response, you'll get the created vendor object.

```json
{
  "id": "61829cf9db1fb65b94f1acf8",
  "businessName": "Better Delivery",
  "email": "john.doe@example.com",
  "createdAt": "2021-11-03T14:30:17.120Z",
  "updatedAt": "2021-11-03T14:30:17.120Z",
  "merchantId": "616d3e7faba71b9e13a2f7b7",
  "acceptPayments": false,
  "receivePayouts": false,
  "onboardingLink": "https://sandbox-hosted.unipaas.com/vendors/6162aff7d7eb80d6982c18bf/I45f0ooz7CkuOsPJ7s4v"
}
```

Note that the create vendor response includes an onboarding link that you can send your vendor. This will allow your vendor to complete all remaining onboarding fields in a UNIPaaS hosted UI.

## Pre populated onboarding fields

The following fields describe the onboarding data that can be, and should to be, pre filled upon vendor creation using a [POST /vendors/\{vendorId}/onboarding](https://docs.unipaas.com/reference/onboardingcontroller_postonboardingflatforms) API call after a vendor has been created.  
Please mind that we strongly recommend you provide as much data as possible. It will save your vendor time and effort, and will increase conversion rates for the payment onboarding process.

> 📘 Read Only fields
>
> Some fields are 'read only': the vendor won't be able to see/edit them.

## Onboarding fields

<table>
  <thead>
    <tr>
      <th>
        Field Name
      </th>

      <th>
        Is Required
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>

      <th>
        Read Only
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `businessName`
      </td>

      <td>
        Optional
      </td>

      <td>
        String
      </td>

      <td>
        Represents the name of the business (if applicable) for both individuals and companies.

        This field will also define how your business is identified in your customer's credit card statements.
      </td>

      <td>
        Yes
      </td>
    </tr>

    <tr>
      <td>
        `firstName`
      </td>

      <td>
        Required
      </td>

      <td>
        String
      </td>

      <td>
        For **Individual onboarding**  this field represents the individual's first name.

        For **Company onboarding**  
        This field represents the company representative first name
      </td>

      <td>
        No
      </td>
    </tr>

    <tr>
      <td>
        `lastName`
      </td>

      <td>
        Required
      </td>

      <td>
        String
      </td>

      <td>
        For **Individual onboarding**  this field represents the individual's last name.

        For **Company onboarding**  
        This field represents the company representative last name
      </td>

      <td>
        No
      </td>
    </tr>

    <tr>
      <td>
        `birthDate`
      </td>

      <td>
        Recommended
      </td>

      <td>
        String
      </td>

      <td>
        For **Individual onboarding**  this field represents the individual's date of birth.

        For **Company onboarding**  
        This field represents the company representative date of birth
      </td>

      <td>
        Yes
      </td>
    </tr>

    <tr>
      <td>
        `phone`
      </td>

      <td>
        Recommended
      </td>

      <td>
        String
      </td>

      <td>
        For **Individual onboarding**  this field represents the individual's phone number

        For **Company onboarding**  
        This field represents the company representative phone number
      </td>

      <td>
        Yes
      </td>
    </tr>

    <tr>
      <td>
        `email`
      </td>

      <td>
        Required
      </td>

      <td>
        String
      </td>

      <td>
        For **Individual onboarding**  this field represents the individual's email address

        For **Company onboarding**  
        This field represents the company email address
      </td>

      <td>
        Yes
      </td>
    </tr>

    <tr>
      <td>
        `country`
      </td>

      <td>
        Required
      </td>

      <td>
        String  
        ISO 3166-1 alpha-2 code
      </td>

      <td>
        For **Individual onboarding**  this field represents the individual's country

        For **Company onboarding**  
        This field represents the company corporate country
      </td>

      <td>
        Yes
      </td>
    </tr>

    <tr>
      <td>
        `type`
      </td>

      <td>
        Recommended  
        (for UI)

        Required  
        (for API)
      </td>

      <td>
        Enum
      </td>

      <td>
        The three available types are:  
        Company  
        Individual  
        Non-profit  
        Each will present a different onboarding flow to your vendors
      </td>

      <td>
        Yes
      </td>
    </tr>

    <tr>
      <td>
        `subType`
      </td>

      <td>
        Required  
        (for type non-profit)
      </td>

      <td>
        Enum
      </td>

      <td>
        The three available types are:  
        Associations  
        Schools  
        Charities
      </td>

      <td>
        Yes
      </td>
    </tr>

    <tr>
      <td>
        `url`
      </td>

      <td>
        Recommended
      </td>

      <td>
        String
      </td>

      <td>
        **Individual onboarding**  
        Profile URL (website, blog, social network profile)

        **Company onboarding**  
        Official Website URL
      </td>

      <td>
        No
      </td>
    </tr>

    <tr>
      <td>
        `serviceDescription`
      </td>

      <td>
        Recommended
      </td>

      <td>
        String
      </td>

      <td>
        **Individual onboarding**  
        Description of the provided service
      </td>

      <td>
        Yes
      </td>
    </tr>

    <tr>
      <td>
        `category`
      </td>

      <td>
        Recommended
      </td>

      <td>
        Enum
      </td>

      <td>
        **Individual and Company onboarding**

        **MCC Enum**

        List of all  
        [MCC codes](https://docs.unipaas.com/docs/mcc-codes)
      </td>

      <td>
        Yes
      </td>
    </tr>

    <tr>
      <td>
        `createOnboardingLink`
      </td>

      <td>
        Recommended
      </td>

      <td>
        boolean
      </td>

      <td>
        **Individual and Company onboarding**

        True - you will receive an onboarding link in the API response

        False - you will NOT receive an onboarding link in the API response
      </td>

      <td>
        Yes
      </td>
    </tr>
  </tbody>
</table>

> 🚧 Vendor invitation flows
>
> In case your vendor creation flows include an invitation flow (e.g an vendor is being invited by an accountant) you should implement **[the referer flow](https://docs.unipaas.com/docs/creating-vendors-by-referral)** before moving forward to the next step.