Main GuideAPI Reference

Import File Workflow

BMG Money provides two distinct technical pathways to import payroll data into our system. Depending on your data volume and technical infrastructure, you can choose between a Secure File Handshake or a Direct JSON Import.

1. High-Volume: Secure File Handshake

This method is recommended for large CSV files. It utilizes pre-signed URLs to allow your system to upload files directly to our secure storage, bypassing the overhead of standard API request limits and improving reliability for large datasets.

The Handshake Sequence

  1. Request Upload Permission: Call the POST /submissions endpoint with a list of file metadata.
  2. Receive Pre-signed URL: The API validates the request and returns a uploadUrl. This URL is uniquely signed for your specific file and expires in 15 minutes.
  3. Perform Binary Upload: Execute an HTTP PUT request directly to the uploadUrl.
    • Method: PUT
    • Body: Raw binary content of your .csv file.
    • Required Header: Content-Type: text/csv

Important: Since you are uploading directly to Google Cloud Storage in Step 3, do not include your BMG bearer token (Authorization) in the PUT request. The signature is already embedded in the URL.

2. Low-Volume: Direct JSON Import

This method is recommended for smaller datasets or real-time synchronizations. Instead of generating a physical file and handling a two-step upload, you send the records directly to our endpoints as a JSON array.

Technical Implementation

We provide dedicated routes for different payroll categories. While the technical flow is identical, the request body layout differs for each:

  • Census Data: POST /api/v1/census
  • Receipt Data: POST /api/v1/receipt

Technical Requirements

  • Method: POST
  • Payload: A JSON collection of records formatted according to the specific layout of the chosen category.

Technical Specifications Comparison

Feature File Handshake (Submissions) Direct JSON Import
Data Format Binary .csv File JSON Object Array
Payload Capacity Up to 100MB Up to 5MB
HTTP Sequence POST (Metadata) then PUT (File) Single POST (Data)
Security Pre-signed Signature Bearer Token
Layouts CSV Column Template JSON Schema

Choosing the Right Path

Use File Handshake if:

  • You are exporting data from a legacy system or database as a flat file.
  • Your data contains more than 1,000 records.
  • You want to ensure file integrity via Checksum verification.

Use Direct JSON if:

  • You are integrating via a modern backend or middleware.
  • You are sending small, frequent batches of data.
  • You prefer to avoid managing local file storage or temporary files.

Common Response Codes

Regardless of the path chosen, the API will return one of the following status codes. All error responses follow our standard DataResponse format.

Status Code Definition Description / Troubleshooting
200 OK Success The request was successful (commonly used for GET requests and some update operations).
201 Created Accepted The request is valid and has been queued for processing.
400 Bad Request Validation Error One or more fields failed validation (e.g., missing mandatory fields, invalid date format).
401 Unauthorized Auth Failure Missing or invalid authentication credentials (check your Authorization).
403 Forbidden Access Denied Credentials are valid, but you do not have permission to access the specified X-Context-Key.
422 Unprocessable Entity Business Rule Error The request is well-formed, but business rules prevent processing (e.g., a duplicate file checksum).
500 Internal Error Server Error An unexpected error occurred on our side. Please contact support with the trace ID.