> ## 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 Subscription > **Prerequisites:** - **Required:** Bearer token — `POST /v1.0/oauth2/tokens` - **Required:** Package ID (PID) — `POST /v1.0/packages` - **Required:** Subscriber ID (TSUID) — `POST /v1.0/subscribers/create` --- Link a subscriber to a package to grant them access to a set of services. A subscription ties together a subscriber (TSUID), a package (PID), and optionally a phone number (TNID) and SIM card (ICCID). The subscriber, package, and phone number must all exist before creating the subscription. Active subscriptions determine what services and capabilities are available to the subscriber. **What this does:** Returns the new `SubscriptionId` (`SUB-`) and full subscription record. Creating a subscription links the subscriber to a package, granting them the services and capabilities defined in that package. **Next steps:** - Confirm the subscription — `GET /v1.0/subscriptions` - View the package contents — `GET /v1.0/packages/items` ## OpenAPI ````yaml /api-reference/openapi.json post /v1.0/subscriptions 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/subscriptions: post: tags: - Subscriptions summary: Create Subscription description: >- **Prerequisites:** - **Required:** Bearer token — `POST /v1.0/oauth2/tokens` - **Required:** Package ID (PID) — `POST /v1.0/packages` - **Required:** Subscriber ID (TSUID) — `POST /v1.0/subscribers/create` --- Link a subscriber to a package to grant them access to a set of services. A subscription ties together a subscriber (TSUID), a package (PID), and optionally a phone number (TNID) and SIM card (ICCID). The subscriber, package, and phone number must all exist before creating the subscription. Active subscriptions determine what services and capabilities are available to the subscriber. **What this does:** Returns the new `SubscriptionId` (`SUB-`) and full subscription record. Creating a subscription links the subscriber to a package, granting them the services and capabilities defined in that package. **Next steps:** - Confirm the subscription — `GET /v1.0/subscriptions` - View the package contents — `GET /v1.0/packages/items` parameters: - name: SubscriptionId in: query required: false schema: type: string description: '' requestBody: required: true content: application/json: schema: type: object required: - SubscriberId - PackageId - Type properties: SubscriberId: type: string description: >- Telegent Subscriber ID. Format: `TSUID-` followed by a UUID. Create one via `POST /v1.0/subscribers/create` or look up existing IDs with `GET /v1.0/subscribers/get`. example: TSUID-d7b3-4696-bdd9-5b407d9e99ee-3985-444b8d TNID: type: string description: Telephone Number ID example: NID-B5B67F02-708A-1851-20DF-61FC1919C4F6 ICCID: type: string description: SIM Card ICCID example: '8901240397190002080' PackageId: type: string description: Package ID to subscribe to example: PID-9a8435dc-ca6e-4a98-b761-5e6dc04447db Type: type: string description: Subscription type example: mvno responses: '200': description: >- Success — returns the new Subscription ID (SUB-) and associated details content: application/json: schema: type: object examples: example: value: SubscriptionId: SUB-ef84c0b5-d750-4a5a-99b1-4705089cd20c SubscriberId: TSUID-d7b3-4696-bdd9-5b407d9e99ee-3985-444b8d TNID: NID-B5B67F02-708A-1851-20DF-61FC1919C4F6 ICCID: '8901240397190002080' PackageId: PID-9a8435dc-ca6e-4a98-b761-5e6dc04447db Type: mvno Active: true '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: |- { "SubscriberId": "SID-d7b3-4696-bdd9-5b407d9e99ee-3985-444b8d", "TNID": "NID-B5B67F02-708A-1851-20DF-61FC1919C4F6", "ICCID": "8901240397190002080", "PackageId": "PID-9a8435dc-ca6e-4a98-b761-5e6dc04447db", "Type": "mvno" } - lang: cURL source: |- curl -X POST https://api.telegent.com/v1.0/subscriptions \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "SubscriberId": "SID-d7b3-4696-bdd9-5b407d9e99ee-3985-444b8d", "TNID": "NID-B5B67F02-708A-1851-20DF-61FC1919C4F6", "ICCID": "8901240397190002080", "PackageId": "PID-9a8435dc-ca6e-4a98-b761-5e6dc04447db", "Type": "mvno" }' 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.' ````