Batch API Overview

The Batch API allows you to upload held account data records in properly formatted and encrypted CSV files via SFTP. MX can provide a response file for each batch file submitted.

File Format

Batch files for creating users, members, accounts, and transactions must adhere to the following standardized format:

• Encoding: UTF-8.
• Format: CSV.
• Quoting: Use field quoting when necessary.
• Header Row: Required to specify the fields you're providing. For which fields are required/optional for each file, see File Contents.
• Customization: Line ending, separator, and quote characters are customizable.

Initial SFTP Setup

To set up access to MX's integration and production SFTP servers:

1. Provide source and destination IP addresses (and domain name, if applicable) for whitelisting.
2. MX will securely provide usernames and passwords for both integration and production environments, and port numbers.
3. (Optional) MX will provide public PGP keys for integration and production environments. All batch files must be encrypted with the environment-specific MX public PGP key.
4. (Optional) If you require response files, provide MX with:
   • SFTP URL and login information for your test and production servers.
   • Destination IP addresses for your SFTP server.
   • (Optional) Your public PGP key. If needed, you can provide separate keys for test and production servers.

Sending Files via SFTP

To send batch files to MX's SFTP server:

1. Prepare each file, ensuring proper formatting, file-naming requirements, and optional encryption with the environment-specific MX public PGP key.
2. Log into the MX SFTP server.
3. Navigate to the upload directory (default: files folder).
4. Upload files using SFTP commands.
5. If requested, MX will upload encrypted response files (using your provided PGP key, if applicable) to your SFTP server.

SFTP Hostname and Port

The MX SFTP hostnames for each MX environment are as follows:

• MX Integration Environment: int-sftp.mx.com
• MX Production Environment: sftp.mx.com

MX uses a non-standard port, which will be provided with your credentials.

Identifiers

Users, members, accounts, and transactions use identifiers provided by your system. This enables retrieval via other MX APIs using your system's identifiers.

We recommend identifiers consist of letters, numbers, dashes, and underscores, and are less than 1,024 bytes. Common choices include 128-bit UUIDs or 64-bit sequential integers.

Date and Times

Batch API resources often include _at and _on fields. Provide dates using either format, but not both:

• _at: Unix datetime.
• _on: ISO 8601 dates (for example, YYYY-MM-DD). Zero pad the month and day.

File Naming and Size

Batch files must follow the naming convention: PREFIX.TYPE.DATE.SUFFIX.csv.pgp. The .pgp extension is required only for PGP encrypted files. All sections are mandatory for file recognition.

Examples:

• Bank.User.2016-12-31.Split001.csv.pgp
• BackfillProject.Member.2017-01-20.Split002.csv.pgp
• Credit.Account.2017-02-01.FixPreviousLoad01.csv.pgp
• MyBank.Transaction.2017-02-01.Complete.csv.pgp

Example of a batch file group:

_10

PreloadGroup.User.2017-10-31.batch001.csv.pgp

_10

PreloadGroup.Member.2017-10-31.batch001.csv.pgp

_10

PreloadGroup.Account.2017-10-31.batch001.csv.pgp

_10

PreloadGroup.Transaction.2017-10-31.batch001.csv.pgp

Prefix

The PREFIX groups files into a batch, ensuring sequential processing according to the MX Architecture heirarchy (for example, users → members → accounts → transactions).

If files have different prefixes, MX may attempt to process a transactions file in parallel with the file containing the users, members, and accounts that are the parent objects of those transactions, resulting in errors for the transactions.

For example, a transactions file called Bank.Transaction.20170202.Split001.csv.pgp will wait for the user, member, and account files prefixed with Bank to complete before it starts processing.

In contrast, independent data sets should be given separate PREFIX values to make sure they can process in parallel. A file called Backfill.Transaction.20170202.Split001.csv.pgp won't wait for the Bank prefixed files to complete before it starts processing.

Type

The TYPE indicates the object type and must be one of: User, Member, Account, Transaction. Use the singular form only.

Date

The DATE must be an ISO 8601 date with a four-digit year and zero-padded months and day (YYYY-MM-DD or YYYYMMDD) reflecting the date the files are uploaded to MX. It must be consistent for all files within a group.

Suffix

The SUFFIX differentiates unique file groups. For example, if multiple batch files are being uploaded on the same day, the SUFFIX can be incremented with each new upload: batch001, batch002, and so on.

File Size

• Recommended: 1 million records or fewer for optimal performance.
• Maximum: 3 million records. Larger datasets must be split.

Upload Order

Objects must be created following the MX Architecture hierarchy. Group batch files appropriately and upload them together to avoid errors. For example, transactions can't be created before the user has been created.

Manifest files (required for new integrations) ensure all batch files are received and processed in the correct order.

If you're not using manifest files, ensure files are processed in the correct order. All files in an upload grouping must share the same PREFIX, DATE, and SUFFIX.

Upload files in the following order within each grouping:

1. User files
2. Member files
3. Account files
4. Transaction files

This ensures hierarchical objects are created in the correct sequence within a batch group.

Manifest Files

Manifest files are required for all new integrations. They specify all files in a batch, guaranteeing correct processing and data integrity. Manifests list filenames and optional checksums for each file in the batch.

Send the manifest file first. MX will begin processing only when all listed files are received.

Manifest File Naming

Manifests follow the same naming pattern: PREFIX.TYPE.DATE.SUFFIX.csv.pgp. Use the same PREFIX and DATE as the batch files, set TYPE to Manifest, and omit the SUFFIX.

Example: Bank.Manifest.2016-12-31.csv.pgp

Manifest File Contents

Manifests must be in CSV format and encrypted. Two columns are supported:

Field	Description	Required?
filename	The name of the files included in the batch.	Yes
checksum	The SHA256 checksum of the unencrypted file.	No

An example of manifest file contents follows.

_10

filename, checksum

_10

Bank.User.2020-04-13.Split1112.csv.pgp,389438d0f857041757a754e696375dc2b8089f2423ccbe5e3ff2a0e60ac1544f

_10

Bank.Member.2020-04-13.Split1112.csv.pgp,89fbc47675603079be7f9feca7625d8ac38802ac3e2c492edeed04a327db8015

_10

Bank.Acct.2020-04-13.Split1112.csv.pgp,5474f58d52395952268b10342b45dff780a0039636aba3a21a0b0ad5775d062d

_10

Bank.Tran.2020-04-13.Split1112.csv.pgp,b423960ce42eadd02ab36f3ba9313d5ac2d533ba3a4d2266d15a2df43d46e0c1

Number Limits

Decimal numbers are defined by precision,scale. Precision is the total number of digits; scale is the number of digits after the decimal. For example, 538.46 has a precision,scale of 5,2.