Dealer Import

Overview

Use this endpoint to push a new dealer (merchant) into Safeturf. The system deduplicates, transforms, and enriches the data automatically, then triggers the underwriting verification workflow. All fields are optional — send what you have. The more data provided, the smoother the verification process.

Authentication

Every request must include a Bearer token in the Authorization header:

Authorization: Bearer <your_api_token>

Contact your Safeturf integration contact to obtain your API token.

Query Parameters

force_update

boolean

default:"false"

Re-import the merchant even if a record already exists for this merchantId. Use this to update an existing dealer.

skip_verification

boolean

default:"false"

Skip the underwriting verification flow after import. Useful for bulk loads where you want to trigger verification later.

source

string

default:"API"

Source identifier for tracking. Set this to "PLMT" so Safeturf can attribute and filter records by partner.

Request Body

merchantId

integer

default:"98001"

Your internal numeric ID for this dealer. Used for deduplication — if a record with this ID already exists, the import is skipped unless force_update=true.

merchantEmail

string

default:"owner@example.com"

Primary contact email for the dealer account.

merchantPhoneNumber

string

default:"407-555-0100"

Primary phone number for the dealer.

websiteUrl

string

default:"https://example.com"

Dealer’s website URL.

merchantStatus

string

default:"active"

The dealer’s current status in your system. Stored as-is in Safeturf for reference. Defaults to "ACTIVE" if not provided.

businessInfo

object

Business information. Send as a nested JSON object — not as dot-notation keys.

Show businessInfo fields

legalName

string

default:"Acme Solar LLC"

Business name. Use the full legal registered name if you have it, or the trading name if not.

dba

string

default:"Acme Solar"

Doing-business-as name (if different from legal name).

ein

string

default:"12-3456789"

Employer Identification Number (EIN), formatted as XX-XXXXXXX.

entityType

string

default:"llc"

Legal entity type. One of: llc, corp, c-corp, s-corp, sole_prop, partnership.

stateIncorp

string

default:"FL"

Two-letter US state code where the business is incorporated (e.g. "FL").

annualSalesRevenue

number

default:"1500000"

Estimated annual sales revenue.

businessPhone

string

default:"407-555-0101"

Business phone number.

businessAddress

object

Registered business address.

Show businessAddress fields

street

string

default:"123 Main St"

Street address.

city

string

default:"Orlando"

City.

state

string

default:"FL"

Two-letter state code.

zip

string

default:"32000"

ZIP code.

principalInfo

object

Principal owner information. Send as a nested JSON object — not as dot-notation keys.

Show principalInfo fields

firstName

string

default:"Alex"

Principal owner’s first name.

lastName

string

default:"Johnson"

Principal owner’s last name.

string

default:"owner@example.com"

Principal owner’s email address.

cellPhone

string

default:"407-555-0102"

Principal owner’s cell phone number.

ssn

string

default:"000-00-0000"

Principal owner’s Social Security Number (used for identity verification).

dob

string

default:"1980-01-01"

Date of birth in YYYY-MM-DD format (e.g. "1980-01-15").

principalAddress

object

Principal owner’s home address.

Show principalAddress fields

street

string

default:"456 Oak Ave"

Street address.

city

string

default:"Kissimmee"

City.

state

string

default:"FL"

Two-letter state code.

zip

string

default:"34000"

ZIP code.

locationInfo

array

Array of physical store locations for this dealer.

Show locationInfo item fields

storeName

string

default:"Acme Solar Orlando"

Name of the store location.

streetAddress

string

default:"123 Main St"

Street address of the location.

city

string

default:"Orlando"

City.

state

string

default:"FL"

Two-letter state code.

zipCode

string

default:"32000"

ZIP code.

phoneNumber

string

default:"407-555-0101"

Phone number for this location.

contactEmail

string

default:"location@example.com"

Contact email for this location.

isPrimary

boolean

default:"true"

Set to true for the primary/main location. Exactly one location should be marked primary.

status

string

default:"approved"

Location status. One of: approved, pending, rejected, review.

bankAccounts

array

Array of bank accounts associated with this dealer.

Show bankAccounts item fields

accountNumber

string

default:"000000001"

Bank account number.

aba

string

default:"000000000"

