Skip to content

UPS Claims API Log Documentation

Menu Location: Tools > UPS Claims > API Logs

Access Level: Administrator / Kiva Admin

Last Updated: 2026-03-01

Overview

The UPS Claims API Log provides a technical view of all interactions between your system and the UPS Capital Claims API. This log is primarily used for troubleshooting API issues, verifying successful API calls, and investigating failed claim submissions or status checks. It displays raw API call data in a searchable table format.

Primary Functions:

  • View all UPS API calls made by the system
  • Troubleshoot failed claim submissions
  • Verify successful API communications
  • Analyze API call patterns and timing
  • Debug integration issues with UPS Capital

Page Layout

Header Section

  • Page Title: "UPS Claims \ Logs" breadcrumb navigation
  • Link to Main Claims: Return to UPS Claims management page
  • Date Range Filters: Select time period for log entries

Filter Controls

Three form fields to narrow displayed logs:

  • From: Starting date for log entries
  • To: Ending date for log entries
  • Search Button: Apply date range filter

Log Table

Dynamic table showing all API call records with:

  • All available database columns as headers
  • Scrollable rows with raw data
  • Automatically sized columns
  • Chronological order (newest first)
  • Limit of 200 most recent entries

Date Range Filtering

Default Date Range

  • From: 25 hours ago from current time
  • To: 1 hour into future (to catch current entries)

Setting Custom Range

Steps:

  1. Click in "From" date field
  2. Select starting date from calendar picker
  3. Click in "To" date field
  4. Select ending date from calendar picker
  5. Click "Search" button
  6. Table refreshes with logs from selected range

Tips:

  • Use narrow ranges for specific troubleshooting
  • Use wider ranges for pattern analysis
  • Future dates in "To" field help catch real-time activity

Log Data & Columns

The table displays all columns from the ups_api_calls database table. Common columns include:

Column Description Typical Values
id Unique log entry identifier Sequential number
timestamp When API call was made Unix timestamp (seconds since epoch)
api_endpoint Which UPS API was called Create Claim, Upload Document, Check Status
request_data Data sent to UPS JSON formatted request payload
response_data Data received from UPS JSON formatted response or error message
claim_id Internal claim ID if applicable Matches ups_claims.id
customer_id Customer associated with call Matches custy.id
success Whether call succeeded 1 for success, 0 for failure
error_message Error details if failed UPS error text or system error

Note: Actual columns may vary. The table automatically displays whatever columns exist in the database.

Reading Log Entries

Interpreting API Calls

Successful Call Pattern:

  • Timestamp shows when it occurred
  • Request data shows what was sent
  • Response data shows UPS confirmation
  • Success = 1
  • Claim ID links to claims table

Failed Call Pattern:

  • Timestamp shows attempt time
  • Request data shows what was tried
  • Response data or error_message explains failure
  • Success = 0
  • Useful for diagnosing problems

Common API Endpoints

Create Claim:

  • Endpoint includes "createclaim" or similar
  • Request shows full claim details
  • Response includes UPS claim number on success

Upload Document:

  • Endpoint includes "uploadDocument"
  • Request shows file metadata
  • Response confirms document received

Check Status:

  • Endpoint includes "status" or "claimStatus"
  • Request shows claim number lookup
  • Response includes current status text

Actions & Operations

Filter by Date Range

Purpose: Focus on specific time period for investigation

Steps:

  1. Determine time period of interest
  2. Enter From and To dates
  3. Click Search
  4. Review filtered results

When to Use:

  • Investigating issue from specific date
  • Reviewing claims processed during certain period
  • Analyzing patterns over time

View Raw API Data

Purpose: See exact data exchanged with UPS for debugging

Steps:

  1. Locate log entry of interest
  2. Read request_data column to see what was sent
  3. Read response_data column to see UPS reply
  4. Compare to expected values

Use For:

  • Understanding why claim failed
  • Verifying correct data was sent
  • Checking UPS error messages
  • Confirming successful submissions

Common Use Cases

Use Case 1: Investigate Failed Claim Submission

Goal: Understand why claim submission returned an error

