TaxGuardian External API Gateway Documentation

Welcome to the TaxGuardian External API Gateway documentation. This API provides secure access to TaxGuardian's comprehensive tax identity protection and monitoring services for partner integrations.

Overview

The TaxGuardian External API Gateway is a partner-facing API that enables integration with TaxGuardian's 24/7 IRS monitoring, real-time alerts, and tax identity protection services. The API is designed to be secure, scalable, and easy to integrate.

Architecture

Key Features

• Secure Partner Integration: OAuth 2.0 authentication with Azure API Management
• Rate Limiting: Rate limiting is enforced to ensure fair usage. For specific rate limit details, contact TaxGuardian customer support.

Environments

The API supports multiple environments:

• DEV: Development environment for testing and integration development
• PROD: Production environment for live partner integrations

Authentication

The TaxGuardian External API Gateway uses OAuth 2.0 authentication via Azure Active Directory (Azure AD) through Azure API Management. All API requests (except the health check and OAuth token endpoint) require a valid Bearer token.

Authentication Flow

OAuth 2.0 Client Credentials Flow

The API uses the OAuth 2.0 Client Credentials grant type for machine-to-machine (M2M) authentication:

1. Obtain OAuth credentials (Client ID, Client Secret, Tenant ID) from your Azure AD application
2. Request an access token from Azure AD OAuth endpoint
3. Include the access token in the Authorization header of subsequent API requests
4. Tokens expire after a set period and must be refreshed. For specific expiration details, contact TaxGuardian customer support.

Subscription Key

In addition to OAuth tokens, Azure API Management requires a subscription key for API access. This key is provided by TaxGuardian and should be included in the X-API-Key header (or Ocp-Apim-Subscription-Key header).

Environment-Specific Endpoints

OAuth endpoints differ between environments:

• DEV: Uses development Azure AD tenant and OAuth endpoints
• PROD: Uses production Azure AD tenant and OAuth endpoints

Configure the azureOauthUrl and tenantId variables according to your environment.

Getting Started

Prerequisites

• Postman application (or similar API testing tool)
• TaxGuardian External API Gateway Postman collection
• OAuth credentials (Client ID, Client Secret, Tenant ID)
• Azure API Management subscription key
• Partner ID and tier information

Environment Setup

1. Import the Postman Collection:
   • Open Postman
   • Click "Import" and select the "TaxGuardian External API Gateway" collection file
   • The collection will be imported with all endpoints pre-configured
2. Create an Environment:
   • Create a new environment in Postman (e.g., "External API Gateway - DEV")
   • Add the following variables (see Variables Reference section for details):

Required Environment Variables

First API Call Walkthrough

1. Get OAuth Token: Obtain access token
   • Endpoint: POST {azureOauthUrl}/{tenantId}/oauth2/v2.0/token
   • Use your OAuth credentials
   • The response will contain an access_token that will be automatically saved to oauth_token variable
2. Health Check: Verify API availability
   • Endpoint: GET /health
   • Requires Bearer token (automatically included from previous step)
   • Should return 200 OK if API is available

API Endpoints

This section documents all available endpoints in the TaxGuardian External API Gateway.

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

curl -X POST "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret" \
  -d "scope=api://your-api-id/.default"

const formData = new URLSearchParams();
formData.append('grant_type', 'client_credentials');
formData.append('client_id', 'your-client-id');
formData.append('client_secret', 'your-client-secret');
formData.append('scope', 'api://your-api-id/.default');

fetch('https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: formData
})
  .then(response => response.json())
  .then(data => {
    console.log('Access Token:', data.access_token);
    // Save token for subsequent requests
  });

import requests

url = f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token"
data = {
    'grant_type': 'client_credentials',
    'client_id': 'your-client-id',
    'client_secret': 'your-client-secret',
    'scope': 'api://your-api-id/.default'
}

response = requests.post(url, data=data)
token_data = response.json()
access_token = token_data['access_token']
print(f"Access Token: {access_token}")

curl -X GET "https://taxguardian-apim-dev.azure-api.net/external/v1/health"

fetch('https://taxguardian-apim-dev.azure-api.net/external/v1/health')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

import requests

response = requests.get('https://taxguardian-apim-dev.azure-api.net/external/v1/health')
print(response.json())

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "ssn": "456-13-6129",
  "dateOfBirth": "1990-01-15T00:00:00Z",
  "address": {
    "street1": "123 Main St",
    "street2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001"
  }
}

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

curl -X POST "https://taxguardian-apim-dev.azure-api.net/external/v1/users" \
  -H "Authorization: Bearer {oauth_token}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {subscription_key}" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "ssn": "456-13-6129",
    "dateOfBirth": "1990-01-15T00:00:00Z",
    "address": {
      "street1": "123 Main St",
      "street2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001"
    }
  }'

const userData = {
  firstName: "John",
  lastName: "Doe",
  email: "john.doe@example.com",
  ssn: "456-13-6129",
  dateOfBirth: "1990-01-15T00:00:00Z",
  address: {
    street1: "123 Main St",
    street2: "Apt 4B",
    city: "New York",
    state: "NY",
    zipCode: "10001"
  }
};

fetch('https://taxguardian-apim-dev.azure-api.net/external/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${oauthToken}`,
    'Content-Type': 'application/json',
    'X-API-Key': subscriptionKey
  },
  body: JSON.stringify(userData)
})
  .then(response => response.text())
  .then(userId => {
    console.log('User ID:', userId);
    // Save userId for subsequent requests
  });

