Teal API Reference & Troubleshooting Guide

This article consolidates key documentation to assist support agents with using the Teal Communications API, including terminology, access instructions, endpoints, error codes, and service levels.

Dictionary of Key Terms

• eID – Unique serial number of an eSIM.
• IMSI – International Mobile Subscriber Identity.
• ICCID – Integrated Circuit Card Identifier for SIM profiles.
• MSISDN – Mapped phone number to the SIM (not profile-specific).
• MCC MNC – Mobile Country Code + Mobile Network Code.
• PMN – TADIG code identifying GSM operators.
• CDR – Charging Data Record for billing and usage tracking.
• Polling – Device heartbeat to verify connectivity (~every 5 mins).
• Bootstrap Profile – Default global profile installed on eSIM.
• Plan – Configuration set assigned to an eSIM (rate, data, etc.).

API Access & Integration

Teal’s API allows external systems to manage eSIMs, monitor usage, and automate SIM lifecycle events. All API definitions are available via Swagger:

Teal API Swagger Documentation

Request Requirements

• requestId – Required unique UUID for each operation.
• callbackUrl – Required URL to receive post-operation status.

Common Tasks

• Activate eSIM: /api/v1/esims/activate
• Assign Plan: /api/v1/esims/assign-plan
• Disable/Enable Data: /api/v1/esims/disable / /enable
• Change Device Name/Group: /change-device-name, /change-device-group-name
• Monitor Usage: /api/v1/data-consumption

Error Codes & Troubleshooting

Below are common API error responses and suggested actions:

• GENERIC_ERROR – Retry or contact support if persistent.
• UNAUTHORIZED – Verify API keys and account scope.
• ESIM_NOT_FOUND – Validate eID or confirm with Teal support.
• VALIDATION_ERROR – Check required parameters like date, UUID, etc.
• FLOW_RESTRICTED_ERROR – Profile operations restricted by policy.

API Service Levels

• Rate Limit: 1000 calls per minute
• Average Response Time: < 2 seconds
• Max Operation Completion: 15 minutes
• SMS Callbacks: Wait at least 15 seconds before polling results.

Additional Notes

• For enable/disable batch operations, max 250 eIDs per request is recommended.
• Non-alphanumeric characters are stripped from requestId values automatically.

For assistance, please contact support@tealcommunications.com.