Who this article is for: Authority Users
Overview
This article explains how to format the CSV file you upload for Billing Sync, based on the SwiftComply Backflow (SCBF) upload template. It covers how to prepare the file, the required and optional fields for each record type, valid values, default values, and how blank values are handled.
How to prepare your file
Column A (the descriptive labels) is for instructional purposes only; please delete it from the actual upload file.
Row 1 (the Record types) is for instructional purposes only; please delete it from the actual upload file.
Row 2 lists the SwiftComply Backflow (SCBF) field names; all mandatory fields are indicated with an * or ** where relevant. These fields must be included with the uploaded file and cannot be blank. Please delete the * and ** from the actual upload file, but do not make any other changes to any of the field names provided.
The notes listed in the contact_email and equipment_serial_number cells should also be deleted.
Optional fields should be deleted if they are not being used.
If any of the optional boolean fields are included, they must not be left blank.
Custom fields can be added; confirm correct field names with SwiftComply.
Examples in rows 3–6 are for instructional purposes and should not be included in your actual upload file.
Required-field key:
* indicates the minimum required fields.
** indicates required fields if syncing that type of record.
Row and relationship rules
Each row must contain only 1 Location-Contact relation and/or 1 Location-Backflow Assembly relation.
If a Location has more than 1 Contact or Backflow Assembly, each unique Contact or Backflow Assembly will need to be represented on their own row with the completed Location details.
If a Contact has more than 1 address, the relevant Location-Contact data must be duplicated and the additional contact addresses listed on a new row.
Default values
All fields can be set to use a default value. Default values are only used when creating a new record, not to overwrite data for an existing record.
Default values are only used if the field (column) is not included in the CSV file. If the field is included, it must have the desired value on each line.
If a required value is left empty, it will not be synced. If a non-required value is left empty, it will sync that empty value to the record in SwiftComply.
Ask SwiftComply for details.
How blank values are handled
For each field, the tables below describe what a blank value does in three situations: (1) to an existing record that already has a value in this field, (2) when attempting to create a new record, and (3) to an existing record that already has a blank in this field.
Location Record Fields
Field | Required | Type | Definition | Default value | How blank values are handled |
property_id | * Required | text | The billing system's location identifier. This must be unique for each location record. | N/A | Existing (has value), new record, and already blank: Returns error — [field(s): property_id, message: Missing or invalid value(s); skipping this property.] |
property_name | * Required | text | The name of the location that corresponds to the billing account listed in the property_id field. | N/A | Existing (has value) and new record: Returns error — [field(s): property_name, message: Missing or invalid value(s); skipping this property.] Already blank: N/A — cannot create a record with this field blank. |
property_address1 | * Required | text | The first line of the address that corresponds to the billing account listed in the property_id field. | N/A | Existing (has value) and new record: Returns error — [field(s): property_address1, message: Missing or invalid value(s); skipping this property.] Already blank: N/A — cannot create a record with this field blank. |
property_address2 | Optional | text | The second line (if applicable) of the address that corresponds to the billing account listed in the property_id field. | N/A | Existing (has value): overwrites this field with a blank. New record and already blank: field will be blank. |
property_city | * Required | text | The city that corresponds to the billing account listed in the property_id field. | N/A | Existing (has value) and new record: Returns error — [field(s): property_city, message: Missing or invalid value(s); skipping this property.] Already blank: N/A — cannot create a record with this field blank. |
property_state_prov | * Required | text | The two letter state/province code that corresponds to the billing account listed in the property_id field. | N/A | Existing (has value): Returns error — [field(s): property_state_prov, message: Missing or invalid value(s); skipping this property.] New record and already blank: N/A — cannot create a record with this field blank. |
property_postal_code | * Required | text | The postal code that corresponds to the billing account listed in the property_id field. | N/A | Existing (has value) and new record: Returns error — [field(s): property_postal_code, message: Missing or invalid value(s); skipping this property.] Already blank: N/A — cannot create a record with this field blank. |
property_country_code | * Required | text | The two letter country code that corresponds to the billing account listed in the property_id field. | If left blank the system will default to the Organization's country code. | Existing (has value) and new record: Returns error — [field(s): property_country_code, message: Missing or invalid value(s); skipping this property.] (In order to use the default setting you would need to delete this column from the upload file.) Already blank: N/A — cannot create a record with this field blank. |
property_phone | Optional | text | The phone number that corresponds to the billing account listed in the property_id field. | N/A | Existing (has value): overwrites this field with a blank. New record and already blank: field will be left blank. |
property_contact_is_primary | Required (boolean — cannot be left blank) | boolean (True/False) | This field value should be true if the contact data on this line of the file should be the primary location contact. | FALSE | Existing (has value), new record, and already blank: Returns error — [field(s): property_contact_is_primary, message: Missing or invalid value(s); skipping this contact's primary designation.] |
property_is_active | Required (boolean — cannot be left blank) | boolean (True/False) | This would normally be assumed to be true unless you were importing historical data for some reason. | TRUE | Existing (has value), new record, and already blank: Returns error — [field(s): property_is_active, message: Missing or invalid value(s); skipping this property.] |
property_notes | Optional | text | Notes from the Organization's billing system that corresponds to the billing account listed in the property_id field. CAUTION: using this field would overwrite any notes that already exist in the database for this record. | N/A | Existing (has value): overwrites this field with a blank. New record and already blank: field will be left blank. |
Contact Record Fields
Field | Required | Type | Definition | Default value | How blank values are handled |
contact_id | ** Required if you are syncing contact records | text | The billing system's contact identifier. This must be unique for each contact record. | N/A | — |
contact_email | ** Required | text | The logic below only applies if no contact_id is provided. The email address for a contact that corresponds to the billing account listed in the property_id field. NOTE: changes to the contact record would be reflected for this contact across ALL locations they are linked to. NOTE: If this field is left blank and SCBF has email addresses that do not exist in the billing system, those addresses would be replaced by the blank value. Each contact should have a unique email; we understand this is not always available and will use alternate methods when available (e.g. contact name) to reduce the number of possible false positives returned from a name comparison. We cannot support using the same email address for multiple contacts with different names. | N/A | Existing (has value): overwrites this field with a blank. |
contact_first_name | ** Required | text | The first name/business name that corresponds to the contact account listed in the contact_email field. NOTE: changes to the contact record would be reflected for this contact across ALL locations they are linked to. | N/A | Existing (has value): Returns error — [field(s): contact_first_name,message: Missing or invalid value(s); skipping this contact.] (Will still get this error even if there is already a record and the email addresses are filled in/match.) |
contact_last_name | Optional | text | The last name that corresponds to the contact account listed in the contact_email field. NOTE: changes to the contact record would be reflected for this contact across ALL locations they are linked to. | N/A | Existing (has value): overwrites this field with a blank. |
contact_phone | Optional | text | The phone number that corresponds to the contact account listed in the contact_email field. NOTE: changes to the contact record would be reflected for this contact across ALL locations they are linked to. | N/A | Existing (has value): overwrites this field with a blank. |
contact_notes | Optional | text | Notes from the Organization's billing system that corresponds to the contact account listed in the contact_email field. NOTE: changes to the contact record would be reflected for this contact across ALL locations they are linked to. CAUTION: using this field would overwrite any notes that already exist in the database for this record. | N/A | Existing (has value): overwrites this field with a blank. |
contact_active | Required (boolean — cannot be left blank) | boolean (True/False) | This would normally be assumed to be true unless you were importing historical data for some reason. | TRUE | Existing (has value) and new record: Returns error — [field(s): contact_active, message: Missing or invalid value(s); skipping this contact.] Already blank: N/A — cannot create a record with this field blank. |
property_contact_types | Optional | text | This is a comma separated list from the following: owner, property manager, onsite, mailing, maintenance. Include only the roles that apply to this specific contact/location combination. This field is NOT updated for this contact across all locations the contact is linked to. | N/A | Existing (has value): unchecks all options. New record and already blank: no roles will be selected. |
Contact Address Record Fields
NOTE: These fields can only be updated if the Contact Record Fields are included.
Field | Required | Type | Definition | Default value | How blank values are handled |
contact_address1 | ** Required | text | The first line of the address that corresponds to the billing account listed in the property_id field. | N/A | Existing (has value): Returns error — [field(s): contact_address1, message: Missing or invalid value(s); skipping this contact address.] New record: Returns error — [field(s): contact_address_city, message: Missing or invalid value(s); skipping this contact address.] Already blank: N/A — cannot create a record with this field blank. |
contact_address2 | Optional | text | The second line (if applicable) of the address that corresponds to the contact account listed in the contact_email field. NOTE: changes to the contact record would be reflected for this contact across ALL locations they are linked to. | N/A | Existing (has value): overwrites this field with a blank. New record and already blank: field will be left blank. |
contact_address_city | ** Required | text | The city that corresponds to the billing account listed in the property_id field. | N/A | Existing (has value) and new record: Returns error — [field(s): contact_address_city, message: Missing or invalid value(s); skipping this contact address.] Already blank: N/A — cannot create a record with this field blank. |
contact_address_state_prov | ** Required | text | The two letter state/province code that corresponds to the contact account listed in the contact_email field. NOTE: changes to the contact record would be reflected for this contact across ALL locations they are linked to. | N/A | Existing (has value): Returns error — [field(s): contact_address_state_prov, message: Missing or invalid value(s); skipping this property.] New record: If left blank system will default to the Organization's state code. Already blank: N/A — cannot create a record with this field blank. |
contact_address_postal_code | ** Required | text | The postal code that corresponds to the billing account listed in the property_id field. | N/A | Existing (has value) and new record: Returns error — [field(s): contact_address_postal_code, message: Missing or invalid value(s); skipping this contact address.] Already blank: N/A — cannot create a record with this field blank. |
contact_address_country_code | ** Required | text | The two letter country code. If left blank the system will default to the Organization's country code. | If left blank the system will default to the Organization's country code. | Existing (has value): Returns error — [field(s): contact_address_country_code, message: Missing or invalid value(s); skipping this property.] New record: Returns error — [field(s): contact_address_country_code, message: Missing or invalid value(s); skipping this contact address.] (In order to use the default setting you would need to delete this column from the upload file.) Already blank: N/A — cannot create a record with this field blank. |
contact_address_is_primary | Required (boolean — cannot be left blank) | boolean (True/False) | If a contact has more than 1 address (not Location) associated with them, a True value indicates which of the addresses the system should use when a communication is sent to this contact. | FALSE | Existing (has value) and new record: Returns error — [field(s): contact_address_is_primary, message: Missing or invalid value(s); skipping this contact address.] Already blank: N/A — cannot create a record with this field blank. |
contact_address_is_active | Required (boolean — cannot be left blank) | boolean (True/False) | This would normally be assumed to be true unless you were importing historical data for some reason. | TRUE | Existing (has value) and new record: Returns error — [field(s): contact_address_is_active, message: Missing or invalid value(s); skipping this contact address.] Already blank: N/A — cannot create a record with this field blank. |
Backflow Assembly Record Fields
Field | Required | Type | Definition | Default value | How blank values are handled |
equipment_serial_number | ** Required only if syncing equipment records | text | The assembly's serial number. The combination of an assembly's serial number, make, and model should be unique across all assemblies. | N/A | Existing (has value): Returns error — [field(s): equipment_serial_number, message: Missing or invalid value(s); skipping this equipment.] New record: same error, plus [message: Skipping this equipment detail because it requires a valid record to exist.] Already blank: N/A — cannot create a record with this field blank. |
equipment_id | ** Required | text | The billing system's unique identifier for an assembly record that corresponds to the billing account listed in the property_id field. For accuracy, the value in this field should be unique across all assemblies. | N/A | Existing (has value): overwrites this field with a blank. New record and already blank: field will be left blank. |
equipment_type | ** Required | text | The assembly type that corresponds to the assembly listed in the equipment_serial_number field. Valid equipment types are: AirGap, AVB, BB, CV, DC, DCDA, DCDA-II, DuC, HC, PVB, RP, RPDA, RPDA-II, SVB, Unknown. | N/A | Existing (has value): Returns error — [field(s): equipment_type, message: Missing or invalid value(s); skipping this equipment.] New record: same error, plus [message: Skipping this equipment detail because it requires a valid record to exist.] Already blank: N/A — cannot create a record with this field blank. |
equipment_make | ** Required | text | The assembly make (manufacturer) that corresponds to the assembly listed in the equipment_serial_number field. | N/A | Existing (has value): [field(s): equipment_make, message: Missing or invalid value(s); skipping this equipment.] New record: Returns error — [message: Skipping this equipment detail because it requires a valid record to exist.] Already blank: N/A — cannot create a record with this field blank. |
equipment_model | ** Required | text | The assembly model that corresponds to the assembly listed in the equipment_serial_number field. | N/A | Existing (has value): [field(s): equipment_model, message: Missing or invalid value(s); skipping this equipment.] New record: Returns error — [message: Skipping this equipment detail because it requires a valid record to exist.] Already blank: N/A — cannot create a record with this field blank. |
equipment_size | ** Required | text | The assembly size that corresponds to the assembly listed in the equipment_serial_number field. Valid inputs are: .25, .375, .5, .75, 1, 1.25, 1.5, 1.75, 2, 2.5, 3, 4, 6, 8, 10, 12. | N/A | Existing (has value): Returns error — [field(s): equipment_size, message: Missing or invalid value(s); skipping this equipment.] New record: same error, plus [message: Skipping this equipment detail because it requires a valid record to exist.] Already blank: N/A — cannot create a record with this field blank. |
equipment_notes | Optional | text | The notes that corresponds to the assembly listed in the equipment_serial_number field. CAUTION: using this field would overwrite any notes that already exist in the database for this record. | N/A | Existing (has value): overwrites this field with a blank. New record and already blank: field will be left blank. |
equipment_active | Required (boolean — cannot be left blank) | boolean (True/False) | This would normally be assumed to be true unless you were importing historical data for some reason. | TRUE | Existing (has value): Returns error — [field(s): equipment_active, message: Missing or invalid value(s); skipping this equipment.] New record: same error, plus [message: Skipping this equipment detail because it requires a valid record to exist.] Already blank: N/A — cannot create a record with this field blank. |
Custom Property
Field | Type | Definition | Default value | How blank values are handled |
Custom Property (format needs to match record type, e.g. property/contact/etc._addl:field_name) | Matches the field on that record's Details form | Import additional data based on custom properties set up in your system; confirm correct backend field names with SwiftComply. | Default values have to be custom set based on the type of column being used. | If left blank in the import file this field will be left blank. If the Custom Property being updated has a defined set of acceptable values (e.g. True/False, Yes/No, dropdown list) any non-blank inputs would need to align with these acceptable values. If an invalid input is used, an error would be returned. |
Examples
The examples below are for instructional purposes and should not be included in your actual upload file.
Example 1 — Location Only
property_id: 123
property_name: Neighborhood Restaurant
property_address1: 100 Main Street
property_city: Denver
property_state_prov: TN
property_postal_code: 80202
property_country_code: US
property_phone: 720.555.5555
property_contact_is_primary: FALSE
property_is_active: TRUE
property_notes: Anything in this cell would replace what currently exists in this location's SCBF record
Example 2 — Location-Contact
property_id: 123
property_name: Neighborhood Restaurant
property_address1: 100 Main Street
property_city: Denver
property_state_prov: CO
property_postal_code: 80202
property_country_code: US
property_phone: 720.555.5555
property_contact_is_primary: FALSE
property_is_active: TRUE
property_notes: Anything in this cell would replace what currently exists in this location's SCBF record
contact_id: 1111
contact_email: Bobbi@example.com
contact_first_name: Bobbi
contact_phone: 720.555.5678
contact_notes: Anything in this cell would replace what currently exists in this contact's SCBF record
contact_active: TRUE
property_contact_types: owner, mailing
contact_address1: 6701 Koll Center Pkwy
contact_address2: Ste 250
contact_address_city: Pleasanton
contact_address_state_prov: CA
contact_address_postal_code: 94566
contact_address_country_code: US
contact_address_is_primary: TRUE
contact_address_is_active: TRUE
Example 3 — Location-Equipment
property_id: 123
property_name: Neighborhood Restaurant
property_address1: 100 Main Street
property_city: Denver
property_state_prov: CO
property_postal_code: 80202
property_country_code: US
property_phone: 720.555.5555
property_contact_is_primary: FALSE
property_is_active: TRUE
property_notes: Anything in this cell would replace what currently exists in this location's SCBF record
equipment_serial_number: 989876
equipment_id: A123456
equipment_type: RP
equipment_make: Ames
equipment_model: 4000B-FP
equipment_size: 0.75
equipment_notes: Anything in this cell would replace what currently exists in this contact's SCBF record
equipment_active: TRUE
Example 4 — Location-Contact-Equipment
property_id: 123
property_name: Neighborhood Restaurant
property_address1: 100 Main Street
property_city: Denver
property_state_prov: CO
property_postal_code: 80202
property_country_code: US
property_phone: 720.555.5555
property_contact_is_primary: FALSE
property_is_active: TRUE
property_notes: Anything in this cell would replace what currently exists in this location's SCBF record
contact_email: Lauren@example.com
contact_first_name: Lauren
contact_phone: 703.555.3456
contact_active: TRUE
property_contact_types: onsite
contact_address1: 100 Main Street
contact_address_city: Denver
contact_address_state_prov: CO
contact_address_postal_code: 80202
contact_address_country_code: US
contact_address_is_primary: TRUE
contact_address_is_active: TRUE
equipment_serial_number: 56B7834
equipment_id: A123789
equipment_type: DC
equipment_make: Watts
equipment_model: U007SSQT
equipment_size: 2
equipment_notes: Anything in this cell would replace what currently exists in this contact's SCBF record
equipment_active: TRUE
Other notes
Leaving blank data in your CSV file — refer to the blank-value details in the field tables above for more information about how blank values will be handled in each of the CSV columns.
Splitting City, State, Postal Code — if your billing export cannot separate out City, State, Postal Code, see these instructions for how to complete this in Excel.
State/province codes — the two letter state/province code; not sure what the correct code is? See USPS for US state/territory codes or Statistics Canada for Canada provinces.
Country codes — the two letter country code; not sure what the correct country code is? See this country code list.
Text field limitations — SwiftComply prides itself on providing the greatest flexibility possible to support the various customers' business processes. To that extent we try to limit creating additional rules as much as possible. In support of this ideal, we do not currently have published limits but we reserve the right to impose reasonable limits on any field if necessary in the future.
The CSV billing sync will only edit/create records. It will never delete old records.
NOTE: This list of fields is subject to change and will be confirmed before your billing sync is finalized.