> ## Documentation Index > Fetch the complete documentation index at: https://docs.telegent.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Voice Route > Create a new voice route to define how inbound calls are handled for numbers assigned to it. Routes support SIP trunk termination, webhook-based IVR, forwarding, and workgroup distribution. Each route returns a unique CRID (Call Route ID) used when provisioning or updating numbers. Workgroups and Schedules can be attached to a route after creation to enable ring groups and business-hours routing. **What this does:** Returns the new route's `CallRouteId` (`CRID-`). Store this ID — it is required when provisioning numbers with voice enabled. Configure SIP trunk IPs, forwarding URLs, or workgroups after creation using the update endpoint. **Next steps:** - Assign the route to a number — `POST /v1.0/numbers/provision` - Add a workgroup — `POST /v1.0/workgroups` ## OpenAPI ````yaml /api-reference/openapi.json post /v1.0/voice/routes openapi: 3.0.3 info: title: mPaaS Core APIs version: 1.0.8 description: >- The Telegent mPaaS (Mobile Platform as a Service) API gives you full programmatic control over mobile phone numbers, messaging, voice routing, subscribers, and account management. Use these APIs to provision MVNO and IoT numbers, send and receive SMS/MMS, configure intelligent call routing, manage subscriber accounts, and apply AI Guardian controls. All requests require a Bearer token obtained from the Authentication endpoint. For support, visit https://support.telegent.com/support/home contact: name: Support email: support@telegent.com termsOfService: https://telegent.com/terms license: name: Use under LICX url: https://telegent.com/license servers: - url: https://api.telegent.com/v1.0 security: - BearerAuth: [] tags: - name: OAuth2 - name: AI Guardian - name: Accounts - name: Distributors - name: Message - name: Numbers - name: Voicemail - name: Packages - name: Products - name: Schedules - name: Services - name: Sims - name: Subscribers - name: Subscriptions - name: Voice - name: Workgroups paths: /v1.0/voice/routes: post: tags: - Voice summary: Create Voice Route description: >- Create a new voice route to define how inbound calls are handled for numbers assigned to it. Routes support SIP trunk termination, webhook-based IVR, forwarding, and workgroup distribution. Each route returns a unique CRID (Call Route ID) used when provisioning or updating numbers. Workgroups and Schedules can be attached to a route after creation to enable ring groups and business-hours routing. **What this does:** Returns the new route's `CallRouteId` (`CRID-`). Store this ID — it is required when provisioning numbers with voice enabled. Configure SIP trunk IPs, forwarding URLs, or workgroups after creation using the update endpoint. **Next steps:** - Assign the route to a number — `POST /v1.0/numbers/provision` - Add a workgroup — `POST /v1.0/workgroups` parameters: [] requestBody: required: true content: application/json: schema: type: object required: - RouteName - RouteType properties: RouteName: type: string description: Friendly name for voice route example: Main SIP Trunk RouteType: type: string enum: - Trunk - URL - Forward description: Type of voice routing example: Trunk VoiceUrl: type: string format: uri description: Webhook URL for voice events example: https://domain.com VoiceUrlMethod: type: string enum: - GET - POST description: HTTP method for voice URL example: POST VoiceAuthenticationType: type: string enum: - None - Basic - Bearer description: Authentication type VoiceUsername: type: string description: Username for auth example: admin VoicePasswordToken: type: string description: Password or token example: passwordORbearerToken CallbackVoiceUrl: type: string format: uri description: Callback URL example: https://apiendpoint.com CallbackVoiceUrlMethod: type: string enum: - GET - POST example: POST TrunkIp1: type: string description: Primary SIP trunk IP example: 20.87.87.87 TrunkIp2: type: string description: Secondary SIP trunk IP example: 20.87.87.86 TrunkPort1: type: string description: Primary trunk port example: '5061' TrunkPort2: type: string description: Secondary trunk port example: '5060' TrunkTransport1: type: string enum: - UDP - TCP - TLS description: Primary transport protocol example: UDP TrunkTransport2: type: string enum: - UDP - TCP - TLS description: Secondary transport protocol example: TCP TrunkUri1: type: string format: uri example: https://pstn.joonto.com TrunkUri2: type: string format: uri example: https://pstn2.joonto.com TrunkEnabled1: type: boolean description: Enable primary trunk example: true TrunkEnabled2: type: boolean description: Enable secondary trunk example: false Trunk1Priortiy: type: integer description: Priority for trunk 1 example: 10 Trunk1Weight: type: integer description: Weight for trunk 1 example: 10 Trunk2Priortiy: type: integer description: Priority for trunk 2 example: 20 Trunk2Weight: type: integer description: Weight for trunk 2 example: 20 HeaderManipulation: type: string description: Header manipulation ID example: HMI8802029 EnableSipRefer: type: boolean description: Enable SIP REFER example: true TransferCallerId: type: string description: Caller ID for transfers example: Transferee/Transferor SymmetricRtp: type: boolean description: Enable symmetric RTP example: true EnableTrpSecureTrunk: type: boolean description: Enable secure trunk example: true EnablePstnTransfer: type: boolean description: Enable PSTN transfer example: true IpWhitelist: type: array description: IP whitelist items: type: object properties: IpAddress: type: string example: 20.20.10.10 CnamLookup: type: boolean description: Enable CNAM lookup example: true TerminationUriSubdomain: type: string description: Termination URI subdomain example: client EnableCallStreaming: type: boolean description: Enable call streaming example: true WssUri: type: string format: uri description: WebSocket secure URI example: wss://192.67.88.2 RouteEnabled: type: boolean description: Enable/disable route example: true IntelligentRouteEnabled: type: boolean description: Enable intelligent routing features for this voice route example: true AccountId: type: string description: Account ID to associate with this voice route example: DID-1e8939ab-3f3c-4db1-89d7-956d80fd793j responses: '200': description: Success — returns the newly created Voice Route ID (CRID) content: application/json: schema: type: object examples: example: value: CallRouteId: CRID-509de94f-79cc-429b-a317-2102654dabbb AccountId: AID-ab12345-2725-45a1-bd5e-526ed19799xx RouteName: Main SIP Trunk RouteType: Trunk VoiceUrl: https://domain.com VoiceUrlMethod: POST TrunkIp1: 20.87.87.87 TrunkIp2: 20.87.87.86 TrunkPort1: '5061' TrunkPort2: '5060' TrunkTransport1: UDP TrunkTransport2: TCP TrunkUri1: https://pstn.joonto.com TrunkUri2: https://pstn2.joonto.com TrunkEnabled1: true TrunkEnabled2: false Trunk1Priortiy: 10 Trunk1Weight: 10 Trunk2Priortiy: 20 Trunk2Weight: 20 HeaderManipulation: HMI8802029 EnableSipRefer: true TransferCallerId: Transferee/Transferor SymmetricRtp: true EnableTrpSecureTrunk: true EnablePstnTransfer: true CnamLookup: true TerminationUriSubdomain: client EnableCallStreaming: true WssUri: wss://192.67.88.2 IntelligentRouteEnabled: true RouteEnabled: true IpWhiteList: [] '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest_Result' example: StatusCode: 400 Message: >- Bad request: one or more required fields are missing or contain an invalid value. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized_Result' example: StatusCode: 401 Message: >- Unauthorized: Bearer token is missing, expired, or invalid. Re-authenticate via POST /v1.0/oauth2/tokens. '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Forbidden_Result' example: StatusCode: 403 Message: >- Forbidden: your token does not have permission to access this resource. Check the ApiEndpoint scope. '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound_Result' example: StatusCode: 404 Message: >- Not found: the requested resource does not exist or belongs to a different account. '405': description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed_Result' example: StatusCode: 405 Message: >- Method not allowed: verify the HTTP method required for this endpoint. '408': description: Request Timeout content: application/json: schema: $ref: '#/components/schemas/RequestTimeout_Result' example: StatusCode: 408 Message: >- Request timeout: the server did not receive a complete request within the allowed time. Retry with exponential backoff. '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/TooManyRequests_Result' example: StatusCode: 429 Message: >- Too many requests: rate limit exceeded. Slow your request cadence and retry after a short delay. '500': description: Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerError_Result' example: StatusCode: 500 Message: >- Internal server error: an unexpected error occurred. If the problem persists contact support@telegent.com. '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailable_Result' example: StatusCode: 503 Message: >- Service unavailable: the API is temporarily unavailable. Retry after a short delay. '504': description: Gateway Timeout content: application/json: schema: $ref: '#/components/schemas/GatewayTimeout_Result' example: StatusCode: 504 Message: >- Gateway timeout: an upstream service did not respond in time. Retry with exponential backoff. x-codeSamples: - lang: JSON source: |- { "RouteName": "Main SIP Trunk", "RouteType": "Trunk", "VoiceUrl": "https://domain.com", "VoiceUrlMethod": "POST", "VoiceAuthenticationType": "Basic", "VoiceUsername": "admin", "VoicePasswordToken": "passwordORbearerToken", "CallbackVoiceUrl": "https://apiendpoint.com", "CallbackVoiceUrlMethod": "POST", "TrunkIp1": "20.87.87.87", "TrunkIp2": "20.87.87.86", "TrunkPort1": "5061", "TrunkPort2": "5060", "TrunkTransport1": "UDP", "TrunkTransport2": "TCP", "TrunkUri1": "https://pstn.joonto.com", "TrunkUri2": "https://pstn2.joonto.com", "TrunkEnabled1": true, "TrunkEnabled2": false, "Trunk1Priortiy": 10, "Trunk1Weight": 10, "Trunk2Priortiy": 20, "Trunk2Weight": 20, "HeaderManipulation": "HMI8802029", "EnableSipRefer": true, "TransferCallerId": "Transferee/Transferor", "SymmetricRtp": true, "EnableTrpSecureTrunk": true, "EnablePstnTransfer": true, "IpWhitelist": [{"IpAddress": "20.20.10.10"}, {"IpAddress": "20.20.10.20"}], "CnamLookup": true, "TerminationUriSubdomain": "client", "EnableCallStreaming": true, "WssUri": "wss://192.67.88.2", "IntelligentRouteEnabled": true, "RouteEnabled": true } - lang: cURL source: |- curl -X POST https://api.telegent.com/v1.0/voice/routes \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "RouteName": "Main SIP Trunk", "RouteType": "Trunk", "VoiceUrl": "https://domain.com", "VoiceUrlMethod": "POST", "TrunkIp1": "20.87.87.87", "TrunkPort1": "5061", "TrunkTransport1": "UDP", "RouteEnabled": true }' components: schemas: BadRequest_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 example: 400 Message: type: string nullable: true example: >- Bad request: one or more required fields are missing or contain an invalid value. additionalProperties: false example: StatusCode: 400 Message: >- Bad request: one or more required fields are missing or contain an invalid value. Unauthorized_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 example: 401 Message: type: string nullable: true example: 'Unauthorized: Bearer token is missing, expired, or invalid.' additionalProperties: false example: StatusCode: 401 Message: 'Unauthorized: Bearer token is missing, expired, or invalid.' Forbidden_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 example: 403 Message: type: string nullable: true example: >- Forbidden: your token does not have permission to access this resource. additionalProperties: false example: StatusCode: 403 Message: >- Forbidden: your token does not have permission to access this resource. NotFound_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 example: 404 Message: type: string nullable: true example: >- Not found: the requested resource does not exist or belongs to a different account. additionalProperties: false example: StatusCode: 404 Message: >- Not found: the requested resource does not exist or belongs to a different account. MethodNotAllowed_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 example: 405 Message: type: string nullable: true example: >- Method not allowed: verify the HTTP method required for this endpoint. additionalProperties: false example: StatusCode: 405 Message: 'Method not allowed: verify the HTTP method required for this endpoint.' RequestTimeout_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 example: 408 Message: type: string nullable: true example: >- Request timeout: the server did not receive a complete request in time. additionalProperties: false example: StatusCode: 408 Message: >- Request timeout: the server did not receive a complete request in time. TooManyRequests_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 example: 429 Message: type: string nullable: true example: >- Too many requests: rate limit exceeded. Slow your request cadence and retry. additionalProperties: false example: StatusCode: 429 Message: >- Too many requests: rate limit exceeded. Slow your request cadence and retry. InternalServerError_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 example: 500 Message: type: string nullable: true example: 'Internal server error: an unexpected error occurred.' additionalProperties: false example: StatusCode: 500 Message: 'Internal server error: an unexpected error occurred.' ServiceUnavailable_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 example: 503 Message: type: string nullable: true example: 'Service unavailable: the API is temporarily unavailable.' additionalProperties: false example: StatusCode: 503 Message: 'Service unavailable: the API is temporarily unavailable.' GatewayTimeout_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 example: 504 Message: type: string nullable: true example: 'Gateway timeout: an upstream service did not respond in time.' additionalProperties: false example: StatusCode: 504 Message: 'Gateway timeout: an upstream service did not respond in time.' ````