Bulk Account Lock Process
The Bulk Account Lock Process is essentially a batch version of calling /account/lock repeatedly. To issue several requests to lock accounts, please use this process. Throttling mechanisms exist in the Helix API to ensure timely responses. See Batch Processing Overview for more information.
Basic Workflow
- You upload a Bulk Account Lock Request File
- Helix processes it then uploads a Bulk Account Lock Response File containing the results
Detailed Workflow
- You upload a properly formatted Bulk Account Lock Request File to
sftp.corepro.io
- Open a support ticket to request the file to be processed.
- Within four days of receiving the request, Helix calls the /account/lock functionality for each content row in the file, but in a vastly more efficient manner
- Helix writes the results to a Bulk Account Lock Response File and uploads it to
sftp.corepro.io
- You inspect this response file for success and failed counts, and process accordingly. NOTE: Only failed account lock operations will appear in the content section of the response file
Bulk Account Lock Request File Definition
The Bulk Account Lock Request File is a file created by the client to perform the equivalent of several requests to the /account/lock endpoint. Multiple files per day can be processed, typically on an hourly basis. It has the following properties:
- Fixed-length
- ANSI endocded
- Line endings are Windows-style CarriageReturn + LineFeed (
\r\n
, or0x0D0A
) - File must be uploaded to the relative directory of
/BulkAccountLock
- File name follows a specific, case-insensitive pattern of:
yyyyMMddhhmm_BULKACCOUNTLOCK.txt
- The date in the file name should be the creation date of the file.
- For example, if the file name is
201501080015_BULKACCOUNTLOCK.TXT
, the data it contains will apply to Jan 8, 2015. - The header record contains an
EffectiveDate
field. This should be the same value as theCreatedDate
field.
Format Disclaimer
Helix reserves the right to append new field(s) to the end of any Header or Content line without notice. This is to allow new data points to be added as needed in a timely fashion.Implementation Note
Your code should be written such that unexpected characters after the "last" field but prior to the end of each line should be ignored. That is, if the file is documented as being 872 bytes per line, receiving a file with 984 bytes per line should not disrupt your processing. This applies to both Header and Content lines.File Name Disclaimer
The date in file name should be used as a guideline for human eyes only. Any date-related programmatic dependencies should rely on theFileCreatedDate
orFileEffectiveDate
contained within the header line of each file, as these will be precise to the second and will be in the appropriate timezone.
Header Row
Property | Data Type (Length) | Alignment | Start Position | Description |
---|---|---|---|---|
RecordType | string (1) | Left | 1 | The flag for the header row. Will always be H . |
FileName | string (50) | Left | 2 | The name of this file excluding path. Format: yyyyMMddhhmm_ACCOUNTLOCK.txt Example: 201407162348_ACCOUNTLOCK.txt |
RecordCount | integer (10) | Right | 52 | The number of records represented within the file. This field is zero-padded on the left side. Example: 0000000872 |
FileCreatedDate | datetime (34) | Left | 62 | The date the file was created. Follows same format as API. Example: 2014-10-20T10:30:31.456-05:00 See data format guidelines |
FileEffectiveDate | datetime (34) | Left | 96 | The date to which the data in the file pertains. Follows same format as API. Example: 2014-10-20T23:59:59.999-05:00 See data format guidelines |
ReferenceId | string (50) | Left | 130 | A client-supplied unique identifier that will be included in the header row of the response file after Helix has processed this file. This allows correlation of the request and response files. |
Content Row
Property | Data Type (Length) | Alignment | Start Position | Description |
---|---|---|---|---|
CustomerId | integer (10) | Right | 1 | The Helix-assigned unique ID for a customer. This field is zero-padded on the left side. Example: 0000000872 |
AccountId | integer (10) | Right | 11 | The Helix-assigned unique ID for an account. This field is zero-padded on the left side. Example: 0000000112 |
LockTypeCode | enum (3) | Left | 21 | See lockTypeCode on /account/lock for possible values |
LockReasonTypeCode | enum (3) | Left | 24 | See lockReasonTypeCode on /account/lock for possible values |
Notes | string (256) | Left | 27 | Optional note to show within the Admin Portal on the customer screen |
IsDemographicLock | string(1) | Left | 283 | Optional field. Values are: - Y : applies a demographic lock to all Helix accounts for a customer, as well as all cards and external accounts associated with the customer- N : applies a lock to only the account of the defined AccountId |
Take me to the Example Bulk Account Lock Request File
Bulk Account Lock Response File Definition
The Bulk Account Lock Response File is created by Helix after Helix processes a Bulk Account Lock Request File. It has the following properties:
- Fixed-length
- ANSI encoded
- Line endings are Windows-style CarriageReturn + LineFeed (
\r\n
, or0x0D0A
) - File will appear in the relative directory of
/BulkAccountLock/Response
- File name follows a specific, case-sensitive pattern of:
yyyyMMddhhmm_BULKACCOUNTLOCKRESPONSE.TXT
- This file is an exception in the naming convention used by other files. The date in the file name is the exact same date as the one in the corresponding Bulk Account Lock Request File. It is NOT the
CreatedDate
of the file. - For example, if the Bulk Account Lock Request File name is
201501080015_BULKACCOUNTLOCK.txt
, the response file name will be201501080015_BULKACCOUNTLOCKRESPONSE.TXT
regardless of the actualCreatedDate
orEffectiveDate
- This file is an exception in the naming convention used by other files. The date in the file name is the exact same date as the one in the corresponding Bulk Account Lock Request File. It is NOT the
Format Disclaimer
Helix reserves the right to append new field(s) to the end of any Header or Content line without notice. This is to allow new data points to be added as needed in a timely fashion.Implementation Note
Your code should be written such that unexpected characters after the "last" field but prior to the end of each line should be ignored. That is, if the file is documented as being 872 bytes per line, receiving a file with 984 bytes per line should not disrupt your processing. This applies to both Header and Content lines.File Name Disclaimer
The date in file name should be used as a guideline for human eyes only. Any date-related programmatic dependencies should rely on theFileCreatedDate
orFileEffectiveDate
contained within the header line of each file, as these will be precise to the second and will be in the appropriate timezone.
Header Row
Property | Data Type (Length) | Alignment | Start Position | Description |
---|---|---|---|---|
RecordType | string (1) | Left | 1 | The flag for the header row. Will always be H . |
FileName | string (50) | Left | 2 | The name of this file excluding path. Format: yyyyMMddhhmm_BULKACCOUNTLOCKRESPONSE.TXT Example: 201407162348_BULKACCOUNTLOCKRESPONSE.TXT NOTE: File name will not contain the CreatedDate . It will consist of the same file name as the Bulk Account Lock Request File that caused this file to be generated but with "RESPONSE" appended to the end of the file name prior to the file extension. |
RecordCount | integer (10) | Right | 52 | The number of Content lines in this file. This field is zero-padded on the left side. Example: 0000000003 |
FileCreatedDate | datetime (34) | Left | 62 | The date the file was created. Follows same format as API. Example: 2014-10-20T10:30:31.456-05:00 See data format guidelines |
FileEffectiveDate | datetime (34) | Left | 96 | The date to which the data in the file pertains. Follows same format as API. Example: 2014-10-20T23:59:59.999-05:00 See data format guidelines |
ReferenceId | string (50) | Left | 130 | The client-supplied unique identifier that was supplied in the corresponding request file. |
SuccessCount | integer (10) | Right | 180 | The number of records successfully processed by Helix. This field is zero-padded on the left side. Example: 0000000001 |
FailedCount | integer (10) | Right | 190 | The number of records that failed processing by Helix. This field is zero-padded on the left side. Example: 0000000003 |
ProcessedCount | integer (10) | Right | 200 | The number of records processed (either successfully or unsuccessfully) by Helix. This field is zero-padded on the left side Example: 0000000004 |
Content Row
Property | Data Type (Length) | Alignment | Start Position | Description |
---|---|---|---|---|
CustomerId | integer (10) | Right | 1 | The Helix-assigned unique ID for a customer. This field is zero-padded on the left side. Example: 0000000872 |
AccountId | integer (10) | Right | 11 | The Helix-assigned unique ID for an account. This field is zero-padded on the left side. Example: 0000000112 |
LockTypeCode | enum (3) | Left | 21 | See lockTypeCode on /account/lock for possible values |
LockReasonTypeCode | enum (3) | Left | 24 | See lockReasonTypeCode on /account/lock for possible values |
LockFailReason | string (255) | Left | 27 | The reason the requested unlock failed. Will be NA if the request was successful or the CustomerId/AccountId was not found. See Error Codes section on /account/lock for possible values |
Take me to the Example Bulk Account Lock Response File
Updated 6 months ago