Steps:

  1. Note the time when submission failed
  2. Navigate to UPS Claims API Logs
  3. Set date range covering the failure time
  4. Click Search
  5. Find the "createclaim" call with success = 0
  6. Read error_message column for UPS error
  7. Read request_data to see what was sent
  8. Identify the problematic field or value
  9. Correct in main UPS Claims page
  10. Retry submission

Example: Claim failed at 2:30pm. Filter logs from 2:00pm-3:00pm. Find entry showing error "Shipping amount must be numeric". Fix shipping amount field and resubmit.

Use Case 2: Verify Document Upload Succeeded

Goal: Confirm a document was successfully sent to UPS

Steps:

  1. Note when document was uploaded
  2. Open API Logs
  3. Filter to time period around upload
  4. Look for "uploadDocument" endpoint entry
  5. Check success column = 1
  6. Verify response_data shows confirmation

Tips:

  • Each document upload creates a separate log entry
  • Multiple uploads in quick succession will show multiple entries
  • Failed uploads will have success = 0 with error details

Use Case 3: Troubleshoot Status Check Failures

Goal: Determine why "Check" button returns errors

Steps:

  1. Try clicking "Check" on a claim
  2. Note the error message
  3. Go to API Logs
  4. Filter to last few minutes
  5. Find the "claimStatus" or "status" call
  6. Read error_message for details
  7. Check if UPS claim number is valid in request_data
  8. Verify API credentials are correct

Common Issues:

  • UPS claim number not found
  • API credentials expired or incorrect
  • UPS API temporarily unavailable

Use Case 4: Monitor API Health and Performance

Goal: Ensure API integration is working reliably over time

Steps:

  1. Set wide date range (e.g., last 30 days)
  2. Click Search to load entries
  3. Scan success column for patterns of failures
  4. Note any clusters of errors
  5. Investigate spikes in failure rates
  6. Review error_message patterns

What to Look For:

  • Increasing failure rates (may indicate API credential issue)
  • Specific error messages repeating (configuration problem)
  • Long gaps with no activity (system may not be making calls)
  • Sudden bursts of activity (bulk claim processing)

Use Case 5: Provide Data to Support for Troubleshooting

Goal: Give Kiva Logic support team information to diagnose issues

Steps:

  1. Identify the problematic claim or time period
  2. Navigate to API Logs
  3. Filter to relevant date range
  4. Take screenshots of relevant log entries
  5. Copy specific error_message text
  6. Note the log entry ID numbers
  7. Provide to support team with description of issue

Include:

  • Timestamp of failed calls
  • Error messages
  • What you were trying to do
  • Screenshots of request/response data if relevant

Filters & Search Options

Date Range Filters

  • From: Calendar picker for start date/time
  • To: Calendar picker for end date/time
  • Search: Apply filters to reload table

Default Behavior:

  • From defaults to 25 hours ago
  • To defaults to 1 hour in future
  • System converts dates to timestamps automatically

Sorting

Click any column header to sort by that column (if table supports it). Most useful sorts:

  • Timestamp: See chronological order
  • Success: Group failures together
  • API endpoint: See all calls of one type

Troubleshooting

No Log Entries Showing

Symptoms: Table is empty or shows "no notes found, try increasing the timeframe"

Solutions:

  1. Expand date range to cover longer period
  2. Verify UPS Claims have actually been created/processed
  3. Check that From date is before To date
  4. Try default range (clear dates and search)

Common Causes:

  • Date range too narrow
  • No API calls made during selected period
  • Dates entered incorrectly

Can't Read Request or Response Data

Symptoms: Data columns show truncated or hard-to-read text

Solutions:

  1. Widen browser window
  2. Use browser's inspect element to view full text
  3. Copy text to text editor for better formatting
  4. Look for JSON formatters online to pretty-print data

Tips:

  • Request/response data is usually JSON format
  • May need JSON formatter for readability
  • Look for key fields like "error" or "claimNumber"

Timestamps Are Confusing

Symptoms: Timestamp column shows large numbers, not readable dates

