KYC Customer & Entity Import/Export

This document covers bulk importing and exporting KYC Customer (individual) and KYC Entity (business) records via CSV. Both record types use the same shared import/export infrastructure.

Overview

KYC Customer inherits from Person and KYC Entity inherits from Entity. The import/export system works with any blueprint kind as the CSV format mirrors the blueprint's field definitions.

Available states for KYC Customer:

initial
pre-cleared
cleared
advanced
expired
rejected
auto-rejected

Available states for KYC Entity:

initial
verification
cleared
monitored
rejected

Importing KYC Customers

Via the UI

Navigate to the KYC Customer index and click + Bulk Upload
Click Download Template to get an empty CSV with correct headers
Fill in your records and save the CSV
Drag the CSV onto the dropzone or click to browse
Click Import

Via the API

POST /api_imports Content-Type: application/json { "key": "KYC Customer",
    "filename": "customers.csv", "content_type": "text/csv", "file_base64":
    "base64-encoded-csv-data" }

The key parameter determines which blueprint to import against. Use "KYC Customer" for individuals or "KYC Entity" for businesses.

KYC Customer CSV Header Reference

The KYC Customer blueprint inherits all fields from Person and replaces ID Doc (Generic ID Document) with KYC ID Document (adds Issuing State/Province). Gender is a select (Male, Female, Unknown) instead of free text.

Header	Type	Notes
`Key`	meta	Auto-generated if blank
`State`	meta	initial, pre-cleared, cleared, etc.
`Due At`	meta	Expiration date
`First Name`	text	Required
`Middle Name`	text
`Last Name`	text	Required
`Suffix`	text	e.g. Sr., Jr.
`Other Names`	text
`Gender`	select	Male / Female / Unknown
`Nationality`	select	ISO 3166-1 alpha-2
`Country of Residence`	select	ISO 3166-1 alpha-2
`Birthdate`	calendar
`Place of Birth`	text
`Occupation`	text
`Occupation Code`	text
`Employer Name`	text
`TIN`	text	Tax identification number
`TIN Type`	select	EIN / SSN-ITIN / Foreign
`Phone`	text
`Phone Ext`	text
`Username`	text
`Email`	text

Address Substep

Header	Type	Notes
`Address Address`	text (multiple)	First line; `Address Address 2` for second line
`Address City`	text
`Address State`	text
`Address Zip`	text
`Address Country Code`	select	ISO 3166-1 alpha-2
`Address Type`	text	e.g. Home, Work

ID Document Substep (Multiple)

The KYC ID Document substep allows multiple documents per customer. The first uses base header names; the second appends 2, the third 3, and so on. By default, most reports will simply submit the newest ID Document record.

Header	Type	Second Instance
`ID Doc Type`	text	`ID Doc 2 Type`
`ID Doc Issuing Country`	select	`ID Doc 2 Issuing Country`
`ID Doc Issuing State/Province`	text	`ID Doc 2 Issuing State/Province`
`ID Doc Number`	text	`ID Doc 2 Number`
`ID Doc Expiry Date`	calendar	`ID Doc 2 Expiry Date`

Example CSV Row

Key,State,Due At,First Name,Middle Name,Last Name,Nationality,Country of
    Residence,Suffix,Other Names,Gender,Birthdate,Occupation,Occupation
    Code,TIN,TIN Type,Phone,Phone Ext,Username,Email,Address Address,Address
    Address 2,Address City,Address State,Address Zip,Address Country
    Code,Address Type,ID Doc Type,ID Doc Issuing Country,ID Doc Number,ID Doc
    Expiry Date,ID Doc 2 Type,ID Doc 2 Issuing Country,ID Doc 2 Number,ID Doc 2
    Expiry Date
    doe-john-11b3a,cleared,2027-03-15,John,Doe,Smith,US,US,Jr.,Johnny,Male,1984-12-21,Software Engineer,123456,789123456,SSN-ITIN,555-1234,1,johnsmith,john.smith@example.com,123 Main St,Apt 4B,New York,NY,10001,US,Home,passport,US,X12345678,2025-04-21,drivers_license,US,Y98765432,2027-03-15

Importing KYC Entities

Navigate to Upload Entities or use the API with "key": "KYC Entity". The KYC Entity blueprint inherits from Entity.

KYC Entity CSV Header Reference

Header	Type	Notes
`Key`	meta
`State`	meta
`Name`	text	Required
`DBA Name`	text
`Nature of Principal Business`	text
`Phone`	text
`Phone Ext`	text
`Email`	text
`URL`	text
`TIN`	text
`TIN Type`	select	BN / GST-HST / Foreign
`Address Address`	text (multiple)
`Address Address 2`	text
`Address City`	text
`Address State`	text
`Address Zip`	text
`Address Country Code`	select
`Address Type`	text

Multiple ID documents (ID Doc Type, ID Doc 2 Type, etc.) and authorized persons (Authorized Persons First Name, Authorized Persons 2 First Name, etc.) are supported the same way as KYC Customer.

Nested & Multiple Fields

Address is a single substep — columns are prefixed with Address
ID Doc is a multiple substep — first uses ID Doc *, second ID Doc 2 *, up to 50
Multiple text fields like Address Address accept numbered suffixes (Address Address 2)

Key References

Instead of providing full field data for a substep, you can reference an existing record by its Key. For example, Address Key in a CSV cell tells the importer to look up that step and link it. If the key is not found, the substep data will be blank (no error is raised).

Exporting

Go to the KYC Customer (or KYC Entity) index view
Apply any search filters (state, date range, keyword query, etc.)
Click the Export button

The export:

Applies the current search/filter criteria
Generates a CSV with the same headers the import expects
Strips empty columns — only populated columns appear
Supports up to 10 instances of multiple-value fields
Exports linked For Key and Secondary Key relations

Template Generation

Click Download Template from the Bulk Upload page to get an empty CSV with all possible headers. The template includes:

Every field defined on the blueprint
Second-instance headers for multiple substeps (e.g. ID Doc 2 *)
A $ref header for key-based references on substeps

Bulk Delete

Go to Top Menu → Imports → Import Row
Find the import record (shows the record kind and timestamp)
Click Delete Imported Records

This deletes every step created with that import's import_id, allowing you to cleanly retry failed or incorrect imports.

Date Formats

The importer accepts these date formats:

2023-10-25
2023-10-25 00:00:00 UTC
Wed, 25 Oct 2023 00:00:00 +0000
2021-07-03T23:21:48.007Z
2007-04-05T12:30-06:00
8/27/2024 (US-centric, m/d/Y)
8/9/24 (US-centric, m/d/y)
08/27/2024 00:00
08/27/24 00:00

When in doubt, create a record via the UI, export it, and copy the format used.

Important Notes

No guaranteed row order — rows may not process in file order
Batch large imports — split very large uploads into multiple files
Best practice: Create a single record in the UI, export it to see the format, then model your bulk import on that export