Full Workflow

We strongly recommend you download the Developer Integration Kit prior to development, which will walk you through the full workflow below.

🚧
Access the Complete Developer Integration Kit
The full implementation kit includes the ready-to-run Postman collection, sample applications in multiple languages, session recording examples, and an AI IDE copilot.
Clients can download the complete kit from the Client Support Center.
New to Symmetry? Contact us to request access and speak with our team.

Step 1: Authenticate

Obtain an access token using your API key. All STL API requests require a bearer token in the Authorization header:

Authentication Request

GET https://api.symmetry.com/authentication/login

Headers:

Header	Value
`Accept`	`application/json`
`api-key`	`<your-symmetry-api-key>`

Authentication Response

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs..."
}

The accessToken field contains your Bearer token. Use it in subsequent requests:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

📘
Full Authentication Examples Available
Production-ready authentication examples (including token refresh handling and environment setup) are available in the Developer Integration Kit.
Log in to download the complete samples, or contact us to request access.

Step 2: Determine Your STE Integration Type

How does your system call STE to calculate taxes?

                    How do you call STE?
                           │
              ┌────────────┴────────────┐
              ▼                         ▼
        JSON API                  On-Prem SDK
     (HTTP/REST)              (C, Java, or C#)
              │                         │
              ▼                         ▼
     You already have           Use Session Recording
     the PayCalc JSON           to capture STE calls
     — go to Path A             — go to Path B

❗️
Need Help Choosing the Right Path?
The Integration Kit includes guided examples for both JSON API and On-Prem SDK implementations, including complete working projects.
Clients can access the full walkthrough in the Developer Hub. Prospects can connect with our team for guided onboarding.

Integration Type	What You Have	Recommended Approach
STE JSON API	Employee PayCalc data	Use the flat employee object directly as `context.payCalc` — simplest path
STE On-Prem SDK	Individual SDK API calls (C/Java/C#)	Implement Session Recording — wraps your existing code with start/stop calls (Path B)

Step 3: Obtain the Payroll Context

Path A: You Use the STE JSON API

This is the simplest path. You already have the employee PayCalc data that you send to STE. You just need to capture and store the flat employee object.

What to do:

When your system calls STE via the JSON API, save the flat employee PayCalc object
Associate it with the employee, pay period, and pay date for later retrieval
When a user clicks to explain a tax, retrieve that saved PayCalc object

📘
Complete JSON API Samples Available
Our Client Developer Hub includes full, runnable JSON API implementations with database storage examples and error handling patterns.
Log in to download the full samples, or request access to get started.

Skip to Step 4.

Path B: You Use the STE On-Premise SDK (C/Java/C#)

When you use the on-premise SDK, you call individual setter functions rather than sending a single JSON object. To provide context to STL, capture those calls using Session Recording.

Session Recording captures every STE API call you make and packages it into a compact, replayable base64 string. It requires no restructuring of your existing code — just wrap your calculation with start/stop calls.

📘
Session Recording Deep Dive
Detailed SDK documentation, edge-case handling, and full language-specific projects are available in the Client Support Center.
Clients can log in for full access. New to Symmetry? Contact us to request implementation support.

Step 4: Associate a UI Action with a Tax ID

The Tax ID identifies which specific tax you want explained. You need to connect a user's UI click to the correct Tax ID.

Tax ID Format

📘
Symmetry Tax ID Guidance
Clients can find simple guidance on all Symmetry Tax IDs in our Developer Hub.
New to Symmetry? Contact us to learn more about how the engine calculates taxes using the Symmetry Tax ID.

Step 5: Construct the STL API Request

The STL API has one main endpoint:

POST https://api.symmetry.com/stl/v1/explain

There are two request formats depending on whether you have JSON or a session recording.

📘
Ready-to-Run Postman Collection
A complete Postman collection with preconfigured environments and example requests is available in the Developer Integration Kit.
Log in to download it, or request access to begin testing immediately.

Step 6: Call the STL API

Full Example (Authentication + Explain)

📘
Complete Runnable Clients Included
Full, production-ready client implementations (Node, Java, C#, and more) are available in the Developer Integration Kit, along with environment configuration and error handling examples.
Access the kit in the Client Support Center or contact us to request access.

Step 7: Process the Response

Success Response (HTTP 200)

The response contains a results array with one entry per requested tax ID:

{
    "id": "01JCPMF5BQ812345",
    "summary": "Your paycheck has three federal withholdings: $76.50 for Social Security (6.2% of $1,000 gross), $14.50 for Medicare (1.45% of $1,000 gross), and $78.00 for Federal Income Tax based on your Single filing status.",
    "results": [
        {
            "taxId": "00-000-0000-FICA-000",
            "response": "Your Social Security (FICA) withholding for this paycheck is $76.50. This is calculated at 6.2% of your $1,000 gross wages...",
            "usage": { "input_tokens": 1250, "output_tokens": 110 }
        },
        {
            "taxId": "00-000-0000-MEDI-000",
            "response": "Your Medicare withholding for this paycheck is $14.50. This is calculated at 1.45% of your $1,000 gross wages...",
            "usage": { "input_tokens": 1250, "output_tokens": 95 }
        },
        {
            "taxId": "00-000-0000-FIT-000",
            "response": "Your Federal Income Tax withholding for this paycheck is $78.00. This was calculated using your $1,000 gross pay and your Single filing status...",
            "usage": { "input_tokens": 1250, "output_tokens": 125 }
        }
    ]
}

📘
Advanced Response Handling & Monitoring
The Integration Kit includes examples for caching, logging, usage tracking, and production monitoring.
Clients can log in for full implementation guidance. Prospects can connect with our team to learn more.

What the Response Text Looks Like

The response field always follows this structure:

Opening sentence: States the tax type and the final calculated amount
Explanation: 2–3 sentences explaining how the amount was derived, in plain English
Summary line: Simple math notation showing the key numbers

The text:

Uses plain English (no payroll jargon)
Translates technical terms (e.g., "taxable wages" becomes "the amount your tax is based on")
Is 80–120 words — concise enough for a tooltip or modal
Contains no markdown or HTML — safe to render as plain text

Step 8: Display the Explanation in Your UI

The response text is designed for direct display. Here are recommended UI patterns:

Pattern 1: Inline Expandable (Recommended)

Best for pay stub views where space is limited.

Federal Income Tax     $287.50   [▼ Why this amount?]

  ┌─────────────────────────────────────────────────┐
  │ Your Federal Income Tax withholding for this     │
  │ paycheck is $287.50. This was calculated using   │
  │ your $3,000 gross pay and your Single filing     │
  │ status. The system projects your annual income   │
  │ based on 26 pay periods to determine the correct │
  │ withholding amount from the federal tax tables.  │
  │                                                  │
  │ Summary: $3,000 biweekly × 26 periods =          │
  │ $78,000 projected annual → $287.50 withheld.     │
  └─────────────────────────────────────────────────┘

Pattern 2: Modal / Dialog

Best for mobile or when you want more visual emphasis.

Pattern 3: Tooltip / Popover

Best for dense data tables where minimal disruption is needed.

UI Implementation Tips

Show a loading state — The API typically responds in 2–4 seconds. Show a spinner or "Analyzing..." text.
Cache explanations — For the same paycheck, the explanation won't change. Cache client-side or server-side.
No parsing needed — The response is plain text. Render it directly.
Lazy load — Don't call the API until the user actually clicks "Explain".
Save the id — Store the response id for support/debugging purposes.

📘
Ready to Implement?
Download the complete Developer Integration Kit to stand up a working STL API integration in minutes.
Clients: Log in to the Client Support Center.
New to Symmetry? Contact us to request access and schedule a technical walkthrough.

Full Workflow

🚧
Access the Complete Developer Integration Kit

Step 1: Authenticate

Authentication Request

Authentication Response

📘
Full Authentication Examples Available

Step 2: Determine Your STE Integration Type

❗️
Need Help Choosing the Right Path?

Step 3: Obtain the Payroll Context

Path A: You Use the STE JSON API

📘
Complete JSON API Samples Available

Path B: You Use the STE On-Premise SDK (C/Java/C#)

📘
Session Recording Deep Dive

Step 4: Associate a UI Action with a Tax ID

Tax ID Format

📘
Symmetry Tax ID Guidance

Step 5: Construct the STL API Request

📘
Ready-to-Run Postman Collection

Step 6: Call the STL API

Full Example (Authentication + Explain)

📘
Complete Runnable Clients Included

Step 7: Process the Response

Success Response (HTTP 200)

📘
Advanced Response Handling & Monitoring

What the Response Text Looks Like

Step 8: Display the Explanation in Your UI

Pattern 1: Inline Expandable (Recommended)

Pattern 2: Modal / Dialog

Pattern 3: Tooltip / Popover

UI Implementation Tips

📘
Ready to Implement?

🚧Access the Complete Developer Integration Kit

Step 1: Authenticate

Authentication Request

Authentication Response

📘Full Authentication Examples Available

Step 2: Determine Your STE Integration Type

❗️Need Help Choosing the Right Path?

Step 3: Obtain the Payroll Context

Path A: You Use the STE JSON API

📘Complete JSON API Samples Available

Path B: You Use the STE On-Premise SDK (C/Java/C#)

📘Session Recording Deep Dive

Step 4: Associate a UI Action with a Tax ID

Tax ID Format

📘Symmetry Tax ID Guidance

Step 5: Construct the STL API Request

📘Ready-to-Run Postman Collection

Step 6: Call the STL API

Full Example (Authentication + Explain)

📘Complete Runnable Clients Included

Step 7: Process the Response

Success Response (HTTP 200)

📘Advanced Response Handling & Monitoring

What the Response Text Looks Like

Step 8: Display the Explanation in Your UI

Pattern 1: Inline Expandable (Recommended)

Pattern 2: Modal / Dialog

Pattern 3: Tooltip / Popover

UI Implementation Tips

📘Ready to Implement?

🚧
Access the Complete Developer Integration Kit

📘
Full Authentication Examples Available

❗️
Need Help Choosing the Right Path?

📘
Complete JSON API Samples Available

📘
Session Recording Deep Dive

📘
Symmetry Tax ID Guidance

📘
Ready-to-Run Postman Collection

📘
Complete Runnable Clients Included

📘
Advanced Response Handling & Monitoring

📘
Ready to Implement?