Check:

  • Timestamps are Unix epoch seconds
  • Convert using online tools or this formula: timestamp × 1000 for JavaScript date
  • Many log viewers have timestamp converters built-in

Quick Conversion: Use browser console: new Date(timestamp * 1000) where timestamp is the number shown.

  • UPS Claims (ups-claims.php) - Main claims management page
  • UPS Claims Settings - Configure API credentials that these logs track
  • System Logs - General system logging (separate from API logs)

Typical Workflow:

  1. UPS Claims → Attempt action → Fails
  2. API Logs → Investigate error → Find cause
  3. UPS Claims → Correct issue → Retry
  4. API Logs → Verify success

Permissions & Access

Required Access Level: Administrator or Kiva Admin

Access Level Capabilities:

  • Customer Service: Cannot access API logs
  • Manager: Cannot access API logs
  • Administrator: View API logs, troubleshoot issues
  • Kiva Admin: All Administrator capabilities plus API configuration

Why Restricted: API logs contain technical data that's primarily useful for troubleshooting and not needed for day-to-day claims management.

Best Practices

Troubleshooting Workflow

  1. Start at UPS Claims page where issue occurred
  2. Note exact time of the error
  3. Navigate to API Logs
  4. Use narrow date range around error time
  5. Identify the failed call
  6. Read error message thoroughly
  7. Compare request data to expected values
  8. Fix issue and verify in logs

Documentation for Support

  • Always include timestamps from logs
  • Screenshot the full log entry row
  • Copy error messages exactly
  • Note what action you were attempting
  • Include claim ID and order ID for context

Regular Monitoring

  • Check logs weekly for unusual patterns
  • Watch for increasing error rates
  • Investigate any new error types immediately
  • Keep screenshots of normal successful calls for comparison

Things to Avoid

  • ❌ Ignoring error patterns—they indicate systemic issues
  • ❌ Not checking logs after making API credential changes
  • ❌ Assuming API is working without verification
  • ❌ Deleting or modifying log entries (view only)

Quick Reference Card

Task Action/Location
Access API logs Tools > UPS Claims, click "API Logs" button
Return to claims Click "UPS Claims" in breadcrumb
Filter by date Set From/To dates, click Search
View default range Leave dates blank, click Search
Read API call details Scan table row for entry of interest
Find failed calls Look for success = 0 entries
Identify error cause Read error_message column
See what was sent to UPS Read request_data column
See UPS response Read response_data column
Troubleshoot submission Find "createclaim" entries with errors

FAQs

What's the difference between this and the "Logs" button on individual claims?

The "Logs" button on individual claims shows claim-specific history (status checks, uploads, shipping events) in a user-friendly format. The API Logs page shows raw technical data for ALL API calls across all claims—it's for system-wide troubleshooting.

How long are API logs stored?

Logs are stored indefinitely in the database. However, the page limits display to 200 most recent entries within your date range. For older or more extensive analysis, contact Kiva Logic support.

Can I delete or edit log entries?

No, this is a read-only log for audit and troubleshooting purposes. Log entries should not be modified or deleted as they provide historical record of API interactions.

Why do I see entries with no claim_id?

Some API calls may be system tests, authentication checks, or calls that failed before a claim was created. This is normal. Focus on entries with claim_id when troubleshooting specific claims.

What does "success = 1" mean exactly?

It means the API call completed without errors from UPS. The request was sent, UPS received it, and returned a successful response. This doesn't necessarily mean the claim was approved—just that the communication worked.

How can I tell if API credentials are wrong?

Look for authentication errors in error_message column, such as "Invalid bearer token", "Unauthorized", "Invalid client ID", etc. If you see these repeatedly, check Settings in UPS Claims page.

Should I check API logs regularly if everything seems to be working?

Not necessary for daily operations. Check logs when: (1) troubleshooting an issue, (2) after changing API settings, (3) monthly as a health check, or (4) if you notice claims acting strangely.

Change Log

2026-03-01

  • Initial documentation created
  • Complete technical reference for API logging system

End of Documentation

For additional help, contact your system administrator or Kiva Logic support.