ABA routing number (9 digits).

bankName

string

default:"Example Bank"

Name of the bank (e.g. "Chase").

type

string

default:"business"

Account type: "business" or "personal".

owner

string

default:"business"

Account owner: "business" or "principal".

legalBusinessName

string

default:"Acme Solar LLC"

Legal name on the account.

licenseInfo

array

Array of contractor or business licenses held by this dealer.

Show licenseInfo item fields

license

string

default:"CGC1523456"

License number.

expirationsDate

string

default:"2026-08-31 00:00:00"

Expiration date in YYYY-MM-DD HH:MM:SS format (e.g. "2026-08-31 00:00:00").

states

string[]

default:"[\"FL\"]"

List of US state codes where this license is valid (e.g. ["FL", "GA"]).

Example Request

curl -X POST "https://api.safeturf.com/api/ftpos/import-generic?source=PALMETTO" \
  -H "Authorization: Bearer <your_api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 98001,
    "merchantEmail": "owner@example.com",
    "merchantPhoneNumber": "407-555-0100",
    "websiteUrl": "https://example.com",
    "businessInfo": {
      "legalName": "Acme Solar LLC",
      "dba": "Acme Solar",
      "ein": "12-3456789",
      "entityType": "llc",
      "stateIncorp": "FL",
      "annualSalesRevenue": 1500000,
      "businessPhone": "407-555-0101",
      "businessAddress": {
        "street": "123 Main St",
        "city": "Orlando",
        "state": "FL",
        "zip": "32000"
      }
    },
    "principalInfo": {
      "firstName": "Alex",
      "lastName": "Johnson",
      "email": "owner@example.com",
      "cellPhone": "407-555-0102",
      "ssn": "000-00-0000",
      "dob": "1980-01-01",
      "principalAddress": {
        "street": "456 Oak Ave",
        "city": "Kissimmee",
        "state": "FL",
        "zip": "34000"
      }
    },
    "locationInfo": [
      {
        "storeName": "Acme Solar Orlando",
        "streetAddress": "123 Main St",
        "city": "Orlando",
        "state": "FL",
        "zipCode": "32000",
        "phoneNumber": "407-555-0101",
        "contactEmail": "location@example.com",
        "isPrimary": true,
        "status": "approved"
      }
    ],
    "bankAccounts": [
      {
        "accountNumber": "000000001",
        "aba": "000000000",
        "bankName": "Example Bank",
        "type": "business",
        "owner": "business",
        "legalBusinessName": "Acme Solar LLC"
      }
    ],
    "licenseInfo": [
      {
        "license": "LIC-0000001",
        "expirationsDate": "2026-08-31 00:00:00",
        "states": ["FL"]
      }
    ]
  }'

Response

{
  "flow_run_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "flow_run_name": "chunky-panther",
  "status": "running",
  "merchant_id": 98001,
  "message": "Generic import started for merchant 98001",
  "prefect_ui": "http://localhost:4200/flow-runs/flow-run/3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

flow_run_id

string

UUID of the background flow run processing this import. Use this to track status.

flow_run_name

string

Human-readable name assigned to the flow run by Prefect.

status

string

Always "running" on a successful submission — the import is processed asynchronously.

merchant_id

integer

Echo of the merchantId from your request.

message

string

Confirmation message.

Notes

Authentication is required. Include your Bearer token on every request.
Set ?source=<YOUR_PARTNER_CODE> as a query parameter for full attribution tracking in Safeturf reporting.
The import is asynchronous — a 200 response means the record was accepted and queued, not that it has finished processing.
If a dealer with the same merchantId already exists, the import will be skipped. To update an existing record, add ?force_update=true to the URL.
After a successful import, poll GET /api/ftpos/business/{merchant_id} to retrieve the business_uuid once the record is ready (returns 404 while processing, 200 when complete). Then use the Check UW Status endpoint to monitor the dealer’s verification progress.

Getting Started

API Reference

Overview

Authentication

Query Parameters

Request Body

Example Request

Response

Notes

Getting Started

API Reference

​Overview

​Authentication

​Query Parameters

​Request Body

​Example Request

​Response

​Notes

Overview

Authentication

Query Parameters

Request Body

Example Request

Response

Notes