Sharing Social Security Scenarios with URL Parameters

Published: 10/7/2025

The SSA.tools calculator supports URL parameters that allow you to create shareable links with preloaded scenarios. This feature is invaluable for financial advisors explaining concepts to clients, educators demonstrating Social Security principles, or simply sharing benefit comparisons with family members.

Why Use URL Parameters?

Rather than manually entering earnings records and birthdates each time you want to show someone a specific scenario, you can encode that information directly in the URL. When someone clicks your link, the calculator will automatically load with your specified parameters.

Basic URL Structure

URL parameters are added to the calculator URL using a hash (#) followed by parameter pairs. The basic format is:

https://ssa.tools/calculator#pia1=VALUE&dob1=DATE&name1=NAME

Available Parameters

There are two ways to specify recipient data: using PIA (Primary Insurance Amount) or using a detailed earnings history. The earnings history approach provides more functionality but requires longer URLs.

Option 1: PIA-Based Parameters (Simple)

This approach is simpler and results in shorter URLs, but the calculator cannot show how future earnings affect your benefits.

For a Single Person

• pia1 - Primary Insurance Amount in dollars (required)
• dob1 - Date of birth in YYYY-MM-DD format (required)
• name1 - Person's name for display (optional, defaults to "Self")

For a Couple

To include a spouse, add the corresponding parameters with "2" suffix:

• pia2 - Spouse's Primary Insurance Amount in dollars
• dob2 - Spouse's date of birth in YYYY-MM-DD format
• name2 - Spouse's name for display (optional)

Option 2: Earnings History Parameters (Advanced)

This approach allows the calculator to show the full benefits report including AIME calculations, indexed earnings, and how future earnings affect your PIA. URLs will be longer but provide complete functionality.

Format

Earnings are specified as comma-separated year:amount pairs. For example: earnings1=2020:50000,2021:55000,2022:60000

For a Single Person

• earnings1 - Earnings history as year:amount pairs (required)
• dob1 - Date of birth in YYYY-MM-DD format (required)
• name1 - Person's name for display (optional, defaults to "Self")

For a Couple

• earnings2 - Spouse's earnings history as year:amount pairs
• dob2 - Spouse's date of birth in YYYY-MM-DD format
• name2 - Spouse's name for display (optional)

Earnings Format Rules

• Format: year:amount,year:amount,...
• Years: 4-digit integers (1951-2100)
• Amounts: Dollar amounts without $ or commas
• Separate pairs with commas
• You can include as many years as needed
• Years do not need to be consecutive (gaps are allowed)
• Use 0 for years with no earnings

Example URLs

PIA-Based Examples

Single Person Example

A single person named Alex with a PIA of $3,000, born September 21, 1965:

https://ssa.tools/calculator#pia1=3000&dob1=1965-09-21&name1=Alex

Try this example →

Couple Example

Alex (PIA $1,000) and Chris (PIA $0, eligible for spousal benefits only):

https://ssa.tools/calculator#pia1=1000&dob1=1965-09-21&name1=Alex&pia2=0&dob2=1965-09-28&name2=Chris

Try this example →

Earnings History Examples

Single Person with Recent Earnings

Jordan, born March 15, 1995, with three years of earnings history:

https://ssa.tools/calculator#earnings1=2020:50000,2021:55000,2022:60000&dob1=1995-03-15&name1=Jordan

Try this example →

Person with Longer Career History

Pat, born June 20, 1980, with 10 years of steady career progression:

https://ssa.tools/calculator#earnings1=2000:35000,2001:38000,2002:42000,2003:45000,2004:48000,2005:52000,2006:55000,2007:58000,2008:60000,2009:62000&dob1=1980-06-20&name1=Pat

Try this example →

Couple with Both Earnings Histories

Alex and Chris, both with earnings histories showing different career paths:

https://ssa.tools/calculator#earnings1=2020:80000,2021:85000&dob1=1960-01-15&name1=Alex&earnings2=2020:40000,2021:42000&dob2=1962-03-10&name2=Chris

Try this example →

Career with Gaps (Zero Earnings Years)

Sam with a career break showing zero earnings for 2017-2018:

https://ssa.tools/calculator#earnings1=2015:50000,2016:55000,2017:0,2018:0,2019:60000,2020:65000&dob1=1980-03-20&name1=Sam

Try this example →

Real-World Use Case: Spousal Benefits

This feature is particularly useful for demonstrating spousal benefit scenarios. For example, showing how a spouse with zero PIA (no work history) can receive spousal benefits based on their partner's earnings:

https://ssa.tools/calculator#pia1=2500&dob1=1960-06-15&name1=Pat&pia2=0&dob2=1962-03-10&name2=Sam

Try this PIA-based example →

Using earnings history (more detailed):

https://ssa.tools/calculator#earnings1=2010:60000,2011:62000,2012:65000,2013:68000,2014:70000,2015:73000,2016:75000,2017:78000,2018:80000,2019:82000,2020:85000&dob1=1960-06-15&name1=Pat&pia2=0&dob2=1962-03-10&name2=Sam

Try this earnings-based example →

Privacy Considerations

URL parameters are processed entirely in the browser—no data is sent to a server. However, be mindful that:

• URLs are visible in browser history.
• Shared links expose the information (PIA/earnings and birthdate) to anyone who views them.
• Use generic examples (not real personal data) when sharing publicly or in educational settings.

Related Resources

• Primary Insurance Amount (PIA) - Understanding what PIA is and how it's calculated
• Averaged Indexed Monthly Earnings (AIME) - How your earnings history determines your PIA
• Navigate the Filing Date Chart - Understanding the calculator's output
• Deep look at Spousal Benefits and Filing Dates - Complex scenarios involving couples