Registering a Company in SynchPay

Follow these steps to register a company in SynchPay

To register a company (such as a gym) in the SynchPay API, you must create a company entity using the /company/create endpoint. This is the first step in enabling company-related operations within SynchPay. The process involves submitting a registration object, waiting for verification, and then completing additional setup steps. Here’s how it works:

1. Obtain an Access Token

   Before calling /company/create, obtain an access token by making a POST request to /auth/token with your ClientId and ClientSecret. Refer to the Authorization section for details.

2. Create a Registration Object

   Use the access token to submit the company details via the /company/create endpoint.

3. Wait for KYB Process

   After submission, SynchPay performs a Know-Your-Business (KYB) verification, which takes approximately 24 hours.

4. Check Company Status

   Use the GET /company/status endpoint to monitor the registration status.

5. Complete Setup

   Once approved, SynchPay sends an email with links to connect a bank account via Plaid and access the Backend Portal for managing your account.

Registering a Company

The /company/create endpoint allows you to define a company entity by submitting a JSON object containing the company’s details. Below are the specifics of the API call.

Endpoint

• URL: https://api.synchpay.com/company/create
• Method: POST
• Authorization: Bearer <AccessToken>Note: The access token is obtained from /auth/token using your ClientId and ClientSecret.

Request Body

The request body is a JSON object with the following top-level fields:

Parameter	Type	Description	Required
CompanyReferenceId	string	Your unique external reference ID for this company.	Yes
Name	string	The company’s name.	Yes
EmailAddress	string	The company’s contact email address. Must be a valid email.	Yes
ContactNumber	string	The company’s contact phone number. Must be a valid phone number.	Yes
TaxId	string	The company’s unique tax ID.	Yes
TaxIdType	string	The type of tax ID (EIN, TIN, or SSN).	Yes
CompanyType	string	One of: SoleProprietorship, NonProfit, ForProfit, Corporation, LLC, or Partnership.	Yes
Owner	object	The owner’s details. See Owner object for structure.	Yes
Employees	array	An array of employee objects. See Employees array for structure.	No
StreetNumberAndName	string	The street number and name.	Yes
ApartmentNumber	string	The apartment or suite number. Must contain only printable ASCII characters if provided.	No
City	string	The city.	Yes
State	string	Two-letter US state abbreviation (e.g. CA, NY).	Yes
ZipCode	string	Five-digit US ZIP code (e.g. 90001 or 90-001).	Yes
WebsiteUrl	string	The company’s website URL. Validated if provided.	No

Owner Object

The Owner object is a required field that contains the following properties:

Field	Type	Description	Required
Name	string	The owner’s full name.	Yes
EmailAddress	string	The owner’s email address. Must be a valid email.	Yes
ContactNumber	string	The owner’s phone number. Must be a valid phone number.	Yes
Title	string	The owner’s title.	Yes
DocumentNumber	string	The owner’s ID number.	No
DocumentType	string	The type of ID (DriversLicense or Passport).	No
Ssn	string	Last 4 digits of the owner’s SSN. Must be exactly 4 digits.	Yes
DateOfBirth	string	Owner’s date of birth in YYYY-MM-DD format.	Yes
StreetNumberAndName	string	The street number and name.	Yes
ApartmentNumber	string	The apartment or suite number.	No
City	string	The city.	Yes
State	string	Two-letter US state abbreviation (e.g. CA, NY).	Yes
ZipCode	string	Five-digit US ZIP code (e.g. 90001 or 90-001).	Yes

Employees Array

The Employees field is an optional array of employee objects. Unlike the Owner object, employee objects do not include document-related fields. Each employee object in the array contains the following properties:

Field	Type	Description	Required
Name	string	The employee’s full name.	Yes
EmailAddress	string	The employee’s email address.	Yes
ContactNumber	string	The employee’s phone number.	Yes
Title	string	The employee’s title.	Yes

Note: The Employees array is optional. If included, each employee object must contain all the specified fields (Name, EmailAddress, ContactNumber, and Title). If there are no employees to register at the time of company creation, you can either omit the Employees field or set it to an empty array ([]).

Validation rules

The API validates all fields before creating the company. If validation fails, you receive a 400 Bad Request response with details about which fields are invalid. Key rules to be aware of:

• Email uniqueness — The owner’s email address cannot match any employee’s email address. All employee email addresses must be unique.
• Phone numbers — ContactNumber fields must be valid phone numbers.
• Address fields — State must be a two-letter uppercase abbreviation. ZipCode must be a five-digit code (with optional hyphen, e.g. 90001 or 90-001).
• Owner SSN — Must be exactly four digits.
• Company type — Must exactly match one of the accepted values (case-insensitive).

Example Request

{
  "CompanyReferenceId": "loc-001",
  "Name": "Example Company",
  "EmailAddress": "[e-mail]",
  "ContactNumber": "[phone]",
  "TaxId": "12-3456789",
  "TaxIdType": "EIN",
  "CompanyType": "LLC",
  "WebsiteUrl": "https://examplegym.com",
  "Owner": {
    "Name": "John Doe",
    "EmailAddress": "[e-mail]",
    "ContactNumber": "[phone]",
    "Title": "Owner",
    "DocumentNumber": "D1234567",
    "DocumentType": "DriversLicense",
    "Ssn": "1234",
    "DateOfBirth": "1950-05-05",
    "StreetNumberAndName": "123 Fitness St",
    "ApartmentNumber": "Suite 100",
    "City": "Fitville",
    "State": "CA",
    "ZipCode": "90001"
  },
  "Employees": [
    {
      "Name": "Jane Smith",
      "EmailAddress": "[e-mail]",
      "ContactNumber": "[phone]",
      "Title": "Manager"
    },
    {
      "Name": "Mike Johnson",
      "EmailAddress": "[e-mail]",
      "ContactNumber": "[phone]",
      "Title": "Manager"
    }
  ],
  "StreetNumberAndName": "123 Fitness St",
  "ApartmentNumber": "Suite 100",
  "City": "Fitville",
  "State": "CA",
  "ZipCode": "90001"
}

Response

Upon successful submission, the endpoint returns a JSON object, likely containing a company identifier or a success message. The exact response format is not specified in the current documentation, so consult the API reference for details. An example might look like:

{
  "CompanyId": "0ba2d920-7588-407f-8553-afc4f073c9b8"
}

Waiting for KYB Process

After submitting the registration object, SynchPay initiates the Know-Your-Business (KYB) process to verify the provided information. This process typically takes up to 24 hours. During this period, the company status remains “Unverified”.

Checking Company Status

To monitor the registration status, use the GET /company/{companyId}/status endpoint:

• URL: https://api.synchpay.com/company/{companyId}/status
• Method: GET
• Authorization: Bearer <AccessToken>

The response will indicate the current status (e.g., “Unverified”, “Verified”, or “Rejected”).

Note: For sandbox environment this will always return “Verified”

Completing Setup

Once the KYB process is complete and the company is verified, SynchPay sends an email to the EmailAddress provided in the registration. The email includes:

• Bank Account Connection: A link to connect your bank account via Plaid.
• Backend Portal Access: A link to the Backend Portal, where you can manage your account, add new account numbers, close accounts, and handle edge cases.

Follow the instructions in the email to finalize your company setup.

---