Print Subscription Confirmation (PSC)

Process Overview

Note: A daily subscriber file sample must be delivered via email to Piano before the scheduled PSC launch date. Piano needs to confirm the file format before the first time submission to the FTP site.

PSC Configurations in Application Settings

The below settings can only be configured by a Piano admin:

Print Subscriber File and Data Requirements

File Requirements

• Naming Convention

  • Publication_Name_YYYYMMDD.txt or PUBLICATION_NAME_YYYYMMDD.txt, as long as it matches what is in Piano's database

    (Note there are no spaces)

  • File name IS case sensitive

  • The listed date in the file name must be the date on which the file will be processed. If a client submits the file after 8:50 PM EST, the following day's date should be listed. Past dates will not be processed.

• File Type: Raw text file

• Daily limit: Clients can post only one file per application per day. The only exception to this rule is when a file exceeds the error rate, does not run, and has to be corrected and re-posted.

Print Subscriber Record Requirements

• Pipe-delimited fields in ONLY UTF-8: LastName|FirstName|Phone|BuildingNumber|StreetName|PostalCode|AccountNumber

• Customer record must be separated via line breaks

• Include subscribers from all delivery schedules and those on vacation stops

• Field requirements

  • Field lengths are not fixed

  • Spaces are permitted

  • Exclude hyphens from every field

  • Include area code in the phone number

  • 5 OR 9 alphanumeric postal codes are allowed

  • The account number is the customer subscription number and must be unique for each customer record per application. (Changing the user's account_id at any later point after a successful PSC run won't cause any issues. The validation is going to run as expected.)

Data Validation (Matching) Process

Description

This process compares records in the Piano Input file (file which contains end-users who completed the PSC flow) against records in the Client Subscriber file.  Validation updates rows in Piano database to have a match status of true or false. If validation does not run, then rows in the Piano database do not update.

Rules

• The first step of this process is a dry run, to calculate the percentage of errors that exist.  The dry run determines if the error rate threshold has been exceeded. In application settings, a Piano admin sets the error rate (the rate of match failure between the Print Subscriber file and Piano Input file) to the client’s desired amount. 

  • The default error rate is 15%.  

  • When the error rate is exceeded, internal Piano contacts are notified through email.

• If the amount of errors does not exceed the set threshold, as a next step, validation runs and updates rows in the Piano database to have a match status of true or false.

• If the amount of errors exceed this threshold, validation does not run, rows in the database do not update, and user subscription status is unaffected.

• All users within a Client Subscriber file are validated together, once a day, based on the time the client posts their file in FTP

• Data validation/the matching process is based on the following fields - LastName (or CompanyName), BuildingNumber, StreetName, Phone, and PostalCode.

• For this process, LastName and CompanyName are interchangeable.  The client can send CompanyName instead of LastName in the event that the end-user inputs their company name instead of first and last name.

• It's possible for two or more users in Piano with different emails to match the same address in your PSC file.

• Note that BuildingNumber and StreetName are matched as separate fields in the matching process
  

  The user should enter the BuildingNumber before the StreetName (as generally used for US addresses). So they should add their street address in the order: BuildingNumber + StreetName

• 3 out of 5 fields must match for a record to pass data validation. The exceptions to this rule are as follows:

• • If LastName or CompanyName + StreetName match, PostalCode is automatically assumed to match, resulting in a record that passes data validation

  • If LastName or CompanyName + Phone match, PostalCode is automatically assumed to match, resulting in a record that passes data validation

• How PSC fields are processed

  • Last name: removes everything except A-Z/a-z characters, digits 0-9, spaces, and then capitalizes it

    • Before:

      Willard Carroll Smith Jr.

    • After: WILLARD CARROLL SMITH JR

  • Company name: removes everything except A-Z/a-z characters, digits 0-9, spaces, and then capitalizes it

    • Before:

      alpha-Beta     Гамма*12390 ++z Inc. Россия-Казахстан Девелопмент 24/66 

    • After: ALPHABETA     12390 Z INC 2466

  • Suffixes in names: does not ignore suffixes[image-zoomable][/image-zoomable]

    • Before:

      Willard Carroll "Will" Smith Jr.

    • After:

      WILLARD CARROLL WILL SMITH JR

  • Dashes and parentheses in phone number: removes everything except A-Z/a-z characters and digits 0-9, and then capitalizes any alpha characters.

    • Before:

      +9(123)456-789-0'12.BB A

    • After:  9123456789012BBA

  • Postal code: removes everything except A-Z/a-z characters, digits 0-9, and then capitalizes it

    • Before:

      k1a-0b1

    • After:  K1A0B1

  • Address: 

    • Building number: removes everything except digits 0-9.

    • Street name

      • removes everything except A-Z/a-z characters, digits 0-9, spaces, and then capitalizes it.

      • The following suffixes are removed from the street name

