> ## 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), a phone number (TNID), and a SIM card (ICCID) — all four are required. 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 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), a phone number (TNID), and a SIM card (ICCID) — all four are required. 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 - TNID - ICCID - 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. Required. example: NID-B5B67F02-708A-1851-20DF-61FC1919C4F6 ICCID: type: string description: SIM Card ICCID. Required. 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: text/plain: schema: $ref: '#/components/schemas/BadRequest_Result' application/json: schema: $ref: '#/components/schemas/BadRequest_Result' examples: example: value: StatusCode: 400 Message: >- Bad request: one or more required fields are missing or contain an invalid value. text/json: schema: $ref: '#/components/schemas/BadRequest_Result' '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/Unauthorized_Result' application/json: schema: $ref: '#/components/schemas/Unauthorized_Result' examples: example: value: StatusCode: 401 Message: >- Unauthorized: Bearer token is missing, expired, or invalid. Re-authenticate via POST /v1.0/oauth2/tokens. text/json: schema: $ref: '#/components/schemas/Unauthorized_Result' '403': description: Forbidden content: text/plain: schema: $ref: '#/components/schemas/Forbidden_Result' application/json: schema: $ref: '#/components/schemas/Forbidden_Result' examples: example: value: StatusCode: 403 Message: >- Forbidden: your token does not have permission to access this resource. Check the ApiEndpoint scope. text/json: schema: $ref: '#/components/schemas/Forbidden_Result' '404': description: Not Found content: text/plain: schema: $ref: '#/components/schemas/NotFound_Result' application/json: schema: $ref: '#/components/schemas/NotFound_Result' examples: example: value: StatusCode: 404 Message: >- Not found: the requested resource does not exist or belongs to a different account. text/json: schema: $ref: '#/components/schemas/NotFound_Result' '405': description: Method Not Allowed content: text/plain: schema: $ref: '#/components/schemas/MethodNotAllowed_Result' application/json: schema: $ref: '#/components/schemas/MethodNotAllowed_Result' examples: example: value: StatusCode: 405 Message: >- Method not allowed: verify the HTTP method required for this endpoint. text/json: schema: $ref: '#/components/schemas/MethodNotAllowed_Result' '408': description: Request Timeout content: text/plain: schema: $ref: '#/components/schemas/RequestTimeout_Result' application/json: schema: $ref: '#/components/schemas/RequestTimeout_Result' examples: example: value: StatusCode: 408 Message: >- Request timeout: the server did not receive a complete request within the allowed time. Retry with exponential backoff. text/json: schema: $ref: '#/components/schemas/RequestTimeout_Result' '429': description: Too Many Requests content: text/plain: schema: $ref: '#/components/schemas/TooManyRequests_Result' application/json: schema: $ref: '#/components/schemas/TooManyRequests_Result' examples: example: value: StatusCode: 429 Message: >- Too many requests: rate limit exceeded. Slow your request cadence and retry after a short delay. text/json: schema: $ref: '#/components/schemas/TooManyRequests_Result' '500': description: Server Error content: text/plain: schema: $ref: '#/components/schemas/InternalServerError_Result' application/json: schema: $ref: '#/components/schemas/InternalServerError_Result' examples: example: value: StatusCode: 500 Message: >- Internal server error: an unexpected error occurred. If the problem persists contact support@telegent.com. text/json: schema: $ref: '#/components/schemas/InternalServerError_Result' '503': description: Service Unavailable content: text/plain: schema: $ref: '#/components/schemas/ServiceUnavailable_Result' application/json: schema: $ref: '#/components/schemas/ServiceUnavailable_Result' examples: example: value: StatusCode: 503 Message: >- Service unavailable: the API is temporarily unavailable. Retry after a short delay. text/json: schema: $ref: '#/components/schemas/ServiceUnavailable_Result' '504': description: Gateway Timeout content: text/plain: schema: $ref: '#/components/schemas/GatewayTimeout_Result' application/json: schema: $ref: '#/components/schemas/GatewayTimeout_Result' examples: example: value: StatusCode: 504 Message: >- Gateway timeout: an upstream service did not respond in time. Retry with exponential backoff. text/json: schema: $ref: '#/components/schemas/GatewayTimeout_Result' 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 Message: type: string nullable: true additionalProperties: false Unauthorized_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false Forbidden_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false NotFound_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false MethodNotAllowed_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false RequestTimeout_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false TooManyRequests_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false InternalServerError_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false ServiceUnavailable_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false GatewayTimeout_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false ````