import requests

url = "https://taxguardian-apim-dev.azure-api.net/external/v1/users"
headers = {
    "Authorization": f"Bearer {oauth_token}",
    "Content-Type": "application/json",
    "X-API-Key": subscription_key
}
data = {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "ssn": "456-13-6129",
    "dateOfBirth": "1990-01-15T00:00:00Z",
    "address": {
        "street1": "123 Main St",
        "street2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "zipCode": "10001"
    }
}

response = requests.post(url, headers=headers, json=data)
user_id = response.text
print(f"User ID: {user_id}")

{
  "Form": "8821",
  "TaxYearStart": 2022,
  "TaxYearEnd": 2024
}

{
  "signatureUrl": "https://sign.taxguardian.com/sign?token=abc123xyz..."
}

{
  "FormType": "FORM_8821",
  "TaxYearStart": 2022,
  "TaxYearEnd": 2024
}

{
  "Id": 10,
  "PublicId": "a4e70af7-f690-4a4a-b2b6-f74e38d17899",
  "BusinessTaxEventID": 554,
  "OutgoingMessageID": 1034,
  "AlertType": "IDENTITYTHEFT",
  "UserResponse": "No",
  "ResponseTimestamp": "2025-11-10T00:00:00",
  "GuidanceContent": "{...}",
  "Status": "DISPUTED",
  "CreatedAt": "2025-11-09T00:00:00",
  "UpdatedAt": "2025-11-14T18:08:47.9271014",
  "BusinessTaxEvent": {
    "Id": 554,
    "EventDescription": "A tax return has just been filed with your SSN. Was this you?",
    "EventDate": "2025-09-26T00:00:00",
    "AmountInCents": 1876598,
    "TaxFormNumber": "1040",
    "TaxYear": 2024,
    "Severity": "CRITICAL",
    "SeverityScore": 1
  }
}

{
  "userResponse": "No"
}

{
  "success": true,
  "message": "Alert response recorded successfully.",
  "guidanceContent": ""
}

{
  "success": true,
  "message": "Alert response recorded successfully.",
  "guidanceContent": {
    "title": "Identity verification requested (Letter 5071C/6331C)",
    "nextsteps": [
      "Complete IRS identity verification online",
      "Call IRS if online fails",
      "Gather ID documents"
    ],
    "messaging": "IRS needs to verify your identity for a recent tax return. Follow the instructions on Letter 5071C/6331C."
  }
}

{
  "FormType": "FORM_8821",
  "TaxYearStart": 2022,
  "TaxYearEnd": 2024
}

{
  "FormType": "FORM_8821",
  "TaxYearStart": 2022,
  "TaxYearEnd": 2024
}

Error Handling

Error Response Format

All error responses follow a consistent format using the ApiErrorResponse structure:

{
  "message": "User-friendly error message",
  "validationErrors": {
    "fieldName": ["Error message 1", "Error message 2"]
  }
}

HTTP Status Codes

Error Handling Best Practices

• Always check the HTTP status code before processing response data
• Implement exponential backoff for 429 (rate limit) and 503 (service unavailable) errors
• Log error responses for debugging and monitoring
• Display user-friendly error messages from the message field
• Handle validation errors by checking the validationErrors object
• Refresh OAuth tokens when receiving 401 errors

Rate Limiting

Azure API Management enforces rate limiting to ensure fair usage. When the rate limit is exceeded, the API returns a 429 Too Many Requests status code. For specific rate limit details, contact TaxGuardian customer support.

Environment Variables Reference

This section documents all environment variables required for the TaxGuardian External API Gateway.

Required Variables

Auto-Generated Variables

These variables are automatically set by Postman test scripts:

Setting Variables in Postman

1. Click the "Environments" icon in the left sidebar
2. Select your environment (or create a new one)
3. Click "Add" to create a new variable
4. Enter the variable name and value
5. Save the environment

Best Practices

Security

• Never expose credentials: Keep OAuth client secrets and subscription keys secure. Never commit them to version control or expose them in client-side code.
• Use HTTPS: Always use HTTPS for all API requests. Never send sensitive data over HTTP.
• Token management: Store OAuth tokens securely and refresh them before expiration. For specific token expiration details, contact TaxGuardian customer support.
• Validate responses: Always validate API responses before processing data to prevent security vulnerabilities.

Rate Limiting

• Respect limits: The API enforces rate limiting to ensure fair usage. For specific rate limit details, contact TaxGuardian customer support.
• Implement backoff: When receiving 429 (Too Many Requests) errors, implement exponential backoff before retrying.
• Monitor usage: Track your API usage to avoid hitting rate limits unexpectedly.

Error Handling

• Handle all status codes: Implement proper error handling for all possible HTTP status codes.
• Retry logic: Implement retry logic for transient errors (500, 503, 429) with exponential backoff.
• Logging: Log all API errors for debugging and monitoring purposes.
• User feedback: Provide clear, user-friendly error messages based on API error responses.

Performance

• Cache tokens: Cache OAuth tokens and reuse them until they expire to reduce authentication overhead.
• Async operations: Use asynchronous operations for API calls to avoid blocking your application.
• Connection pooling: Reuse HTTP connections when making multiple API calls.
• Minimize requests: Reduce the number of API calls by batching operations and caching data when appropriate.

Environment Management

• Separate environments: Use separate Postman environments for DEV and PROD to avoid accidental production calls.
• Environment validation: Validate that you're using the correct environment before making API calls.
• Variable management: Keep environment variables organized and documented.