If you'd like to edit the look and feel of the input screen of these PSC fields you can do so in the External Verification Components template.

Run Times

See run times for Data Validation and Verification here

Verification Process

Description

Verification is a process that runs separate from data validation where each user’s access is verified individually and is based on the most recent match status from the data validation process.

• Verification period: The verification process runs as often as it is specified in the verification period field and if all criteria were met.  It is recommended by Piano that the verification period is kept at 1 day.

  • There are two different types of terms that can be created with PSC logic

    • External Service Term - user redeems free digital access with an existing print subscription.  In this case, the verification period is configurable but defaults to 1 day

    • Payment Subscription + External API - user redeems digital access as a part of a payment term.  In this case, the verification period is ALWAYS 1 day.

  • Regardless of the verification period setting at the term, when a user is in a grace period, the verification period is ALWAYS 1 day

• The next verification date is calculated as the date of PSC redemption or the previous verification date plus the verification period.

• Verification checks if a subscription is marked as match = true or match = false (by data validation). 

• If subscription is marked as match = true, then verification calculates a next verification date, keeps subscription and access active.

• If subscription is marked as match = false, then verification starts grace period and sets next verification date to tomorrow.

• Verification sends the following emails:

  • External API verification success email - sent immediately after redemption (verification does not need to run for this email to be sent)

  • Verification rejection - when a user fails data validation

  • F1 - goes out approximately 24 hours after the grace period starts. This depends on when the verification job runs

  • F5 - day 5 of grace period

  • Suspend - day 8 of grace period - FINAL EMAIL and then access is revoked if the record is not verified

• After verification runs, the Subscription Details Report Status field is updated to reflect access status

Grace Period

• Grace period is hardcoded to be 8 days

• Verification runs every day for a subscription in a grace period 

Run Times

See run times for Data Validation and Verification here

Run Times

Piano Input File Generation

The Piano input file containing user addresses from our database is generated only once per day between 4:30 - 4:35 AM EST.

Any edits to user addresses after this time of the day will be applied in the input file of the following day.

Piano Subscriber File Detection

Piano checks the FTP for a Print Subscriber file every 60 minutes, from 6:50am to 8:50pm EST.

Data Validation

• Data Validation runs 6 times a day: 8am, 11am, 2pm, 5pm, 8pm, 11pm EST

• The time the client sends their Print Subscriber File will determine which time slot they will fall into for data validation.

• Duration: this process can run on average between 2 - 4 hours, but it is possible for it to take longer depending on how many files have been uploaded

Verification

• Verification runs 4 times a day: 2:20am, 11:20am, 5:20pm, and 9:20pm EST

• For new users: 1st Verification = PSC redemption time + 24hrs + time until next verification run

Below is a visual diagram displaying run times of the above three processes in EST:

Possible Redemption Scenarios

(with sample redemption times based on process run times)

You can use the following guide for updating a user's PSC address via API if needed.

The same goes for subscribing users to PSC terms in general. Currently, we support this only on the frontend, and it's not possible to subscribe a user to a PSC term via API.

Data Segregation and Security

• Client subscriber records included in the daily subscriber file are held only by Piano.

• Data in the daily subscriber file is used only for the print subscription confirmation process. Piano will not use this data for any other purpose.

Glossary

• PSC Subscriber File - file from the client that contains records of customers that are print subscribers

• Piano Input File - data from Piano that contains records of end-users who completed the PSC flow to redeem a digital access

• Data Validation - a process that checks for error rate and marks records between the PSC Subscriber File and Piano Input File as matched or not matched if the error rate has not been exceeded

• Dry Run - The dry run calculates the percentage of errors that exist and determines if the error rate threshold has been exceeded.  The match status rows in the Piano database are only updated if the error rate does not exceed the set threshold and data validation runs again after the dry run

• Verification - a process which checks for match status of records after data validation and determines if access is granted, revoked, or user enters/continues grace period

Last updated: June 24, 2026