{ "openapi": "3.1.0", "info": { "title": "Gigs Core API", "description": "API to manage voice & data plans for smartphones, wearables and IoT in 200+ countries.", "contact": { "name": "Gigs Support", "email": "support@gigs.com" }, "version": "2026-01-29.323" }, "servers": [ { "url": "https://api.gigs.com", "description": "production" } ], "paths": { "/projects/{project}/addons": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Add-ons" ], "operationId": "AddonsList", "summary": "List all add-ons", "description": "List add-ons. By default only add-ons with a status of 'available' are returned.", "parameters": [ { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "coverageCountry", "in": "query", "description": "The ISO3166 alpha-2 country code to filter the add-ons by.", "schema": { "type": "array", "items": { "type": "string", "examples": [ "DE" ] } }, "style": "form", "explode": false }, { "name": "provider", "in": "query", "description": "The provider of the add-on to be filtered by.", "schema": { "type": "string", "examples": [ "p4" ] } }, { "name": "plan", "in": "query", "description": "Limit the list of add-ons to those compatible with the given plan id.", "schema": { "type": "string", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] } }, { "name": "status", "in": "query", "description": "The status of the add-on to be filtered by.", "schema": { "type": "string", "examples": [ "available" ] } }, { "name": "type", "in": "query", "description": "The type of the add-on to be filtered by.", "schema": { "type": "string", "examples": [ "topUp" ] } }, { "name": "recurrenceType", "in": "query", "description": "The recurrence type of the add-on to be filtered by.", "schema": { "type": "string", "examples": [ "oneTime" ] } } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of add-ons.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `addon`.", "items": { "$ref": "#/components/schemas/addon" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7, "totalPeriods": 1 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" } } } }, "/projects/{project}/addons/{addon}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "$ref": "#/components/parameters/addon" } ], "get": { "tags": [ "Add-ons" ], "operationId": "AddonsRetrieve", "summary": "Retrieve an add-on", "description": "Retrieves the details of an existing add-on.", "responses": { "200": { "description": "Returns the add-on object if it exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addon" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7, "totalPeriods": 1 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" } } }, "patch": { "tags": [ "Add-ons" ], "operationId": "AddonsUpdate", "summary": "Update an add-on", "description": "Updates an add-on's name and description.", "requestBody": { "description": "Add-on attributes to update.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The name of the add-on, meant to be displayable to users.", "examples": [ "1GB Data Top-up" ] }, "description": { "type": [ "string", "null" ], "description": "The description of the add-on.", "examples": [ "Disable international roaming." ] }, "validity": { "type": [ "object", "null" ], "description": "The custom validity for this add-on. Set to `null` to remove custom validity and fall back to network add-on validity.\n If provided, must not exceed the network add-on's validity period.", "properties": { "unit": { "type": "string", "enum": [ "day", "month" ], "description": "The time unit, either `day` or `month`.", "examples": [ "day" ] }, "value": { "type": "integer", "description": "The amount of units.", "minimum": 1, "examples": [ 7 ] }, "totalPeriods": { "type": "integer", "description": "How many times the validity period repeats. The total lifetime (`value` times `unit` times `totalPeriods`) must not exceed 10 years.", "maximum": 3652, "minimum": 1, "examples": [ 1 ] } }, "required": [ "unit", "value" ] }, "metadata": { "$ref": "#/components/schemas/metadataUpdate" } }, "required": [] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "name": "1GB Data Top-up", "description": "Disable international roaming.", "validity": { "unit": "day", "value": 7, "totalPeriods": 1 }, "metadata": {} } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": true }, "responses": { "200": { "description": "Returns the updated add-on.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addon" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7, "totalPeriods": 1 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/addons/{addon}/archive": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "$ref": "#/components/parameters/addon" } ], "post": { "tags": [ "Add-ons" ], "operationId": "AddonsArchive", "summary": "Archive an add-on", "description": "Set the status of an add-on to archived. An archived add-on can not be added to subscriptions.", "responses": { "200": { "description": "Returns the archived add-on.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addon" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7, "totalPeriods": 1 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/addons/{addon}/publish": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "$ref": "#/components/parameters/addon" } ], "post": { "tags": [ "Add-ons" ], "operationId": "AddonsPublish", "summary": "Publish an add-on", "description": "Set the status of an add-on to available. Available add-ons can be added to subscriptions.", "responses": { "200": { "description": "Returns the available add-on.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addon" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7, "totalPeriods": 1 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/consentRequests": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Consent Requests" ], "operationId": "ConsentRequestsList", "summary": "List all consent requests", "description": "Returns a list of consent requests. The consent requests returned are sorted by creation date, with the most recently created consent requests appearing first.", "parameters": [ { "name": "subject", "in": "query", "description": "The unique identifier for the subject related to the consent request.", "schema": { "type": "string", "examples": [ "pto_0SNlurA049MEWV4DWEaT4SaeDI8s" ] } }, { "name": "subscription", "in": "query", "description": "The unique identifier for the subscription related to the consent request.", "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, { "name": "status", "in": "query", "description": "A comma-separated list of statuses to filter the consent requests by.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "approved", "bypassed", "canceled", "expired", "pending" ] } }, "style": "form", "explode": false }, { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a list of consentRequest objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `consentRequest`.", "items": { "$ref": "#/components/schemas/consentRequest" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "consentRequest", "id": "crq_0SNlurA049MEWV2jN9EvAfKMf7VU", "createdAt": "2024-01-09T15:00:51Z", "deliveryMethod": "emailLink", "expiredAt": "2024-01-09T15:00:51Z", "operation": "exchange.sim", "status": "pending", "subject": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "consentRequest", "id": "crq_0SNlurA049MEWV2jN9EvAfKMf7VU", "createdAt": "2024-01-09T15:00:51Z", "deliveryMethod": "emailLink", "expiredAt": "2024-01-09T15:00:51Z", "operation": "exchange.sim", "status": "pending", "subject": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } }, "post": { "tags": [ "Consent Requests" ], "operationId": "ConsentRequestsCreate", "summary": "Create a consent request", "description": "Creates a new consent request from an existing one, delivering a new code to the user.\nThe existing consent request must be pending or\nexpired and must be the most recent one for its resource.\nA pending one expires as soon as the new one is created.\n", "requestBody": { "description": "The consent request to create the new one from.", "content": { "application/json": { "schema": { "type": "object", "title": "ConsentRequestCreate", "properties": { "fromConsentRequest": { "type": "string", "description": "The unique identifier for the existing consent request to recreate, e.g. when the user missed the original code. The new consent request covers the same operation and resource and carries a newly generated code. The referenced consent request must be `pending` or `expired` and must be the most recent one for its resource. A `pending` one expires as soon as the new one is created.", "examples": [ "crq_0SNlurA049MEWV2jN9EvAfKMf7VU" ] } }, "required": [ "fromConsentRequest" ] }, "examples": { "Example": { "summary": "Example", "value": { "fromConsentRequest": "crq_0SNlurA049MEWV2jN9EvAfKMf7VU" } } } } }, "required": true }, "responses": { "201": { "description": "Returns the created consent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/consentRequest" }, "examples": { "Example": { "summary": "Example", "value": { "object": "consentRequest", "id": "crq_0SNlurA049MEWV2jN9EvAfKMf7VU", "createdAt": "2024-01-09T15:00:51Z", "deliveryMethod": "emailLink", "expiredAt": "2024-01-09T15:00:51Z", "operation": "exchange.sim", "status": "pending", "subject": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/consentRequests/{consentRequest}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "consentRequest", "in": "path", "description": "The unique identifier of the consent request.", "required": true, "schema": { "type": "string", "examples": [ "crq_0SNlurA049MEWV2jN9EvAfKMf7VU" ] } } ], "get": { "tags": [ "Consent Requests" ], "operationId": "ConsentRequestsRetrieve", "summary": "Retrieve a consent request", "description": "Retrieves a consent request by the given id.\n", "responses": { "200": { "description": "Returns the consent request if it exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/consentRequest" }, "examples": { "Example": { "summary": "Example", "value": { "object": "consentRequest", "id": "crq_0SNlurA049MEWV2jN9EvAfKMf7VU", "createdAt": "2024-01-09T15:00:51Z", "deliveryMethod": "emailLink", "expiredAt": "2024-01-09T15:00:51Z", "operation": "exchange.sim", "status": "pending", "subject": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" } } } }, "/projects/{project}/consentRequests/{consentRequest}/approve": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "consentRequest", "in": "path", "description": "The unique identifier of the consent request.", "required": true, "schema": { "type": "string", "examples": [ "crq_0SNlurA049MEWV2jN9EvAfKMf7VU" ] } } ], "post": { "tags": [ "Consent Requests" ], "operationId": "ConsentRequestsApprove", "summary": "Approves the consent request", "description": "Grants consent for the given request. This will trigger the consent\nrequest to be processed and the request to transition to the\napproved status. The consent request must be\nin the pending status in order to be approved.\n", "requestBody": { "description": "The credentials required to approve the consent request.", "content": { "application/json": { "schema": { "type": "object", "title": "ConsentRequestApprove", "properties": { "code": { "type": "string", "description": "The OTP associated with the consent request, used to validate the given consent.", "examples": [ "123456" ] } }, "required": [ "code" ] }, "examples": { "Example": { "summary": "Example", "value": { "code": "123456" } } } } }, "required": true }, "responses": { "200": { "description": "Returns the consent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/consentRequest" }, "examples": { "Example": { "summary": "Example", "value": { "object": "consentRequest", "id": "crq_0SNlurA049MEWV2jN9EvAfKMf7VU", "createdAt": "2024-01-09T15:00:51Z", "deliveryMethod": "emailLink", "expiredAt": "2024-01-09T15:00:51Z", "operation": "exchange.sim", "status": "pending", "subject": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/devices": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Devices" ], "operationId": "DevicesList", "summary": "List all devices", "description": "Returns a list of devices. The devices returned are sorted by creation date, with the most recently created devices appearing first.", "parameters": [ { "name": "sim", "in": "query", "description": "The unique identifier for the sim to be filtered by.", "schema": { "type": "string", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] } }, { "name": "user", "in": "query", "description": "The unique identifier for the user to be filtered by.", "schema": { "type": "string", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of devices.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `device`.", "items": { "$ref": "#/components/schemas/device" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "device", "id": "dev_0SNlurA049MEWV55CrA9qMvI2FVJ", "metadata": {}, "createdAt": "2021-02-14T19:38:34Z", "imei": "492388841798923", "model": { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" }, "name": "Anna's iPhone 12 Pro", "sims": [ { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } ], "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "device", "id": "dev_0SNlurA049MEWV55CrA9qMvI2FVJ", "metadata": {}, "createdAt": "2021-02-14T19:38:34Z", "imei": "492388841798923", "model": { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" }, "name": "Anna's iPhone 12 Pro", "sims": [ { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } ], "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } }, "post": { "tags": [ "Devices" ], "operationId": "DevicesCreate", "summary": "Create a device", "description": "Creates a new device with the given parameters.", "requestBody": { "description": "Device attributes to create. You must specify either an IMEI or a user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "imei": { "type": "string", "pattern": "^[0-9]{15,16}$", "description": "The IMEI (international mobile equipment identity) of the device.", "examples": [ "492388841798923" ] }, "user": { "type": [ "string", "null" ], "description": "Unique user identifier for the device owner.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] }, "sims": { "type": [ "array", "null" ], "description": "List of identifiers for all SIMs to attach to the device.", "items": { "type": "string", "description": "Unique SIM identifier.", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] } }, "name": { "type": [ "string", "null" ], "description": "An optional custom name for the device.", "examples": [ "Anna's iPhone 12 Pro" ] }, "metadata": { "$ref": "#/components/schemas/metadataUpdate" } }, "required": [ "imei" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "imei": "492388841798923", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "sims": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ], "name": "Anna's iPhone 12 Pro", "metadata": {} } }, "Example - Required": { "summary": "Example - Required", "value": { "imei": "492388841798923" } } } } }, "required": true }, "responses": { "201": { "description": "Returns the created device.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device" }, "examples": { "Example": { "summary": "Example", "value": { "object": "device", "id": "dev_0SNlurA049MEWV55CrA9qMvI2FVJ", "metadata": {}, "createdAt": "2021-02-14T19:38:34Z", "imei": "492388841798923", "model": { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" }, "name": "Anna's iPhone 12 Pro", "sims": [ { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } ], "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/devices/{device}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "device", "in": "path", "description": "The unique identifier for the device.", "required": true, "schema": { "type": "string", "examples": [ "dev_0SNlurA049MEWV55CrA9qMvI2FVJ" ] } } ], "get": { "tags": [ "Devices" ], "operationId": "DevicesRetrieve", "summary": "Retrieve a device", "description": "Retrieves the details of an existing device owned by the authenticated user.", "responses": { "200": { "description": "Returns the device object if it exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device" }, "examples": { "Example": { "summary": "Example", "value": { "object": "device", "id": "dev_0SNlurA049MEWV55CrA9qMvI2FVJ", "metadata": {}, "createdAt": "2021-02-14T19:38:34Z", "imei": "492388841798923", "model": { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" }, "name": "Anna's iPhone 12 Pro", "sims": [ { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } ], "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } }, "delete": { "tags": [ "Devices" ], "operationId": "DevicesDelete", "summary": "Delete a device", "description": "Retrieves the details of an existing device and deletes it.", "responses": { "200": { "description": "Returns the device after a successful deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device" }, "examples": { "Example": { "summary": "Example", "value": { "object": "device", "id": "dev_0SNlurA049MEWV55CrA9qMvI2FVJ", "metadata": {}, "createdAt": "2021-02-14T19:38:34Z", "imei": "492388841798923", "model": { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" }, "name": "Anna's iPhone 12 Pro", "sims": [ { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } ], "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } }, "patch": { "tags": [ "Devices" ], "operationId": "DevicesUpdate", "summary": "Update a device", "description": "Updates the given properties of an existing device.", "requestBody": { "description": "The device properties to update, at least one of them must be provided. Use null or an empty array to remove existing values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "An optional custom name for the device.", "examples": [ "Anna's iPhone 12 Pro" ] }, "metadata": { "$ref": "#/components/schemas/metadataUpdate" }, "sims": { "type": "array", "description": "List of identifiers for all SIMs currently attached to the device.", "items": { "type": "string", "description": "Unique SIM identifier.", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] } }, "user": { "type": [ "string", "null" ], "description": "Unique user identifier for the device owner.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } } }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "name": "Anna's iPhone 12 Pro", "metadata": {}, "sims": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ], "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": true }, "responses": { "200": { "description": "Returns the updated device object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/device" }, "examples": { "Example": { "summary": "Example", "value": { "object": "device", "id": "dev_0SNlurA049MEWV55CrA9qMvI2FVJ", "metadata": {}, "createdAt": "2021-02-14T19:38:34Z", "imei": "492388841798923", "model": { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" }, "name": "Anna's iPhone 12 Pro", "sims": [ { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } ], "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/devices/search": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "post": { "tags": [ "Devices" ], "operationId": "DevicesSearch", "summary": "Search for devices", "description": "Searches for existing devices matching the given parameters. The search will only return factory devices not yet assigned to any user, or devices already owned by the current user.", "requestBody": { "description": "Device attributes to search for.", "content": { "application/json": { "schema": { "type": "object", "properties": { "imei": { "type": "string", "pattern": "^[0-9]{15,16}$", "description": "The IMEI (international mobile equipment identity) of the device.", "examples": [ "492388841798923" ] } }, "required": [ "imei" ] }, "examples": { "Example": { "summary": "Example", "value": { "imei": "492388841798923" } } } } }, "required": true }, "responses": { "200": { "description": "Returns a list schema response with all found devices.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `device`.", "items": { "$ref": "#/components/schemas/device" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "device", "id": "dev_0SNlurA049MEWV55CrA9qMvI2FVJ", "metadata": {}, "createdAt": "2021-02-14T19:38:34Z", "imei": "492388841798923", "model": { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" }, "name": "Anna's iPhone 12 Pro", "sims": [ { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } ], "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "device", "id": "dev_0SNlurA049MEWV55CrA9qMvI2FVJ", "metadata": {}, "createdAt": "2021-02-14T19:38:34Z", "imei": "492388841798923", "model": { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" }, "name": "Anna's iPhone 12 Pro", "sims": [ { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } ], "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/deviceModelBrands": { "get": { "tags": [ "Devices" ], "operationId": "DeviceModelBrandsList", "summary": "List all device model brands", "description": "Returns a list of device model brands. The device model brands returned are sorted alphabetically.", "responses": { "200": { "description": "Returns a list of device model brands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceModelBrands" }, "examples": { "Example": { "summary": "Example", "value": { "object": "deviceModelBrands", "items": [ "Apple" ] } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } } }, "/deviceModels/{deviceModel}": { "parameters": [ { "name": "deviceModel", "in": "path", "description": "The unique identifier for the device model.", "required": true, "schema": { "type": "string", "examples": [ "dmd_0SNlurA04OUskUGfGAn3Rh" ] } } ], "get": { "tags": [ "Devices" ], "operationId": "DeviceModelsRetrieve", "summary": "Retrieve a device model", "description": "Retrieves the details of an existing device model.", "responses": { "200": { "description": "Returns the device model object if it exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deviceModel" }, "examples": { "Example": { "summary": "Example", "value": { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } } }, "/deviceModels/search": { "post": { "tags": [ "Devices" ], "operationId": "DeviceModelsSearch", "summary": "Search for device models", "description": "Searches for existing devices models matching the given parameters.", "requestBody": { "description": "Device model attributes to search for.", "content": { "application/json": { "schema": { "type": "object", "properties": { "imei": { "type": "string", "pattern": "^[0-9]{15,16}$", "description": "The IMEI (international mobile equipment identity) of the corresponding device.", "examples": [ "492388841798923" ] } }, "required": [ "imei" ] }, "examples": { "Example": { "summary": "Example", "value": { "imei": "492388841798923" } } } } }, "required": true }, "responses": { "200": { "description": "Returns a list schema response with all found device models.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `deviceModel`.", "items": { "$ref": "#/components/schemas/deviceModel" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/deviceModels": { "get": { "tags": [ "Devices" ], "operationId": "DeviceModelsList", "summary": "List all device models", "description": "Returns a list of device models. The models returned are sorted by creation date, with the most recently created models appearing first.", "parameters": [ { "name": "type", "in": "query", "description": "A comma-separated list of types to be filtered by.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "car", "iot", "laptop", "router", "smartphone", "feature-phone", "smartwatch", "tablet", "wearable", "other" ] }, "examples": [ "smartphone,tablet" ] }, "style": "form", "explode": false }, { "name": "brand", "in": "query", "description": "A comma-separated list of brands to be filtered by. To include a literal comma in a value, double-encode it as `%252C`.", "schema": { "type": "array", "items": { "type": "string" }, "examples": [ "Apple,Samsung" ] }, "style": "form", "explode": false }, { "name": "simType", "in": "query", "description": "A comma-separated list of SIM types to be filtered by.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "eSIM", "pSIM" ] }, "examples": [ "eSIM,pSIM" ] }, "style": "form", "explode": false }, { "name": "hardwareIdentifier", "in": "query", "description": "A comma-separated list of hardware identifiers (e.g. the Android `Build.MODEL` string) to filter device models by. To include a literal comma in a value, double-encode it as `%252C`.", "schema": { "type": "array", "items": { "type": "string" }, "examples": [ "SM-S928U1,SM-S928U2" ] }, "style": "form", "explode": false }, { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of device models.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `deviceModel`.", "items": { "$ref": "#/components/schemas/deviceModel" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "deviceModel", "id": "dmd_0SNlurA04OUskUGfGAn3Rh", "brand": "Apple", "hardwareIdentifiers": [ "SM-S928U1" ], "name": "iPhone 12 Pro", "simTypes": [ "eSIM", "pSIM" ], "type": "smartphone" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/sims/{sim}/eSimProfile": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "sim", "in": "path", "description": "The unique identifier for the SIM.", "required": true, "schema": { "type": "string", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] } } ], "get": { "tags": [ "SIMs" ], "operationId": "EsimProfilesRetrieve", "summary": "Retrieve an eSIM profile", "description": "Retrieves the details of an existing eSIM profile for a given SIM.\n\nA 404 response will be returned if the SIM does not exist, or is a pSIM.\n\nNote that for providers other than `p3`, `p14` or `p15` the `status` of\nthe profile will currently always be `unknown`.\n\nRelated guide: [eSIM profile lifecycle](https://developers.gigs.com/docs/core/sims#e-sim-profile-lifecycle)\n", "responses": { "200": { "description": "Returns the eSimProfile if it exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/eSimProfile" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "eSimProfile", "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "deleted", "updatedAt": "2024-03-13T15:36:01Z" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "eSimProfile", "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "deleted", "updatedAt": "2024-03-13T15:36:01Z" } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } } }, "/projects/{project}/networkAvailability/lookup": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "post": { "tags": [ "Network Availabilities" ], "operationId": "NetworkAvailabilitiesLookup", "summary": "Lookup network availability by location", "description": "Looks up network availability information based on geographic coordinates (latitude/longitude) or address. Returns network availability data only for US locations.\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "requestBody": { "description": "Location to lookup availability for. Provide either `coordinates` or `address`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "object", "title": "NetworkAvailabilityAddress", "description": "The address for which availability information is provided.\n\n\n> #### Preview\n>\n> This schema is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "properties": { "city": { "type": "string", "description": "The city/municipality of the address.", "examples": [ "New York City" ] }, "country": { "type": "string", "description": "The ISO 3166-1 alpha-2 country code of the address.", "examples": [ "US" ] }, "line1": { "type": "string", "description": "The first line of the address, e.g. street and house number.", "examples": [ "129 West 81st Street" ] }, "line2": { "type": [ "string", "null" ], "description": "The second line of the address, e.g. apartment number.", "examples": [ "Apartment 5" ] }, "postalCode": { "type": [ "string", "null" ], "description": "The postal code of the address.", "examples": [ "10024" ] }, "state": { "type": [ "string", "null" ], "description": "The state/province/region of the address.", "examples": [ "NY" ] } }, "required": [ "city", "country", "line1" ] }, "coordinates": { "type": "object", "title": "NetworkAvailabilityCoordinates", "description": "The coordinates for which availability information is provided.\n\n\n> #### Preview\n>\n> This schema is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "properties": { "latitude": { "type": "number", "description": "The latitude coordinate for which availability information is provided.", "maximum": 90, "minimum": -90, "examples": [ 40.7831 ] }, "longitude": { "type": "number", "description": "The longitude coordinate for which availability information is provided.", "maximum": 180, "minimum": -180, "examples": [ -73.9712 ] } }, "required": [ "latitude", "longitude" ] } } }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "coordinates": { "latitude": 40.7831, "longitude": -73.9712 } } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": false }, "responses": { "200": { "description": "Returns the network availability data with location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/networkAvailability" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "networkAvailability", "availability": [ { "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "provider": "p11", "technologies": { "4G": { "strength": "good", "minDecibelMilliwatts": -90.0 }, "5G": { "strength": "fair", "minDecibelMilliwatts": -100.0 } } } ], "location": { "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "coordinates": { "latitude": 40.7831, "longitude": -73.9712 } } } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "networkAvailability", "availability": [ { "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "provider": "p11", "technologies": { "4G": { "strength": "good", "minDecibelMilliwatts": -90.0 }, "5G": { "strength": "fair", "minDecibelMilliwatts": -100.0 } } } ], "location": {} } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/networkAvailabilityTilesets": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Network Availabilities" ], "operationId": "NetworkAvailabilityTilesetsList", "summary": "List all coverage map tilesets", "description": "Returns the tilesets needed to render a coverage map, based on the project's available plans.\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "parameters": [ { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "plan", "in": "query", "description": "Returns the tileset for a specific plan, if available.", "schema": { "type": "string", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] } } ], "responses": { "200": { "description": "Returns a list of network availability tilesets.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `networkAvailabilityTileset`.", "items": { "$ref": "#/components/schemas/networkAvailabilityTileset" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "networkAvailabilityTileset", "expiresAt": "2026-08-04T12:00:00Z", "layers": [ { "technology": "5G", "sourceLayer": "coverage_5g" } ], "maxZoom": 10, "minZoom": 0, "urlTemplate": "https://tiles.gigs.com/tiles/default/2026-08-03/{z}/{x}/{y}.pbf?URLPrefix=aHR0cHM6Ly90aWxlcy5naWdzLmNvbS90aWxlcy9kZWZhdWx0LzIwMjYtMDgtMDMv&Expires=1785844800&KeyName=tiles-key-20260930&Signature=pciE55nCNX-qhXzJNSAXaf34624=" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "networkAvailabilityTileset", "expiresAt": "2026-08-04T12:00:00Z", "layers": [ { "technology": "5G", "sourceLayer": "coverage_5g" } ], "maxZoom": 10, "minZoom": 0, "urlTemplate": "https://tiles.gigs.com/tiles/default/2026-08-03/{z}/{x}/{y}.pbf?URLPrefix=aHR0cHM6Ly90aWxlcy5naWdzLmNvbS90aWxlcy9kZWZhdWx0LzIwMjYtMDgtMDMv&Expires=1785844800&KeyName=tiles-key-20260930&Signature=pciE55nCNX-qhXzJNSAXaf34624=" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/plans": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Plans" ], "operationId": "PlansList", "summary": "List all plans", "description": "Returns a list of plans.", "parameters": [ { "name": "provider", "in": "query", "description": "The network provider ID to filter the plans by.", "schema": { "type": "array", "items": { "type": "string", "examples": [ "p3" ] } }, "style": "form", "explode": false }, { "name": "simType", "in": "query", "description": "The type of SIM card to filter the plans by.", "schema": { "type": "array", "default": [ "eSIM", "pSIM" ], "items": { "type": "string", "enum": [ "eSIM", "pSIM" ] } }, "style": "form", "explode": false }, { "name": "status", "in": "query", "description": "The status to filter the plans by. Only available plans are returned by default.", "schema": { "type": "array", "default": [ "available" ], "items": { "type": "string", "enum": [ "available", "archived", "pending", "draft" ] } }, "style": "form", "explode": false }, { "name": "coverageCountry", "in": "query", "description": "The ISO3166 alpha-2 country code to filter the plans by.", "schema": { "type": "array", "items": { "type": "string", "examples": [ "DE" ] } }, "style": "form", "explode": false }, { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a list of plan objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `plan`.", "items": { "$ref": "#/components/schemas/plan" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/plans/{plan}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "$ref": "#/components/parameters/plan" } ], "get": { "tags": [ "Plans" ], "operationId": "PlansRetrieve", "summary": "Retrieve a plan", "description": "Retrieve the details of an existing plan.", "parameters": [], "responses": { "200": { "description": "Returns the plan if it exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plan" }, "examples": { "Example": { "summary": "Example", "value": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "501": { "$ref": "#/components/responses/notImplemented" } } }, "patch": { "tags": [ "Plans" ], "operationId": "PlansUpdate", "summary": "Update a plan", "description": "Updates the specified plan by setting the values of the parameters passed.", "requestBody": { "description": "Plan attributes to update.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The plan's name, meant to be displayable to the user.", "examples": [ "Gigs Global" ] }, "description": { "type": [ "string", "null" ], "description": "The plan's description, meant to be displayable to the user.", "examples": [ "A data plan you will love! Operates in most countries of the world." ] }, "image": { "type": [ "string", "null" ], "format": "url", "description": "The plan's image, meant to be displayable to the user.", "examples": [ "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png" ] }, "metadata": { "$ref": "#/components/schemas/metadataUpdate" } }, "required": [] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "name": "Gigs Global", "description": "A data plan you will love! Operates in most countries of the world.", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "metadata": {} } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": true }, "responses": { "200": { "description": "Returns the updated plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plan" }, "examples": { "Example": { "summary": "Example", "value": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/plans/{plan}/archive": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "$ref": "#/components/parameters/plan" } ], "post": { "tags": [ "Plans" ], "operationId": "PlansArchive", "summary": "Archive a plan", "description": "Set the status of a plan to archived. An archived plan can not be used to create new subscriptions.", "responses": { "200": { "description": "Returns the archived plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plan" }, "examples": { "Example": { "summary": "Example", "value": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/plans/{plan}/publish": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "$ref": "#/components/parameters/plan" } ], "post": { "tags": [ "Plans" ], "operationId": "PlansPublish", "summary": "Publish a plan", "description": "Set the status of a plan to available. Available plans can be used to create new subscriptions.", "responses": { "200": { "description": "Returns the available plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plan" }, "examples": { "Example": { "summary": "Example", "value": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/plans/search": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "post": { "tags": [ "Plans" ], "operationId": "PlansSearch", "summary": "Search for Plans", "description": "Searches for plans matching the given parameters.", "requestBody": { "description": "Attributes to search for.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "array", "default": [ "available" ], "description": "The status to filter plans by.", "items": { "type": "string", "enum": [ "available", "archived", "pending", "draft" ] } }, "simType": { "type": [ "array", "null" ], "description": "The type of the SIM card to filter the plans by.", "items": { "type": "string", "enum": [ "eSIM", "pSIM" ] } }, "provider": { "type": [ "array", "null" ], "description": "The network provider ID to filter the plans by.", "items": { "type": "string" }, "examples": [ [ "p3", "p9" ] ] }, "coverageCountry": { "type": [ "array", "null" ], "description": "The ISO3166 alpha-2 country code to filter the plans by.", "items": { "type": "string" }, "examples": [ [ "DE", "GB" ] ] }, "compatibleWith": { "type": "object", "description": "Compatibility requirements for the plans. Only plans compatible with all requirements are returned. At least one requirement must be specified.", "properties": { "imei": { "type": [ "string", "null" ], "pattern": "^[0-9]{15,16}$", "description": "The IMEI (international mobile equipment identity) of the corresponding device.", "examples": [ "492388841798923" ] }, "deviceModel": { "type": [ "string", "null" ], "description": "The device model identifier of the corresponding device.", "examples": [ "dmd_123" ] }, "subscription": { "type": [ "string", "null" ], "description": "Unique identifier for the subscription.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } } } } }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "status": [ "available" ], "simType": [ "eSIM" ], "provider": [ "p3", "p9" ], "coverageCountry": [ "DE", "GB" ], "compatibleWith": { "imei": "492388841798923", "deviceModel": "dmd_123", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": true }, "responses": { "200": { "description": "Returns a list schema response with all found Plans.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `plan`.", "items": { "$ref": "#/components/schemas/plan" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" }, "503": { "$ref": "#/components/responses/serviceUnavailable" } } } }, "/projects/{project}/planDocuments": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Plans" ], "operationId": "PlanDocumentsList", "summary": "List all plan documents", "description": "Returns a list of documents related to the given plan. The documents returned are sorted by creation date, with the most recently created documents appearing first.", "parameters": [ { "name": "plan", "in": "query", "description": "The unique identifier for the plan to be filtered by.", "schema": { "type": "string", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] } } ], "responses": { "200": { "description": "Returns a list of document objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `planDocument`.", "items": { "$ref": "#/components/schemas/planDocument" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "planDocument", "id": "pdc_0SNlurA049MEWV1S6e1qVqBV2xge", "createdAt": "2022-07-04T16:20:27Z", "language": "en-US", "name": "My Plan Contract", "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "type": "application/pdf", "url": "https://a.gigscdn.net/p/my-project/01G74ZPB5PQTDESM4JGYR2CWB9.pdf" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "planDocument", "id": "pdc_0SNlurA049MEWV1S6e1qVqBV2xge", "createdAt": "2022-07-04T16:20:27Z", "language": "en-US", "name": "My Plan Contract", "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "type": "application/pdf", "url": "https://a.gigscdn.net/p/my-project/01G74ZPB5PQTDESM4JGYR2CWB9.pdf" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } } }, "/projects/{project}/planDocuments/{planDocument}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "planDocument", "in": "path", "description": "The unique identifier for the document.", "required": true, "schema": { "type": "string", "examples": [ "pdc_0SNlurA049MEWV1S6e1qVqBV2xge" ] } } ], "get": { "tags": [ "Plans" ], "operationId": "PlanDocumentsRetrieve", "summary": "Retrieve a plan document", "description": "Retrieves the details of an existing document for a given plan.", "responses": { "200": { "description": "Returns the plan if it exists and is owned by the plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/planDocument" }, "examples": { "Example": { "summary": "Example", "value": { "object": "planDocument", "id": "pdc_0SNlurA049MEWV1S6e1qVqBV2xge", "createdAt": "2022-07-04T16:20:27Z", "language": "en-US", "name": "My Plan Contract", "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "type": "application/pdf", "url": "https://a.gigscdn.net/p/my-project/01G74ZPB5PQTDESM4JGYR2CWB9.pdf" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/portings": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Portings" ], "operationId": "PortingsList", "summary": "List all portings", "description": "Returns a list of portings. The portings returned are sorted by creation date, with the most recently created portings appearing first.", "parameters": [ { "name": "status", "in": "query", "description": "The status to filter the portings by.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "draft", "initiated", "pending", "informationRequired", "requested", "declined", "completed", "canceled", "expired", "failed" ] } }, "style": "form", "explode": false }, { "name": "subscription", "in": "query", "description": "The unique identifier of the subscription to be filtered by.", "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, { "name": "user", "in": "query", "description": "The unique identifier of the user to be filtered by.", "schema": { "type": "string", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of portings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `porting`.", "items": { "$ref": "#/components/schemas/porting" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } }, "post": { "tags": [ "Portings" ], "operationId": "PortingsCreate", "summary": "Create a porting", "description": "Creates a new porting. It will be created in `draft` status and can be later used to create an order or subscription for the same provider.\n\nOnly some of the fields are required during creation. Some providers require additional fields which are listed in the `required` array property of the porting. It will remain in `informationRequired` status until all required information has been collected.\n\nFor a porting with a `requestBehavior` of `automatic`, the porting will then be requested. For a porting with a `requestBehavior` of `manual`, it stays in `informationRequired` until it is requested via the [request a porting](https://developers.gigs.com/core/portings#request-a-porting) endpoint.\n\nRelated guide: [How Porting Works](https://developers.gigs.com/docs/porting/how-porting-in-works)\n", "requestBody": { "description": "Porting parameters to create.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountNumber": { "type": [ "string", "null" ], "description": "The account number on the donor service provider.", "examples": [ "123456789" ] }, "accountPin": { "type": [ "string", "null" ], "description": "The pin for the account on the donor service provider. This will be used only for the porting.", "examples": [ "1234" ] }, "accountType": { "type": [ "string", "null" ], "enum": [ null, "postpaidMulti", "postpaidSingle", "prepaidRegistered", "prepaidUnregistered" ], "description": "The type of account on the donor service provider. Required for portings in Ireland.", "examples": [ "prepaidUnregistered" ] }, "address": { "type": [ "object", "null" ], "description": "The address of the account holder on the donor service provider.", "properties": { "city": { "type": "string", "description": "The city/municipality of the address.", "examples": [ "New York City" ] }, "country": { "type": "string", "description": "The ISO 3166-1 alpha-2 country code of the address.", "examples": [ "US" ] }, "line1": { "type": "string", "description": "The first line of the address, e.g. street and house number.", "examples": [ "129 West 81st Street" ] }, "line2": { "type": [ "string", "null" ], "description": "TThe second line of the address, e.g. apartment number.", "examples": [ "Apartment 5" ] }, "postalCode": { "type": "string", "description": "The postal code of the address.", "examples": [ "10024" ] }, "state": { "type": [ "string", "null" ], "description": "The state/province/region of the address.", "examples": [ "NY" ] } }, "required": [ "city", "country", "line1" ] }, "behavior": { "type": [ "string", "null" ], "enum": [ "cancelOnly", "portIn" ], "default": "portIn", "description": "The behavior of the porting.\n\nUse `portIn` to transfer the phone number from\nthe previous provider.\n\nUse `cancelOnly` to cancel the previous service\nwithout transferring the number. This behavior is currently only\navailable for local plans in the United Kingdom.\n\nDefaults to `portIn` if no value is provided.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "portIn" ] }, "billingPin": { "type": [ "string", "null" ], "description": "The billing pin for the account on the donor service provider. This will be used only for the porting.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "1234" ] }, "birthday": { "type": [ "string", "null" ], "format": "date", "description": "The birthday of the account holder on the donor service provider.", "examples": [ "2017-07-21" ] }, "donorProvider": { "type": [ "string", "null" ], "description": "The unique identifier of the donor service provider.", "examples": [ "svp_0SNlurA01K6GY5L0XJffY8" ] }, "donorProviderApproval": { "type": [ "boolean", "null" ], "description": "Whether the donor provider has approved or not the porting.", "examples": [ true ] }, "firstName": { "type": [ "string", "null" ], "description": "The first name of the account holder.", "examples": [ "Jerry" ] }, "lastName": { "type": [ "string", "null" ], "description": "The last name of the account holder.", "examples": [ "Seinfeld" ] }, "phoneNumber": { "type": "string", "format": "E.164", "description": "The phone number to port in E.164 string_format.", "examples": [ "+19591234567" ] }, "provider": { "type": "string", "description": "The name of the receiving network provider.", "examples": [ "p9" ] }, "requestBehavior": { "type": [ "string", "null" ], "enum": [ null, "automatic", "manual" ], "default": "automatic", "description": "Controls when the porting is submitted to the recipient network provider.\n\nUse `automatic` to have the porting requested automatically as soon as all required information is present.\n\nUse `manual` to withhold that automatic submission, for example to give a user a chance to review the porting first. The porting must then be requested explicitly, once ready, via the [request a porting](https://developers.gigs.com/core/portings#request-a-porting) endpoint. A `manual` porting that has all required information waits in the `informationRequired` status, or in `declined` if it was declined, until it is requested.\n\nDefaults to `automatic` if no value is provided.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "automatic" ] }, "scheduledOn": { "type": [ "string", "null" ], "format": "date", "description": "The date that the porting is scheduled to take effect.\n\nScheduling is only supported by providers in France, Ireland, Sweden and the United Kingdom. Attempting to schedule a porting for any other provider will result in an error. Providers may also apply restrictions to the date.\n\nUse `null` to indicate that the porting should be scheduled as soon as possible. Otherwise, the date provided must be in the future.\n\nIf, by the time the porting is requested from the provider, the scheduled date has already passed, then the porting will instead occur as soon as possible.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "2021-01-21" ] }, "user": { "type": "string", "description": "The unique identifier for an existing [user](https://developers.gigs.com/core/users#the-user-resource) the porting should be created for.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, "required": [ "phoneNumber", "provider", "user" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "accountNumber": "123456789", "accountPin": "1234", "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPin": "1234", "birthday": "2017-07-21", "donorProvider": "svp_0SNlurA01K6GY5L0XJffY8", "donorProviderApproval": true, "firstName": "Jerry", "lastName": "Seinfeld", "phoneNumber": "+19591234567", "provider": "p9", "requestBehavior": "automatic", "scheduledOn": "2021-01-21", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } }, "Example - Required": { "summary": "Example - Required", "value": { "phoneNumber": "+19591234567", "provider": "p9", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } }, "required": true }, "responses": { "201": { "description": "Returns the created porting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/porting" }, "examples": { "Example": { "summary": "Example", "value": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" }, "503": { "$ref": "#/components/responses/serviceUnavailable" } } } }, "/projects/{project}/portings/{porting}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "porting", "in": "path", "description": "The unique identifier for the porting.", "required": true, "schema": { "type": "string", "examples": [ "prt_0SNlurA049MEWV39s2kSYqaat7ZS" ] } } ], "get": { "tags": [ "Portings" ], "operationId": "PortingsRetrieve", "summary": "Retrieve a Porting", "description": "Retrieves the details of an existing porting.", "responses": { "200": { "description": "Returns the porting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/porting" }, "examples": { "Example": { "summary": "Example", "value": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } }, "delete": { "tags": [ "Portings" ], "operationId": "PortingsDelete", "summary": "Delete a draft porting", "description": "Deletes a porting that is in the `draft` state.", "responses": { "200": { "description": "Returns the porting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/porting" }, "examples": { "Example": { "summary": "Example", "value": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } }, "patch": { "tags": [ "Portings" ], "operationId": "PortingsUpdate", "summary": "Update a porting", "description": "Updates a porting with the given parameters.\n\nDepending on the status of the porting, some fields may not be updated anymore.\n\nFor a porting with a `requestBehavior` of `automatic`, the porting will be requested when all the required information is provided. If the porting is declined, it will be retried. To retry a porting without providing any new information, simply update the porting with an empty request.\n\nFor a porting with a `requestBehavior` of `manual`, the porting is only requested via the [request a porting](https://developers.gigs.com/core/portings#request-a-porting) endpoint, including when it was declined.\n\nRelated guide: [How Porting Works](https://developers.gigs.com/docs/core/how-porting-in-works)\n", "requestBody": { "description": "Porting parameters to update.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountNumber": { "type": "string", "description": "The account number on the donor service provider.", "examples": [ "123456789" ] }, "accountPin": { "type": "string", "description": "The pin for the account on the donor service provider. This will be used only for the porting.", "examples": [ "1234" ] }, "accountType": { "type": "string", "enum": [ "postpaidMulti", "postpaidSingle", "prepaidRegistered", "prepaidUnregistered" ], "description": "The type of account on the donor service provider. Required for portings in Ireland.", "examples": [ "prepaidUnregistered" ] }, "address": { "type": [ "object" ], "description": "The address of the account holder on the donor service provider.", "properties": { "city": { "type": "string", "description": "The city/municipality of the address.", "examples": [ "New York City" ] }, "country": { "type": "string", "description": "The ISO 3166-1 alpha-2 country code of the address.", "examples": [ "US" ] }, "line1": { "type": "string", "description": "The first line of the address, e.g. street and house number.", "examples": [ "129 West 81st Street" ] }, "line2": { "type": [ "string", "null" ], "description": "TThe second line of the address, e.g. apartment number.", "examples": [ "Apartment 5" ] }, "postalCode": { "type": [ "string", "null" ], "description": "The postal code of the address.", "examples": [ "10024" ] }, "state": { "type": [ "string", "null" ], "description": "The state/province/region of the address.", "examples": [ "NY" ] } }, "required": [] }, "behavior": { "type": [ "string" ], "enum": [ "cancelOnly", "portIn" ], "description": "The behavior of the porting.\n\nUse `portIn` to transfer the phone number from\nthe previous provider.\n\nUse `cancelOnly` to cancel the previous service\nwithout transferring the number. This behavior is currently only\navailable for local plans in the United Kingdom.\n\nThis property is only updatable when the porting's status is draft.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "portIn" ] }, "billingPin": { "type": "string", "description": "The billing pin for the account on the donor service provider. This will be used only for the porting.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "1234" ] }, "birthday": { "type": "string", "format": "date", "description": "The birthday of the account holder on the donor service provider.", "examples": [ "2017-07-21" ] }, "donorProvider": { "type": "string", "description": "The unique identifier of the donor service provider.", "examples": [ "svp_0SNlurA01K6GY5L0XJffY8" ] }, "donorProviderApproval": { "type": [ "boolean" ], "description": "Whether the donor provider has approved or not the porting.", "examples": [ true ] }, "firstName": { "type": "string", "description": "The first name of the account holder.", "examples": [ "Jerry" ] }, "lastName": { "type": "string", "description": "The last name of the account holder.", "examples": [ "Seinfeld" ] }, "phoneNumber": { "type": "string", "format": "E.164", "description": "The phone number to port in E.164 string_format. This is only updatable when the porting is in a status of: draft, or, for providers `p11` and `p12`, declined or informationRequired.", "examples": [ "+19591234567" ] }, "provider": { "type": "string", "description": "The ID of the recipient network provider. This is only updatable when the porting is in a status of: draft", "examples": [ "p9" ] }, "requestBehavior": { "type": [ "string" ], "enum": [ "automatic", "manual" ], "description": "Controls when the porting is submitted to the recipient network provider.\n\nUse `automatic` to have the porting requested automatically as soon as all required information is present.\n\nUse `manual` to withhold that automatic submission, for example to give a user a chance to review the porting first. The porting must then be requested explicitly, once ready, via the [request a porting](https://developers.gigs.com/core/portings#request-a-porting) endpoint. A `manual` porting that has all required information waits in the `informationRequired` status, or in `declined` if it was declined, until it is requested.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "automatic" ] }, "scheduledOn": { "type": [ "string", "null" ], "format": "date", "description": "Date when the porting is scheduled to take effect.\n\nScheduling is only supported by providers in France, Ireland, Sweden and the United Kingdom. Attempting to schedule a porting for any other provider will result in an error. Providers may also apply restrictions to the date.\n\nUse `null` to indicate that the porting should be scheduled as soon as possible. Otherwise, the date provided must be in the future.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "2021-01-21" ] } }, "required": [] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "accountNumber": "123456789", "accountPin": "1234", "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPin": "1234", "birthday": "2017-07-21", "donorProvider": "svp_0SNlurA01K6GY5L0XJffY8", "donorProviderApproval": true, "firstName": "Jerry", "lastName": "Seinfeld", "phoneNumber": "+19591234567", "provider": "p9", "requestBehavior": "automatic", "scheduledOn": "2021-01-21" } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": true }, "responses": { "200": { "description": "Returns the updated porting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/porting" }, "examples": { "Example": { "summary": "Example", "value": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" }, "503": { "$ref": "#/components/responses/serviceUnavailable" } } } }, "/projects/{project}/portings/{porting}/cancel": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "porting", "in": "path", "description": "The unique identifier for the porting.", "required": true, "schema": { "type": "string", "examples": [ "prt_0SNlurA049MEWV39s2kSYqaat7ZS" ] } } ], "post": { "tags": [ "Portings" ], "operationId": "PortingsCancel", "summary": "Cancel a porting", "description": "Cancels a porting. A porting can be cancelled in the following situations:\n - it is in the `initiated`, `declined` or `informationRequired` state,\n - it is in the `pending` state **and** the porting request has not been sent to the provider yet,\n - it is in the `requested` state **and** it is scheduled for a future date that is within the provider's cancellation window.\n\nCanceling a porting will result in the activation of the subscription with a new number. To cancel the whole process, end the subscription instead.\n", "responses": { "200": { "description": "Returns the canceled porting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/porting" }, "examples": { "Example": { "summary": "Example", "value": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/portings/{porting}/request": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "porting", "in": "path", "description": "The unique identifier for the porting.", "required": true, "schema": { "type": "string", "examples": [ "prt_0SNlurA049MEWV39s2kSYqaat7ZS" ] } } ], "post": { "tags": [ "Portings" ], "operationId": "PortingsRequest", "summary": "Request a porting", "description": "Requests a porting from the recipient network provider.\n\nOnly portings with a `requestBehavior` of `manual` can be requested with this endpoint. The porting must be in the `informationRequired` or `declined` status, have all required information and be attached to a subscription that is pending or active.\n\nRelated guide: [How Porting Works](https://developers.gigs.com/docs/core/how-porting-in-works)\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "responses": { "200": { "description": "Returns the porting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/porting" }, "examples": { "Example": { "summary": "Example", "value": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/portings/search": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "post": { "tags": [ "Portings" ], "operationId": "PortingsSearch", "summary": "Search for portings", "description": "Searches for existing portings matching the given parameters.", "requestBody": { "description": "Porting attributes to search for.", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "type": "string", "format": "E.164", "description": "The E.164-formatted phone number associated with the porting.", "examples": [ "+12065550123" ] } }, "required": [ "phoneNumber" ] }, "examples": { "Example": { "summary": "Example", "value": { "phoneNumber": "+12065550123" } } } } }, "required": true }, "responses": { "200": { "description": "Returns a list of portings matching the search criteria.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `porting`.", "items": { "$ref": "#/components/schemas/porting" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/portOuts": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Port Outs" ], "operationId": "PortOutsList", "summary": "List all port outs", "description": "Returns a list of port outs.", "parameters": [ { "name": "subscription", "in": "query", "description": "The unique identifier of the subscription to be filtered by.", "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, { "name": "status", "in": "query", "description": "A comma-separated list of statuses to filter the port outs by. Only initiated, processing and issued port outs are returned by default.", "schema": { "type": "array", "default": [ "initiated", "issued", "processing" ], "items": { "type": "string", "enum": [ "completed", "expired", "failed", "initiated", "issued", "processing" ] } }, "style": "form", "explode": false }, { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of port outs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `portOut`.", "items": { "$ref": "#/components/schemas/portOut" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "portOut", "id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s", "behavior": "portOut", "completedAt": "2022-02-21T19:38:34Z", "createdAt": "2020-01-01T00:00:00Z", "expirationRequestedAt": "2022-02-21T19:38:12Z", "expiredAt": "2022-02-21T19:38:34Z", "failureReason": "consentNotGiven", "status": "issued", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "portOut", "id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s", "behavior": "portOut", "completedAt": "2022-02-21T19:38:34Z", "createdAt": "2020-01-01T00:00:00Z", "expirationRequestedAt": "2022-02-21T19:38:12Z", "expiredAt": "2022-02-21T19:38:34Z", "failureReason": "consentNotGiven", "status": "issued", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } }, "post": { "tags": [ "Port Outs" ], "operationId": "PortOutsCreate", "summary": "Create port out", "description": "Create a new port out.", "parameters": [], "requestBody": { "description": "Port out parameters to create.", "content": { "application/json": { "schema": { "type": "object", "properties": { "behavior": { "type": [ "string", "null" ], "enum": [ "cancelOnly", "portOut" ], "default": "portOut", "description": "The behavior of the port out.\n\nA value of `portOut` indicates that using this\nport out will transfer the phone number to the recipient provider.\n\nPort out with behavior `cancelOnly`\nwill cancel the service without transferring the number. This behavior is\ncurrently only available for local plans in the United Kingdom.\n\nDefaults to `portOut` if no value is provided.\n", "examples": [ "portOut" ] }, "subscription": { "type": [ "string" ], "description": "Unique identifier of the subscription the port out applies to.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, "required": [ "subscription" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "behavior": "portOut", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } }, "Example - Required": { "summary": "Example - Required", "value": { "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } } } } }, "required": true }, "responses": { "201": { "description": "Returns the created port out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/portOut" }, "examples": { "Example": { "summary": "Example", "value": { "object": "portOut", "id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s", "behavior": "portOut", "completedAt": "2022-02-21T19:38:34Z", "createdAt": "2020-01-01T00:00:00Z", "expirationRequestedAt": "2022-02-21T19:38:12Z", "expiredAt": "2022-02-21T19:38:34Z", "failureReason": "consentNotGiven", "status": "issued", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/portOuts/{portOut}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "portOut", "in": "path", "description": "The unique identifier for the port out.", "required": true, "schema": { "type": "string", "examples": [ "pto_0SNlurA049MEWV4DWEaT4SaeDI8s" ] } } ], "get": { "tags": [ "Port Outs" ], "operationId": "PortOutsRetrieve", "summary": "Retrieve port out", "description": "Retrieves the details of an existing port out.", "responses": { "200": { "description": "Returns the port out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/portOut" }, "examples": { "Example": { "summary": "Example", "value": { "object": "portOut", "id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s", "behavior": "portOut", "completedAt": "2022-02-21T19:38:34Z", "createdAt": "2020-01-01T00:00:00Z", "expirationRequestedAt": "2022-02-21T19:38:12Z", "expiredAt": "2022-02-21T19:38:34Z", "failureReason": "consentNotGiven", "status": "issued", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/portOuts/{portOut}/credentials": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "portOut", "in": "path", "description": "The unique identifier for the port out.", "required": true, "schema": { "type": "string", "examples": [ "pto_0SNlurA049MEWV4DWEaT4SaeDI8s" ] } } ], "get": { "tags": [ "Port Outs" ], "operationId": "PortOutCredentialsRetrieve", "summary": "Retrieve port out credentials", "description": "Retrieve the credentials of an issued port out.", "responses": { "200": { "description": "Returns the port out credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/portOutCredentials" }, "examples": { "Example": { "summary": "Example", "value": { "object": "portOutCredentials", "accountNumber": "123456789", "accountPin": "1234", "portOut": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/portOuts/{portOut}/expire": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "portOut", "in": "path", "description": "The unique identifier for the port out.", "required": true, "schema": { "type": "string", "examples": [ "pto_0SNlurA049MEWV4DWEaT4SaeDI8s" ] } } ], "post": { "tags": [ "Port Outs" ], "operationId": "PortOutsExpire", "summary": "Expire existing port out credentials", "description": "Requests expiration of the port out, making the credentials unusable. Port outs with a status\nof `\"initiated\"`, `\"processing\"` or `\"issued\"` can be expired. The returned port out\nwill have the status as before, but with an `expirationRequestedAt` timestamp.\n", "responses": { "200": { "description": "Returns the port out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/portOut" }, "examples": { "Example": { "summary": "Example", "value": { "object": "portOut", "id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s", "behavior": "portOut", "completedAt": "2022-02-21T19:38:34Z", "createdAt": "2020-01-01T00:00:00Z", "expirationRequestedAt": "2022-02-21T19:38:12Z", "expiredAt": "2022-02-21T19:38:34Z", "failureReason": "consentNotGiven", "status": "issued", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects": { "get": { "tags": [ "Projects" ], "operationId": "ProjectsList", "summary": "List all projects", "description": "Returns a list of projects. The projects returned are sorted by creation date, with the most recently created projects appearing first.", "parameters": [ { "name": "organization", "in": "query", "description": "The unique identifier for the organization to be filtered by.", "schema": { "type": "string", "examples": [ "org_0SNlurA04kOdemVEMVZQBF" ] } }, { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of projects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `project`.", "items": { "$ref": "#/components/schemas/project" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "project", "id": "gigs", "billing": { "advanceInvoicingDays": 7, "invoiceGracePeriodDays": 3, "invoiceOverdueDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": "end", "currency": "USD", "restrictBehavior": null, "restoreBehavior": null, "paymentBehavior": "manual", "taxBehavior": "exclusive", "recoveryFeePercentage": 10.0, "recoveryFeeAmount": { "amount": 150, "currency": "USD" } }, "consent": { "deliveryMethods": [ "emailLink" ], "approvalBaseUrl": "https://consent.gigs.com/consent" }, "createdAt": "2021-01-21T19:32:13Z", "image": "https://a.gigscdn.net/p/gigs/icon.png", "legal": { "name": "Gigs Inc.", "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "locales": [ "en-US" ], "name": "Gigs Connect", "organization": { "object": "organization", "id": "org_0SNlurA04kOdemVEMVZQBF", "createdAt": "2021-02-01T13:21:30Z", "name": "Gigs" }, "payments": { "currency": "USD", "mode": "live" }, "subscriptionOwner": "user", "support": { "email": "support@gigs.com", "phoneNumber": "+12345678900" }, "tax": { "country": "US" }, "type": "live" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "project", "id": "gigs", "billing": { "advanceInvoicingDays": 7, "invoiceGracePeriodDays": 3, "invoiceOverdueDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": "end", "currency": "USD", "restrictBehavior": null, "restoreBehavior": null, "paymentBehavior": "manual", "taxBehavior": "exclusive", "recoveryFeePercentage": 10.0, "recoveryFeeAmount": { "amount": 150, "currency": "USD" } }, "consent": {}, "createdAt": "2021-01-21T19:32:13Z", "image": "https://a.gigscdn.net/p/gigs/icon.png", "legal": { "name": "Gigs Inc.", "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "locales": [ "en-US" ], "name": "Gigs Connect", "organization": { "object": "organization", "id": "org_0SNlurA04kOdemVEMVZQBF", "createdAt": "2021-02-01T13:21:30Z", "name": "Gigs" }, "payments": { "currency": "USD", "mode": "live" }, "subscriptionOwner": "user", "support": { "email": "support@gigs.com", "phoneNumber": "+12345678900" }, "tax": { "country": "US" }, "type": "live" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Projects" ], "operationId": "ProjectsRetrieve", "summary": "Retrieve a project", "description": "Retrieves the details of an existing project accessible by the API client.", "responses": { "200": { "description": "Returns the project object if it exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/project" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "project", "id": "gigs", "billing": { "advanceInvoicingDays": 7, "invoiceGracePeriodDays": 3, "invoiceOverdueDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": "end", "currency": "USD", "restrictBehavior": null, "restoreBehavior": null, "paymentBehavior": "manual", "taxBehavior": "exclusive", "recoveryFeePercentage": 10.0, "recoveryFeeAmount": { "amount": 150, "currency": "USD" } }, "consent": { "deliveryMethods": [ "emailLink" ], "approvalBaseUrl": "https://consent.gigs.com/consent" }, "createdAt": "2021-01-21T19:32:13Z", "image": "https://a.gigscdn.net/p/gigs/icon.png", "legal": { "name": "Gigs Inc.", "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "locales": [ "en-US" ], "name": "Gigs Connect", "organization": { "object": "organization", "id": "org_0SNlurA04kOdemVEMVZQBF", "createdAt": "2021-02-01T13:21:30Z", "name": "Gigs" }, "payments": { "currency": "USD", "mode": "live" }, "subscriptionOwner": "user", "support": { "email": "support@gigs.com", "phoneNumber": "+12345678900" }, "tax": { "country": "US" }, "type": "live" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "project", "id": "gigs", "billing": { "advanceInvoicingDays": 7, "invoiceGracePeriodDays": 3, "invoiceOverdueDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": "end", "currency": "USD", "restrictBehavior": null, "restoreBehavior": null, "paymentBehavior": "manual", "taxBehavior": "exclusive", "recoveryFeePercentage": 10.0, "recoveryFeeAmount": { "amount": 150, "currency": "USD" } }, "consent": {}, "createdAt": "2021-01-21T19:32:13Z", "image": "https://a.gigscdn.net/p/gigs/icon.png", "legal": { "name": "Gigs Inc.", "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "locales": [ "en-US" ], "name": "Gigs Connect", "organization": { "object": "organization", "id": "org_0SNlurA04kOdemVEMVZQBF", "createdAt": "2021-02-01T13:21:30Z", "name": "Gigs" }, "payments": { "currency": "USD", "mode": "live" }, "subscriptionOwner": "user", "support": { "email": "support@gigs.com", "phoneNumber": "+12345678900" }, "tax": { "country": "US" }, "type": "live" } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } } }, "/projects/{project}/credentials": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Projects" ], "operationId": "ProjectCredentialsRetrieve", "summary": "Retrieve the project credentials", "description": "Retrieve the credentials of an existing project.\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "responses": { "200": { "description": "Returns the project credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectCredentials" }, "examples": { "Example": { "summary": "Example", "value": { "object": "projectCredentials", "paymentsKey": "pk_test_XXooYYauvdEDq12NiTphI7sa" } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } } }, "/serviceProviders": { "get": { "tags": [ "Portings" ], "operationId": "ServiceProvidersList", "summary": "List all service providers", "description": "Returns a list of service providers. It is recommended that callers provide either a recipient provider or country to filter for relevant service providers.\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "parameters": [ { "name": "recipientProvider", "in": "query", "description": "Only return service providers that have the given network provider as supported porting recipient.", "schema": { "type": "string", "examples": [ "p7" ] } }, { "name": "country", "in": "query", "description": "Only return service providers for the given country represented by the ISO 3166-1 alpha-2 country code.", "schema": { "type": "string", "examples": [ "US" ] } } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of service providers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `serviceProvider`.", "items": { "$ref": "#/components/schemas/serviceProvider" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/serviceProviders/{serviceProvider}": { "parameters": [ { "name": "serviceProvider", "in": "path", "description": "The unique identifier for the service provider.", "required": true, "schema": { "type": "string", "examples": [ "svp_0SNlurA01K6GY5L0XJffY8" ] } } ], "get": { "tags": [ "Portings" ], "operationId": "ServiceProvidersRetrieve", "summary": "Retrieve a service provider", "description": "Retrieves the details of a service provider.\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "responses": { "200": { "description": "Returns the service provider object if it exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/serviceProvider" }, "examples": { "Example": { "summary": "Example", "value": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } } }, "/projects/{project}/sims": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "SIMs" ], "operationId": "SimsList", "summary": "List all SIMs", "description": "Returns a list of SIMs. The SIMs returned are sorted by creation date, with the most recently created SIMs appearing first.", "parameters": [ { "name": "provider", "in": "query", "description": "The network provider ID for the sim to be filtered by.", "schema": { "type": "array", "items": { "type": "string", "examples": [ "p3" ] } }, "style": "form", "explode": false }, { "name": "status", "in": "query", "description": "A comma-separated list of statuses to filter the sims by.", "schema": { "type": "array", "default": [ "inactive", "active" ], "items": { "type": "string", "enum": [ "inactive", "active", "retired" ] } }, "style": "form", "explode": false }, { "name": "type", "in": "query", "description": "The type for the sim to be filtered by.", "schema": { "type": "string", "enum": [ "eSIM", "pSIM" ] } }, { "name": "user", "in": "query", "description": "The unique identifier for the user to be filtered by.", "schema": { "type": "string", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of SIMs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `sim`.", "items": { "$ref": "#/components/schemas/sim" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/sims/{sim}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "sim", "in": "path", "description": "The unique identifier for the SIM.", "required": true, "schema": { "type": "string", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] } } ], "get": { "tags": [ "SIMs" ], "operationId": "SimsRetrieve", "summary": "Retrieve a SIM", "description": "Retrieve the details of an existing SIM which the authenticated user is authorized to view.", "responses": { "200": { "description": "Returns the SIM if it exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sim" }, "examples": { "Example": { "summary": "Example", "value": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } }, "patch": { "tags": [ "SIMs" ], "operationId": "SimsUpdate", "summary": "Update a SIM", "description": "Update the details of an existing SIM.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/metadataUpdate" } } }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "metadata": {} } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": false }, "responses": { "200": { "description": "Returns the updates SIM.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sim" }, "examples": { "Example": { "summary": "Example", "value": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "403": { "$ref": "#/components/responses/permissionDenied" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/sims/{sim}/credentials": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "sim", "in": "path", "description": "The unique identifier for the SIM.", "required": true, "schema": { "type": "string", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] } } ], "get": { "tags": [ "SIMs" ], "operationId": "SimCredentialsRetrieve", "summary": "Retrieve the SIM credentials", "description": "Retrieve the credentials of an existing SIM.", "responses": { "200": { "description": "Returns the SIM credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/simCredentials" }, "examples": { "Example": { "summary": "Example", "value": { "object": "simCredentials", "activationCode": "LPA:1$smdp.gigs.com$2M-3L0MX-F8HE2", "androidInstallUrl": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.gigs.com$2M-3L0MX-F8HE2", "iosInstallUrl": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.gigs.com$2M-3L0MX-F8HE2", "puk1": "12345678", "puk2": "12345678", "qrCodeUrl": "https://files.gigs.com/qrcode/example/pUNIvfeLBNQ.png", "sim": "sim_0SNlurA049MEWV1BAAmWZULA4lf6" } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } } }, "/projects/{project}/sims/search": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "post": { "tags": [ "SIMs" ], "operationId": "SimsSearch", "summary": "Search for SIMs", "description": "Searches for existing SIMs matching the given parameters.", "requestBody": { "description": "SIM attributes to search for.", "content": { "application/json": { "schema": { "type": "object", "properties": { "iccid": { "type": "string", "pattern": "^([0-9]{19}[Ff]?|[0-9]{20})$", "description": "The ICCID (integrated circuit card identifier) associated with the SIM.", "examples": [ "89883070000007537119" ] }, "type": { "type": [ "array", "null" ], "default": [ "eSIM", "pSIM" ], "description": "Optional type of the SIM card, either `eSIM`, `pSIM` or both.", "items": { "type": "string", "enum": [ "eSIM", "pSIM" ] } } }, "required": [ "iccid" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "iccid": "89883070000007537119", "type": [ "eSIM" ] } }, "Example - Required": { "summary": "Example - Required", "value": { "iccid": "89883070000007537119" } } } } }, "required": true }, "responses": { "200": { "description": "Returns a list schema response with all found SIMs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `sim`.", "items": { "$ref": "#/components/schemas/sim" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/sims/{sim}/suspend": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "sim", "in": "path", "description": "The unique identifier for the SIM.", "required": true, "schema": { "type": "string", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] } } ], "post": { "tags": [ "SIMs" ], "operationId": "SimsSuspend", "summary": "Suspend a SIM", "description": "Suspends all connectivity of the SIM, blocking voice, SMS and data, for example when the device is lost or stolen.\nThe subscription, the phone number and billing are not affected.\n\nIf the SIM is still suspended 30 days after the suspension took effect, its subscription ends.\nUnsuspending the SIM before then cancels the end.\n\nThe returned SIM includes a `suspension` object with `status: suspending`. The status changes to `suspended` once the network provider confirms the suspension.\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "responses": { "200": { "description": "Returns the SIM with the requested suspension.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sim" }, "examples": { "Example": { "summary": "Example", "value": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": { "status": "suspending", "updatedAt": "2026-09-24T10:00:00Z" }, "type": "eSIM" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/sims/{sim}/unsuspend": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "sim", "in": "path", "description": "The unique identifier for the SIM.", "required": true, "schema": { "type": "string", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] } } ], "post": { "tags": [ "SIMs" ], "operationId": "SimsUnsuspend", "summary": "Unsuspend a SIM", "description": "Restores the connectivity of a suspended SIM, for example once a lost device is recovered.\n\nThe returned SIM includes a `suspension` object with `status: unsuspending`. The SIM has no service until the network provider confirms, at which point `suspension` is cleared.\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "responses": { "200": { "description": "Returns the SIM, which stays suspended until the network provider confirms it can proceed to unsuspend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sim" }, "examples": { "Example": { "summary": "Example", "value": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": { "status": "unsuspending", "updatedAt": "2026-09-24T10:00:00Z" }, "type": "eSIM" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/subscriptions": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Subscriptions" ], "operationId": "SubscriptionsList", "summary": "List all subscriptions", "description": "Returns a list of subscriptions. The subscriptions returned are sorted by creation date, with the most recently created subscriptions appearing first.", "parameters": [ { "name": "user", "in": "query", "description": "The unique identifier for the user to be filtered by.", "schema": { "type": "string", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, { "name": "plan", "in": "query", "description": "The unique identifier for the plan to be filtered by.", "schema": { "type": "string", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] } }, { "name": "sim", "in": "query", "description": "The unique identifier for the sim to be filtered by.", "schema": { "type": "string", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] } }, { "name": "status", "in": "query", "description": "A comma-separated list of statuses to filter the subscriptions by. Only pending and active subscriptions are returned by default.", "schema": { "type": "array", "default": [ "pending", "initiated", "active", "restricted" ], "items": { "type": "string", "enum": [ "pending", "initiated", "active", "restricted", "ended" ] } }, "style": "form", "explode": false }, { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a list of subscription objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `subscription`.", "items": { "$ref": "#/components/schemas/subscription" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": { "cause": "cancellationRequested", "userReason": "connectivityIssues" }, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": {}, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } } } }, "post": { "tags": [ "Subscriptions" ], "operationId": "SubscriptionsCreate", "summary": "Create a subscription", "description": "Creates a new subscription for an existing user in the specified project.", "parameters": [], "requestBody": { "description": "Optional and required parameters to be passed in the request body to create a new subscription:", "content": { "application/json": { "schema": { "type": "object", "properties": { "billing": { "type": [ "object", "null" ], "description": "Configuration for this specific subscription billing. Only available when the Billing API is enabled.", "properties": { "discount": { "type": [ "object", "null" ], "description": "Discount to apply to the subscription.", "properties": { "voucher": { "type": [ "string", "null" ], "description": "The unique identifier for the existing [voucher](https://developers.gigs.com/api/latest/billing/vouchers) of the subscription. A voucher applies a discount to the price of a subscription.", "examples": [ "vou_0SNlurA049MEWV0h2jfjkdiOdplN" ] } } }, "invoiceGracePeriodDays": { "type": [ "integer", "null" ], "description": "Number of days after renewal that an invoice can remain unpaid before it becomes overdue. After this period, the action specified in `invoiceOverdueAction` is triggered.\n\nWhen configured, this property takes precedence over the value set at the project level.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ 3 ] }, "invoiceOverduePeriodDays": { "type": [ "integer", "null" ], "description": "Number of days that invoices can remain overdue before subscriptions are ended.\n\nRelevant when subscriptions are not ended immediately after an invoice becomes overdue.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ 1 ] }, "invoiceOverdueAction": { "type": [ "string", "null" ], "enum": [ "end", "none", "restrict" ], "description": "Indicates what happens to the subscription when a renewal invoice becomes overdue. One of:\n\n- `none`: Leave the subscription as is.\n- `end`: End the subscription immediately.\n\nWhen configured, this property takes precedence over the value set at the project level.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n" }, "restrictBehavior": { "type": [ "string", "null" ], "enum": [ null, "incomingOnly", "noData", "throttledData" ], "description": "Required when `invoiceOverdueAction` is `restrict`.\nDetermines how subscriptions are restricted when an invoice becomes overdue. It can have one of the following values:\n\n- `incomingOnly`: The subscription line can receive calls & SMS, but cannot make calls, send SMS, or use data.\n- `noData`: The subscription line can make and receive calls & SMS, but cannot use data.\n- `throttledData`: The subscription line can still make and receive calls & SMS, and use up to 1GB of data at a reduced speed.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n" }, "restoreBehavior": { "type": [ "string", "null" ], "enum": [ null, "keepPeriodAnchor", "resetPeriodAnchor" ], "description": "Required when `invoiceOverdueAction` is `restrict`.\nDetermines how subscriptions are restored once a subscription is restored (e.g. after payment of an overdue invoice). It can have one of the following values:\n\n- `resetPeriodAnchor`: The subscription cycle is reset to the date of restoration. This means the user has a whole new period to use their plan allowance that was just restored.\n- `keepPeriodAnchor`: The subscription cycle remains unchanged. The next renewal date stays the same as before the restriction.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n" } } }, "device": { "type": [ "string", "null" ], "description": "The unique identifier for the existing [device](https://developers.gigs.com/core/devices#the-device-resource) to be linked with the passed SIM. Some network providers require this field (or `deviceModel`) for activation. If the exact IMEI of the device is known, then it is recommended to create a device and specify its ID here. See `deviceModel` if the device IMEI is not known. At most one of `device` and `deviceModel` may be specified. Trying to link a pSIM to a second device will cause an error.", "examples": [ "dev_0SNlurA049MEWV55CrA9qMvI2FVJ" ] }, "deviceModel": { "type": [ "string", "null" ], "description": "The unique identifier for the [device model](https://developers.gigs.com/core/devices#retrieve-a-device-model) to be linked with the passed SIM. Some network providers require this field (or `device`) for activation. If the device IMEI is not known, but the device model is known, this property can be used in place of `device`. At most one of `device` and `deviceModel` may be specified.", "examples": [ "dmd_0SNlurA04OUskUGfGAn3Rh" ] }, "metadata": { "$ref": "#/components/schemas/metadataUpdate" }, "fromSubscription": { "type": [ "string", "null" ], "description": "The unique identifier for an existing ended [subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource) to base the new subscription on. The referenced subscription must have status `ended` and its SIM must still be usable (not retired, not ported out). When provided, the user, plan, SIM, billing settings, and applicable discounts are copied from the referenced subscription. This is the recommended way to reactivate an ended subscription and keep its phone number. An eSIM whose profile was deleted from the device can still be reused this way. If the original eSIM can't be installed on the phone anymore, follow up with a [subscription change](https://developers.gigs.com/core/subscription-changes#the-subscription-change-resource) to issue a new one. Cannot be combined with `user`, `plan`, `sim`, `porting`, `device`, `deviceModel`, `userAddress`, or `billing`." }, "plan": { "type": [ "string", "null" ], "description": "The unique identifier for the existing [plan](https://developers.gigs.com/core/plans#the-plan-resource) to be used for the subscription. Required if `fromSubscription` is not provided.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] }, "porting": { "type": [ "string", "null" ], "description": "The unique identifier for the existing draft [porting](https://developers.gigs.com/core/portings#the-porting-resource) to be used for the subscription.", "examples": [ "prt_0SNlurA049MEWV39s2kSYqaat7ZS" ] }, "sim": { "type": [ "string", "null" ], "default": "auto", "description": "The unique identifier for the existing [SIM](https://developers.gigs.com/core/sims#the-sim-resource) to be used for the subscription. In combination with an eSIM plan, it can be passed as `auto` to request a new eSIM, or `preferLastUsed` to reuse the user's most recently used SIM from an ended subscription. `preferLastUsed` falls back to `auto` if no eligible SIM is found, which only works for eSIM-capable plans; for plans requiring a physical SIM, subscription creation will fail if no eligible SIM is found.", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] }, "userAddress": { "type": [ "string", "null" ], "description": "The unique identifier for the existing [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) to be used for the subscription. Only needed if the plan requires an address.", "examples": [ "adr_0SNlurA049MEWV5ELDmnaqVXgTFT" ] }, "user": { "type": [ "string", "null" ], "description": "The unique identifier for the existing [user](https://developers.gigs.com/core/users#the-user-resource) to which the subscription will be assigned. Required if `fromSubscription` is not provided.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } } }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": "end" }, "device": "dev_0SNlurA049MEWV55CrA9qMvI2FVJ", "deviceModel": "dmd_0SNlurA04OUskUGfGAn3Rh", "metadata": {}, "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "porting": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "sim": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": true }, "responses": { "201": { "description": "Returns the newly created subscription and supporting objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": { "cause": "cancellationRequested", "userReason": "connectivityIssues" }, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": {}, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/subscriptions/{subscription}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "subscription", "in": "path", "description": "The unique identifier for the subscription.", "required": true, "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } } ], "get": { "tags": [ "Subscriptions" ], "operationId": "SubscriptionsRetrieve", "summary": "Retrieve a subscription", "description": "Retrieves the details of an existing subscription. You need only supply the unique subscription identifier that was returned upon purchasing a plan.", "responses": { "200": { "description": "Returns the subscription if it exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": { "cause": "cancellationRequested", "userReason": "connectivityIssues" }, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": {}, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } }, "patch": { "tags": [ "Subscriptions" ], "operationId": "SubscriptionsUpdate", "summary": "Update a subscription", "description": "Updates the specified subscription by setting the values of the parameters passed.", "requestBody": { "description": "Optional parameters to be passed in the request body to update an existing subscription.", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/metadataUpdate" }, "billing": { "type": [ "object" ], "description": "Configuration for this specific subscription billing. Only available when the Billing API is enabled.", "properties": { "discount": { "type": [ "object", "null" ], "description": "Discount to apply to the subscription. Using a `null` value will remove any existing discount.", "properties": { "voucher": { "type": "string", "description": "The unique identifier for the existing [voucher](https://developers.gigs.com/api/latest/billing/vouchers) of the subscription. A voucher applies a discount to the price of a subscription.", "examples": [ "vou_0SNlurA049MEWV0h2jfjkdiOdplN" ] } } }, "invoiceGracePeriodDays": { "type": [ "integer", "null" ], "description": "Number of days after renewal that an invoice can remain unpaid before it becomes overdue. After this period, the action specified in `invoiceOverdueAction` is triggered.\n\nWhen configured, this property takes precedence over the value set at the project level.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ 3 ] }, "invoiceOverduePeriodDays": { "type": [ "integer", "null" ], "description": "Number of days that invoices can remain overdue before subscriptions are ended.\n\nRelevant when subscriptions are not ended immediately after an invoice becomes overdue.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ 1 ] }, "invoiceOverdueAction": { "type": [ "string", "null" ], "enum": [ "end", "none", "restrict" ], "description": "Indicates what happens to the subscription when a renewal invoice becomes overdue. One of:\n\n- `none`: Leave the subscription as is.\n- `end`: End the subscription immediately.\n- `restrict`: Restrict the subscription's connectivity.\n\nWhen configured, this property takes precedence over the value set at the project level.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n" }, "restrictBehavior": { "type": [ "string", "null" ], "enum": [ null, "incomingOnly", "noData", "throttledData" ], "description": "Required when `invoiceOverdueAction` is `restrict`.\nDetermines how subscriptions are restricted when an invoice becomes overdue. It can have one of the following values:\n\n- `incomingOnly`: The subscription line can receive calls & SMS, but cannot make calls, send SMS, or use data.\n- `noData`: The subscription line can make and receive calls & SMS, but cannot use data.\n- `throttledData`: The subscription line can still make and receive calls & SMS, and use up to 1GB of data at a reduced speed.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n" }, "restoreBehavior": { "type": [ "string", "null" ], "enum": [ null, "keepPeriodAnchor", "resetPeriodAnchor" ], "description": "Required when `invoiceOverdueAction` is `restrict`.\nDetermines how subscriptions are restored once a subscription is restored (e.g. after payment of an overdue invoice). It can have one of the following values:\n\n- `resetPeriodAnchor`: The subscription cycle is reset to the date of restoration. This means the user has a whole new period to use their plan allowance that was just restored.\n- `keepPeriodAnchor`: The subscription cycle remains unchanged. The next renewal date stays the same as before the restriction.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n" } } }, "userAddress": { "type": "string", "description": "The unique identifier for an existing [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) to be used for the subscription.\n\nOnce a subscription has a user address it cannot be removed, only updated to a different user address. Only available for active subscriptions.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "adr_0SNlurA049MEWV5ELDmnaqVXgTFT" ] } }, "required": [] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "metadata": {}, "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": "end" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT" } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": true }, "responses": { "200": { "description": "Returns the updated subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": { "cause": "cancellationRequested", "userReason": "connectivityIssues" }, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": {}, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/subscriptions/{subscription}/cancel": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "subscription", "in": "path", "description": "The unique identifier for the subscription.", "required": true, "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } } ], "post": { "tags": [ "Subscriptions" ], "operationId": "SubscriptionsCancel", "summary": "Cancel an active subscription", "description": "Cancels a subscription. A canceled subscription still has connectivity,\nbut is no longer renewed.\n\nA canceled subscription is ended at the end of its contract term (as\ndefined by its plan) or, if it is already past the term, at the end of\nits current period.\n\nNote that the status of a subscription that has been canceled will\nremain `active` until the `endedAt` date is reached, at which point it\nwill be updated to `ended`.\n\nA subscription can only be canceled up to one hour before its renewal.\nIf it is canceled after this point, it will be ended after the\nfollowing period.\n\nA canceled subscription that hasn't yet ended can be [resumed](https://developers.gigs.com/core/subscriptions#resume-a-canceled-subscription).\n\nNote: Cancellation is rejected when the subscription might never\nactivate on its own, e.g. the porting has not been submitted to\nthe provider yet. Use the\n[end endpoint](https://developers.gigs.com/core/subscriptions#end-a-subscription)\ninstead to immediately terminate the subscription.\n", "requestBody": { "description": "Optional and required parameters to be passed in the request body to cancel a subscription.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancellationDetails": { "type": [ "object", "null" ], "description": "Details about the cancellation of the subscription.", "properties": { "userComment": { "type": [ "string", "null" ], "description": "Comment from the user explaining the cancellation reason. It is only present when the userReason is other." }, "userReason": { "type": "string", "enum": [ "connectivityIssues", "customerService", "noDetails", "other", "tooExpensive", "unused" ], "description": "Reason for the user to cancel the subscription." } }, "required": [ "userReason" ] } } }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "cancellationDetails": { "userReason": "connectivityIssues" } } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": false }, "responses": { "200": { "description": "Returns the subscription after a successful cancellation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": { "cause": "cancellationRequested", "userReason": "connectivityIssues" }, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": {}, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/subscriptions/{subscription}/portIn": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "subscription", "in": "path", "description": "The unique identifier for the subscription.", "required": true, "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } } ], "post": { "tags": [ "Subscriptions" ], "operationId": "SubscriptionsPortin", "summary": "Port a phone number into a subscription", "description": "Port a phone number into an active subscription.\n\nThe subscription remains activated and connected to the old phone number until the porting is completed.\nAfter the porting is completed, the phone number of this subscription is updated.\n\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "parameters": [], "requestBody": { "description": "The parameters to request a mid-subscription porting.", "content": { "application/json": { "schema": { "type": "object", "properties": { "porting": { "type": "string", "description": "The unique identifier for the existing draft [porting](https://developers.gigs.com/core/portings#the-porting-resource) to be requested for this subscription.", "examples": [ "prt_0SNlurA049MEWV39s2kSYqaat7ZS" ] } }, "required": [ "porting" ] }, "examples": { "Example": { "summary": "Example", "value": { "porting": "prt_0SNlurA049MEWV39s2kSYqaat7ZS" } } } } }, "required": true }, "responses": { "200": { "description": "Returns the subscription after successfully requesting the port in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": { "cause": "cancellationRequested", "userReason": "connectivityIssues" }, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": {}, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/subscriptions/{subscription}/end": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "subscription", "in": "path", "description": "The unique identifier for the subscription.", "required": true, "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } } ], "post": { "tags": [ "Subscriptions" ], "operationId": "SubscriptionsEnd", "summary": "End a subscription immediately", "description": "Ends a subscriptions immediately given its identifier.\n\nAdditionally, you can pass in optional cancellation details in the\nrequest body, which will be used to provide more context on why the\nsubscription was ended.\n", "requestBody": { "description": "Optional and required parameters to be passed in the request body to end a subscription.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancellationDetails": { "type": [ "object", "null" ], "description": "Details about the cancellation of the subscription.", "properties": { "userComment": { "type": [ "string", "null" ], "description": "Comment from the user explaining the cancellation reason. It is only present when the userReason is other." }, "userReason": { "type": "string", "enum": [ "connectivityIssues", "customerService", "noDetails", "other", "tooExpensive", "unused" ], "description": "Reason for the user to cancel the subscription." } }, "required": [ "userReason" ] } } }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "cancellationDetails": { "userReason": "connectivityIssues" } } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": false }, "responses": { "200": { "description": "Returns the ended subscription after a successful termination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": { "cause": "cancellationRequested", "userReason": "connectivityIssues" }, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": {}, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/subscriptions/{subscription}/resume": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "subscription", "in": "path", "description": "The unique identifier for the subscription.", "required": true, "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } } ], "post": { "tags": [ "Subscriptions" ], "operationId": "SubscriptionsResume", "summary": "Resume a canceled subscription", "description": "Removes the cancellation and end times of the subscription. The subscription will continue to auto-renew until canceled again.", "responses": { "200": { "description": "Returns the resumed subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": { "cause": "cancellationRequested", "userReason": "connectivityIssues" }, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": {}, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/subscriptions/search": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "post": { "tags": [ "Subscriptions" ], "operationId": "SubscriptionsSearch", "summary": "Search for subscriptions", "description": "Searches for existing subscriptions matching the given parameters.", "requestBody": { "description": "Subscription attributes to search for.", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "type": "string", "format": "E.164", "description": "The E.164-formatted phone number associated with the subscription.", "examples": [ "+12065550123" ] } }, "required": [ "phoneNumber" ] }, "examples": { "Example": { "summary": "Example", "value": { "phoneNumber": "+12065550123" } } } } }, "required": true }, "responses": { "200": { "description": "Returns a list schema response with all found subscriptions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `subscription`.", "items": { "$ref": "#/components/schemas/subscription" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": { "cause": "cancellationRequested", "userReason": "connectivityIssues" }, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "subscription", "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "metadata": {}, "activatedAt": "2021-01-21T19:38:34Z", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" }, "invoiceGracePeriodDays": 3, "invoiceOverduePeriodDays": 1, "invoiceOverdueAction": null, "restrictBehavior": null, "restoreBehavior": null }, "canceledAt": "2021-01-29T13:22:51Z", "cancellationDetails": {}, "createdAt": "2021-01-21T19:32:13Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "earliestEndAt": "2021-02-20T19:38:34Z", "endedAt": "2021-02-20T19:38:34Z", "firstUsageAt": "2021-01-21T19:38:34Z", "lastPorting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, "phoneNumber": "+19591234567", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "restoreRequestedAt": "2021-02-21T19:38:34Z", "restrictedAt": "2021-02-21T19:38:34Z", "restrictionDetails": { "restrictBehavior": "incomingOnly", "restoreBehavior": "resetPeriodAnchor", "cause": "invoiceOverdue" }, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "user": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" }, "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "porting": { "object": "porting", "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS", "accountNumber": "123456789", "accountPinExists": true, "accountType": "prepaidUnregistered", "address": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY" }, "behavior": "portIn", "billingPinExists": true, "birthday": "2017-07-21", "canceledAt": "2021-01-21T19:39:53Z", "completedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "declinedAttempts": 0, "declinedCode": "portingPhoneNumberPortProtected", "declinedMessage": "The phone number has port protection on the provider.", "donorProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "donorProviderApproval": true, "expiredAt": "2021-01-21T19:39:53Z", "failedAt": "2021-01-21T19:39:53Z", "failureReason": "consentNotGiven", "firstName": "Jerry", "lastDeclinedAt": "2021-01-21T19:31:13Z", "lastName": "Seinfeld", "lastRequestedAt": "2021-01-21T19:22:31Z", "phoneNumber": "+19591234567", "provider": "p9", "recipientProvider": { "object": "serviceProvider", "id": "svp_0SNlurA01K6GY5L0XJffY8", "country": "US", "name": "AT&T", "recipientProviders": [ "p3" ] }, "requestBehavior": "automatic", "required": [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ], "scheduledOn": "2021-01-21", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/subscriptionAddons": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Subscription Add-ons" ], "operationId": "SubscriptionAddonsList", "summary": "List all subscription add-ons", "description": "Returns a list of subscription add-ons. The subscription add-ons returned are sorted by creation date, with the most recently created subscription add-ons appearing first.", "parameters": [ { "name": "addon", "in": "query", "description": "The unique identifier for the add-on to be filtered by.", "schema": { "type": "string", "examples": [ "add_0SNlurA049MEWV4VxLfwJc7PJtHc" ] } }, { "name": "status", "in": "query", "description": "A comma-separated list of statuses to filter the subscription add-ons by.", "schema": { "type": "array", "default": [ "pending", "initiated", "active" ], "items": { "type": "string", "enum": [ "pending", "initiated", "active", "ended" ] } }, "style": "form", "explode": false }, { "name": "subscription", "in": "query", "description": "The unique identifier for the subscription to be filtered by.", "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, { "name": "user", "in": "query", "description": "The unique identifier for the user to be filtered by.", "schema": { "type": "string", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of subscription add-ons.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `subscriptionAddon`.", "items": { "$ref": "#/components/schemas/subscriptionAddon" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "subscriptionAddon", "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "activatedAt": "2021-01-15T12:36:57Z", "addon": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7, "totalPeriods": 1 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" } }, "canceledAt": "2021-01-22T19:39:53Z", "createdAt": "2021-01-15T12:30:28Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "endedAt": "2021-01-30T23:12:28Z", "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "subscriptionAddon", "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "activatedAt": "2021-01-15T12:36:57Z", "addon": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" } }, "canceledAt": "2021-01-22T19:39:53Z", "createdAt": "2021-01-15T12:30:28Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "endedAt": "2021-01-30T23:12:28Z", "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } }, "post": { "tags": [ "Subscription Add-ons" ], "operationId": "SubscriptionAddonsCreate", "summary": "Create a subscription add-on", "description": "Creates a new subscription add-on for an existing subscription in the specified project.\n\nOn projects with billing enabled, the subscription may still be activating (status `initiated` or `pending`). The add-on is invoiced right away and activates once its invoice is paid and the subscription is active.\n", "requestBody": { "description": "Required parameters to be passed in the request body to create a new subscription add-on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "addon": { "type": "string", "description": "Unique identifier of the add-on.", "examples": [ "add_0SNlurA049MEWV4VxLfwJc7PJtHc" ] }, "billing": { "type": [ "object", "null" ], "description": "Configuration for this specific subscription add-on billing. Only available when the Billing API is enabled.", "properties": { "discount": { "type": [ "object", "null" ], "description": "Discount to apply to the subscription add-on.", "properties": { "voucher": { "type": [ "string", "null" ], "description": "The unique identifier for the existing [voucher](https://developers.gigs.com/api/latest/billing/vouchers) of the subscription add-on. A voucher applies a discount to the price of a subscription add-on.", "examples": [ "vou_0SNlurA049MEWV0h2jfjkdiOdplN" ] } } }, "paymentBehavior": { "type": [ "string", "null" ], "enum": [ "manual", "none" ], "description": "Determines how invoices are paid for this subscription add-on. It can have one of the following values:\n\n- `manual`: Invoices are not automatically paid without explicit action.\n- `none`: No payment is performed and invoices are marked as paid automatically.\n\nWhen configured, this property takes precedence over the value set at the project level.\n", "examples": [ "manual" ] } } }, "subscription": { "type": [ "string" ], "description": "Unique identifier of the subscription the add-on applies to.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, "required": [ "addon", "subscription" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN" }, "paymentBehavior": "manual" }, "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } }, "Example - Required": { "summary": "Example - Required", "value": { "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } } } } }, "required": true }, "responses": { "201": { "description": "Returns the newly created subscription add-on.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscriptionAddon" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "subscriptionAddon", "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "activatedAt": "2021-01-15T12:36:57Z", "addon": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7, "totalPeriods": 1 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" } }, "canceledAt": "2021-01-22T19:39:53Z", "createdAt": "2021-01-15T12:30:28Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "endedAt": "2021-01-30T23:12:28Z", "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "subscriptionAddon", "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "activatedAt": "2021-01-15T12:36:57Z", "addon": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" } }, "canceledAt": "2021-01-22T19:39:53Z", "createdAt": "2021-01-15T12:30:28Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "endedAt": "2021-01-30T23:12:28Z", "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/subscriptionAddons/{subscriptionAddon}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "subscriptionAddon", "in": "path", "description": "The unique identifier for the subscription add-on.", "required": true, "schema": { "type": "string", "examples": [ "sad_0SNlurA049MEWV2UNWPbDfW5B40U" ] } } ], "get": { "tags": [ "Subscription Add-ons" ], "operationId": "SubscriptionAddonsRetrieve", "summary": "Retrieve a subscription add-on", "description": "Retrieve the details of an existing subscription add-on which the authenticated user is authorized to view.", "responses": { "200": { "description": "Returns the subscription add-on if it exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscriptionAddon" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "subscriptionAddon", "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "activatedAt": "2021-01-15T12:36:57Z", "addon": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7, "totalPeriods": 1 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" } }, "canceledAt": "2021-01-22T19:39:53Z", "createdAt": "2021-01-15T12:30:28Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "endedAt": "2021-01-30T23:12:28Z", "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "subscriptionAddon", "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "activatedAt": "2021-01-15T12:36:57Z", "addon": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" } }, "canceledAt": "2021-01-22T19:39:53Z", "createdAt": "2021-01-15T12:30:28Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "endedAt": "2021-01-30T23:12:28Z", "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } }, "delete": { "tags": [ "Subscription Add-ons" ], "operationId": "SubscriptionAddonsEnd", "summary": "End a subscription add-on", "description": "Ends a subscription add-on immediately. Subscription add-ons that are already ended cannot be ended again.", "responses": { "200": { "description": "Returns the ended subscription add-on.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscriptionAddon" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "subscriptionAddon", "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "activatedAt": "2021-01-15T12:36:57Z", "addon": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7, "totalPeriods": 1 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" } }, "canceledAt": "2021-01-22T19:39:53Z", "createdAt": "2021-01-15T12:30:28Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "endedAt": "2021-01-30T23:12:28Z", "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "subscriptionAddon", "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "activatedAt": "2021-01-15T12:36:57Z", "addon": { "object": "addon", "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:12:28Z", "description": "Disable international roaming.", "limits": { "dataBytes": 13000000000, "throttling": { "thresholdBytes": 3000000000, "bandwidthBitsPerSecond": 256000 } }, "name": "1GB Data Top-up", "plans": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ], "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "recurrenceType": "oneTime", "status": "draft", "type": "topUp", "validity": { "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "billing": { "discount": { "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "expiresAt": "2021-02-20T19:38:34Z" } }, "canceledAt": "2021-01-22T19:39:53Z", "createdAt": "2021-01-15T12:30:28Z", "currentPeriod": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "endedAt": "2021-01-30T23:12:28Z", "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/subscriptionChanges": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Subscription Changes" ], "operationId": "SubscriptionChangesList", "summary": "List all subscription changes", "description": "Returns a list of subscription changes. The subscription changes returned are sorted by creation date, with the most recently created subscription changes appearing first.", "parameters": [ { "name": "status", "in": "query", "description": "A comma-separated list of statuses to filter the subscription changes by.", "schema": { "type": "array", "default": [ "pending", "initiated" ], "items": { "type": "string", "enum": [ "pending", "initiated", "applied", "failed", "deleted" ] } }, "style": "form", "explode": false }, { "name": "subscription", "in": "query", "description": "The unique identifier for the subscription to be filtered by.", "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, { "name": "user", "in": "query", "description": "The unique identifier for the user to be filtered by.", "schema": { "type": "string", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of subscription changes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `subscriptionChange`.", "items": { "$ref": "#/components/schemas/subscriptionChange" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "subscriptionChange", "id": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "appliedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "failureCode": "consentNotGiven", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "requestedChange": { "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "sim": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "phoneNumber": "auto", "when": "renewal" }, "scheduledAt": "2021-01-21T19:12:28Z", "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "subscriptionChange", "id": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "appliedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "failureCode": "consentNotGiven", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "requestedChange": { "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "sim": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "phoneNumber": "auto", "when": "renewal" }, "scheduledAt": "2021-01-21T19:12:28Z", "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } }, "post": { "tags": [ "Subscription Changes" ], "operationId": "SubscriptionChangesCreate", "summary": "Create a subscription change", "description": "Creates a new subscription change for an existing subscription in the specified project.\n\nNote that plan changes cannot be created within the cutoff period of 1 hour before the subscription period ends. In the UK, this cutoff period is extended to 13 hours but only for changes scheduled at renewal.\n", "parameters": [], "requestBody": { "description": "Required parameters to be passed in the request body to create a new subscription change:", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": [ "string", "null" ], "description": "Unique identifier of the target plan, to which the subscription should be changed.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] }, "sim": { "type": [ "string", "null" ], "description": "Unique identifier of the target SIM, to which the subscription should be changed. Can also be set to \"auto\", in which case an eSIM will be automatically allocated.", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] }, "phoneNumber": { "type": [ "string", "null" ], "description": "Requests a change of the subscription's phone number. Only \"auto\" is supported: the network provider assigns a new random number. Mutually exclusive with `plan` and `sim`, and only valid with `when` set to \"now\". Changing the phone number is only available for a subset of network providers.", "examples": [ "auto" ] }, "subscription": { "type": "string", "description": "Unique identifier of the subscription to be changed.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] }, "when": { "type": "string", "enum": [ "now", "renewal" ], "default": "renewal", "description": "When the change should take effect. If set to `\"now\"`, the change will take effect immediately. If set to `\"renewal\"`, the change will instead take effect at the next subscription renewal date. Plan changes can always happen on `\"renewal\"`, but only selected network providers allow `\"now\"` changes. SIM changes can only happen `\"now\"`.", "examples": [ "renewal" ] } }, "required": [ "subscription" ] }, "examples": { "Plan change": { "summary": "Plan change", "value": { "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "when": "renewal" } }, "SIM change": { "summary": "SIM change", "value": { "sim": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "when": "now" } }, "Phone number change": { "summary": "Phone number change", "value": { "phoneNumber": "auto", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "when": "now" } } } } }, "required": true }, "responses": { "201": { "description": "Returns the newly created subscription change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscriptionChange" }, "examples": { "Plan change": { "summary": "Plan change", "value": { "object": "subscriptionChange", "id": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "appliedAt": null, "createdAt": "2021-01-21T19:12:28Z", "failureCode": null, "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "requestedChange": { "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "sim": null, "phoneNumber": null, "when": "renewal" }, "scheduledAt": "2021-01-21T19:12:28Z", "sim": null, "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } }, "SIM change": { "summary": "SIM change", "value": { "object": "subscriptionChange", "id": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "appliedAt": null, "createdAt": "2021-01-21T19:12:28Z", "failureCode": null, "plan": null, "requestedChange": { "plan": null, "sim": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "phoneNumber": null, "when": "now" }, "scheduledAt": null, "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } }, "Phone number change": { "summary": "Phone number change", "value": { "object": "subscriptionChange", "id": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "appliedAt": null, "createdAt": "2021-01-21T19:12:28Z", "failureCode": null, "plan": null, "requestedChange": { "plan": null, "sim": null, "phoneNumber": "auto", "when": "now" }, "scheduledAt": null, "sim": null, "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/subscriptionChanges/{subscriptionChange}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "subscriptionChange", "in": "path", "description": "The unique identifier for the subscription change.", "required": true, "schema": { "type": "string", "examples": [ "sch_0SNlurA049MEWV3bE0SMtbIEJApp" ] } } ], "get": { "tags": [ "Subscription Changes" ], "operationId": "SubscriptionChangesRetrieve", "summary": "Retrieve a subscription change", "description": "Retrieve the details of an existing subscription change which the authenticated user is authorized to view.", "responses": { "200": { "description": "Returns the subscription change if it exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscriptionChange" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "subscriptionChange", "id": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "appliedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "failureCode": "consentNotGiven", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "requestedChange": { "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "sim": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "phoneNumber": "auto", "when": "renewal" }, "scheduledAt": "2021-01-21T19:12:28Z", "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "subscriptionChange", "id": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "appliedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "failureCode": "consentNotGiven", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "requestedChange": { "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "sim": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "phoneNumber": "auto", "when": "renewal" }, "scheduledAt": "2021-01-21T19:12:28Z", "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } }, "delete": { "tags": [ "Subscription Changes" ], "operationId": "SubscriptionChangesDelete", "summary": "Delete a subscription change", "description": "Retrieve the details of an existing subscription change and delete it. Only subscription changes that have not been applied can be deleted.", "responses": { "200": { "description": "Returns the subscription change after a successful deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscriptionChange" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "subscriptionChange", "id": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "appliedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "failureCode": "consentNotGiven", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "requestedChange": { "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "sim": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "phoneNumber": "auto", "when": "renewal" }, "scheduledAt": "2021-01-21T19:12:28Z", "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "subscriptionChange", "id": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "appliedAt": "2021-01-21T19:36:57Z", "createdAt": "2021-01-21T19:12:28Z", "failureCode": "consentNotGiven", "plan": { "object": "plan", "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "metadata": {}, "activationTrigger": "creation", "allowances": { "dataBytes": 10000000000, "voiceSeconds": 30000, "smsMessages": 100 }, "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "createdAt": "2021-01-21T19:38:34Z", "description": "A data plan you will love! Operates in most countries of the world.", "firstPeriodTrigger": "creation", "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png", "limits": { "dataBytes": 100000000000, "bandwidthBitsPerSecond": 100000000, "throttling": { "thresholdBytes": 10000000000, "bandwidthBitsPerSecond": 512000 } }, "name": "Gigs Global", "price": { "amount": 999, "currency": "USD" }, "provider": "p5", "requirements": { "address": "present", "device": "none", "user.birthday": "none", "user.fullName": "present" }, "simTypes": [ "eSIM", "pSIM" ], "status": "available", "validity": { "minimumPeriods": 12, "type": "recurring", "unit": "day", "value": 7 }, "data": 10000000000, "dataUnit": "byte", "sms": 100, "smsUnit": "message", "voice": 30000, "voiceUnit": "second" }, "requestedChange": { "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "sim": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "phoneNumber": "auto", "when": "renewal" }, "scheduledAt": "2021-01-21T19:12:28Z", "sim": { "object": "sim", "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6", "metadata": {}, "createdAt": "2021-01-21T19:38:34Z", "iccid": "89883070000007537119", "provider": "p9", "status": "inactive", "suspension": null, "type": "eSIM" }, "status": "pending", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/subscriptions/{subscription}/usage": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "subscription", "in": "path", "description": "The unique identifier for the subscription.", "required": true, "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } } ], "get": { "tags": [ "Usage" ], "operationId": "SubscriptionUsageList", "summary": "List subscription usage records", "description": "Lists usage records in ascending order for a subscription, defaulting to `daily` aggregation for the latest subscription period. If none of the `start`, `end`, or `period` parameters is provided, records are returned for the latest subscription period.", "parameters": [ { "name": "period", "in": "query", "description": "Limits the usage data returned to the subscription period provided. This option is incompatible with the `start` and `end` parameters.", "schema": { "type": "integer", "minimum": 1, "examples": [ 12 ] } }, { "name": "start", "in": "query", "description": "Limits the usage data to dates greater than or equal to the provided date. Can only be used in combination with `end`.", "schema": { "type": "string", "format": "date", "examples": [ "2021-06-19" ] } }, { "name": "end", "in": "query", "description": "Limits the usage data to dates up to and including the provided date. Can only be used in combination with `start`.", "schema": { "type": "string", "format": "date", "examples": [ "2021-11-14" ] } }, { "name": "aggregation", "in": "query", "description": "Determines the aggregation method used, defaulting to `daily`. `period` provides aggregated values for the time range or period requested. The `roaming` aggregation is in preview and may only be used in particular cases.", "schema": { "type": "string", "enum": [ "daily", "period", "country", "roaming", "daily,country", "daily,roaming", "period,country", "period,roaming", "country,daily", "country,period", "roaming,daily", "roaming,period" ] } } ], "responses": { "200": { "description": "Returns the list of usage records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `usageRecord`.", "items": { "$ref": "#/components/schemas/usageRecord" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "usageRecord", "data": 18883100, "dataDeviceBytes": 30029300, "dataTetheringBytes": 30029300, "end": "2021-02-15T00:00:00Z", "labels": { "country": "US", "roaming": "none", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" }, "sms": 15, "smsInternationalMessages": 6, "smsLocalMessages": 6, "start": "2021-02-14T00:00:00Z", "updatedAt": "2024-02-15T12:13:14Z", "voice": 240, "voiceInternationalSeconds": 125, "voiceLocalSeconds": 6 } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "usageRecord", "data": 18883100, "end": "2021-02-15T00:00:00Z", "labels": {}, "sms": 15, "start": "2021-02-14T00:00:00Z", "voice": 240 } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/usageBalances": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Usage Balances" ], "operationId": "UsageBalancesList", "summary": "List all usage balances", "description": "Returns a list of usage balances for the given project. The list can be filtered by subscription, subscription period, or subscription add-on. When filtering by subscription without specifying subscriptionPeriod or subscriptionAddon, all usage balances for the subscription are returned regardless of source type or period.\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "parameters": [ { "name": "subscription", "in": "query", "description": "Filter usage balances by [Subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource) ID.", "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, { "name": "subscriptionPeriod", "in": "query", "description": "Filter usage balances by subscription period. Requires the `subscription` parameter. Accepts a positive integer, the special value `current`, or a negative integer to request previous periods (e.g., `-1` for the previous period). Cannot be combined with `subscriptionAddon`. A usage balance is sourced from either a subscription period or a subscription add-on, never both - combining these will return an error.", "schema": { "type": "string", "examples": [ "current" ] } }, { "name": "subscriptionAddon", "in": "query", "description": "Filter usage balances by [Subscription Add-on](https://developers.gigs.com/core/subscription-add-ons#the-subscription-add-on-resource) ID. Can be combined with `subscription` but not with `subscriptionPeriod`. A usage balance is sourced from either a subscription period or a subscription add-on, never both — combining these will return an error.", "schema": { "type": "string", "examples": [ "sad_0SNlurA049MEWV2UNWPbDfW5B40U" ] } }, { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a list of usage balances.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `usageBalance`.", "items": { "$ref": "#/components/schemas/usageBalance" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "usageBalance", "id": "ubl_0V9n0zo90CE0NuvcsN0j88", "allowance": { "object": "allowance", "id": "alw_0SNlurA049MEWV3OMTRrGKbd99GH", "name": "Roaming data in Europe", "type": "data", "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "limit": 500, "unit": "bytes" }, "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "source": { "type": "subscriptionPeriod", "subscriptionPeriod": 4, "subscriptionAddon": null }, "unit": "bytes", "used": 230, "limit": 500, "remaining": 270, "usedPercent": 46, "remainingPercent": 54, "usableFrom": "2026-01-03T13:41:24Z", "usableUntil": "2026-02-03T13:41:24Z" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "usageBalance", "id": "ubl_0V9n0zo90CE0NuvcsN0j88", "allowance": { "object": "allowance", "id": "alw_0SNlurA049MEWV3OMTRrGKbd99GH", "name": "Roaming data in Europe", "type": "data", "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "limit": 500, "unit": "bytes" }, "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "source": { "type": "subscriptionPeriod", "subscriptionPeriod": 4, "subscriptionAddon": null }, "unit": "bytes", "used": 230, "limit": 500, "remaining": 270, "usedPercent": 46, "remainingPercent": 54, "usableFrom": "2026-01-03T13:41:24Z", "usableUntil": "2026-02-03T13:41:24Z" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" } } } }, "/projects/{project}/usageBalances/{usageBalance}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "usageBalance", "in": "path", "description": "The unique identifier for the usage balance.", "required": true, "schema": { "type": "string", "examples": [ "ubl_0V9n0zo90CE0NuvcsN0j88" ] } } ], "get": { "tags": [ "Usage Balances" ], "operationId": "UsageBalancesRetrieve", "summary": "Retrieve a usage balance", "description": "Returns the details of an existing usage balance.\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "responses": { "200": { "description": "Returns the usage balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usageBalance" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "usageBalance", "id": "ubl_0V9n0zo90CE0NuvcsN0j88", "allowance": { "object": "allowance", "id": "alw_0SNlurA049MEWV3OMTRrGKbd99GH", "name": "Roaming data in Europe", "type": "data", "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "limit": 500, "unit": "bytes" }, "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "source": { "type": "subscriptionPeriod", "subscriptionPeriod": 4, "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U" }, "unit": "bytes", "used": 230, "limit": 500, "remaining": 270, "usedPercent": 46, "remainingPercent": 54, "usableFrom": "2026-01-03T13:41:24Z", "usableUntil": "2026-02-03T13:41:24Z" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "usageBalance", "id": "ubl_0V9n0zo90CE0NuvcsN0j88", "allowance": { "object": "allowance", "id": "alw_0SNlurA049MEWV3OMTRrGKbd99GH", "name": "Roaming data in Europe", "type": "data", "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "limit": 500, "unit": "bytes" }, "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "source": { "type": "subscriptionPeriod" }, "unit": "bytes", "used": 230, "limit": 500, "remaining": 270, "usedPercent": 46, "remainingPercent": 54, "usableFrom": "2026-01-03T13:41:24Z", "usableUntil": "2026-02-03T13:41:24Z" } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" } } } }, "/testing/projects/{project}/portOuts/{portOut}/simulate": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "portOut", "in": "path", "description": "The unique identifier for the port out.", "required": true, "schema": { "type": "string", "examples": [ "pto_0SNlurA049MEWV4DWEaT4SaeDI8s" ] } } ], "post": { "tags": [ "Port Outs" ], "operationId": "PortOutsSimulate", "summary": "Simulate port out completion by network provider", "description": "Simulates completion of a port out for a subscription with a test SIM. Can be used to test complete flow of a successful port out with end of subscription.\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "responses": { "200": { "description": "Port out completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/portOut" }, "examples": { "Example": { "summary": "Example", "value": { "object": "portOut", "id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s", "behavior": "portOut", "completedAt": "2022-02-21T19:38:34Z", "createdAt": "2020-01-01T00:00:00Z", "expirationRequestedAt": "2022-02-21T19:38:12Z", "expiredAt": "2022-02-21T19:38:34Z", "failureReason": "consentNotGiven", "status": "issued", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/testing/projects/{project}/subscriptions/{subscription}/usage": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "subscription", "in": "path", "description": "The unique identifier for the subscription.", "required": true, "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } } ], "post": { "tags": [ "Usage" ], "operationId": "SubscriptionUsageSimulate", "summary": "Simulate subscription usage", "description": "Simulates usage on a subscription with a test SIM. Can be used to test usage notifications. Subscription must be in status \"active\".\n\n\n> #### Preview\n>\n> This endpoint is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "requestBody": { "description": "Usage parameters to simulate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "integer", "null" ], "default": 0, "description": "Amount of data used in bytes.", "minimum": 0, "examples": [ 18883100 ] }, "dataDevice": { "type": [ "integer", "null" ], "default": 0, "description": "Amount of on-device data used in bytes.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "minimum": 0, "examples": [ 102938120 ] }, "dataTethering": { "type": [ "integer", "null" ], "default": 0, "description": "Amount of tethering data used in bytes.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "minimum": 0, "examples": [ 102938120 ] }, "voice": { "type": [ "integer", "null" ], "default": 0, "description": "Amount of voice usage in seconds.", "minimum": 0, "examples": [ 240 ] }, "voiceLocal": { "type": [ "integer", "null" ], "default": 0, "description": "Amount of local voice usage in seconds.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "minimum": 0, "examples": [ 329 ] }, "voiceInternational": { "type": [ "integer", "null" ], "default": 0, "description": "Amount of international long distance voice usage in seconds.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "minimum": 0, "examples": [ 329 ] }, "sms": { "type": [ "integer", "null" ], "default": 0, "description": "Amount of SMS messages sent and received.", "minimum": 0, "examples": [ 15 ] }, "smsLocal": { "type": [ "integer", "null" ], "default": 0, "description": "Amount of local SMS messages sent and received.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "minimum": 0, "examples": [ 4 ] }, "smsInternational": { "type": [ "integer", "null" ], "default": 0, "description": "Amount of international long distance SMS messages sent and received.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "minimum": 0, "examples": [ 4 ] }, "subscriptionAddon": { "type": [ "string", "null" ], "description": "The unique identifier for the subscription addon to which the simulated usage should be attributed. If not provided, the usage won't be attributed to any add-on.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "sad_0SNlurA049MEWV2UNWPbDfW5B40U" ] }, "country": { "type": [ "string", "null" ], "format": "ISO 3166-1 alpha-2", "description": "The ISO 3166-1 alpha-2 country code to assign to the simulated usage. If not provided, the usage will be assigned to the home country of the provider.", "examples": [ "US" ] }, "roaming": { "type": [ "string", "null" ], "enum": [ "none", "international", "domestic" ], "default": "none", "description": "The roaming mode to assign to the simulated usage.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n" }, "usageBalance": { "type": [ "string", "null" ], "description": "The Usage Balance id to assign the simulated usage to.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "ubl_0SNlurA049MEWV4VxLfwJc3PJtHc" ] }, "usageBalanceAmount": { "type": [ "integer", "null" ], "description": "The amount of usage to attribute to the specified Usage Balance.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n" } } }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "data": 18883100, "dataDevice": 102938120, "dataTethering": 102938120, "voice": 240, "voiceLocal": 329, "voiceInternational": 329, "sms": 15, "smsLocal": 4, "smsInternational": 4, "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "country": "US", "roaming": "none", "usageBalance": "ubl_0SNlurA049MEWV4VxLfwJc3PJtHc" } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": true }, "responses": { "201": { "description": "Returns the relevant usage record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usageRecord" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "usageRecord", "data": 18883100, "dataDeviceBytes": 30029300, "dataTetheringBytes": 30029300, "end": "2021-02-15T00:00:00Z", "labels": { "country": "US", "roaming": "none", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi" }, "sms": 15, "smsInternationalMessages": 6, "smsLocalMessages": 6, "start": "2021-02-14T00:00:00Z", "updatedAt": "2024-02-15T12:13:14Z", "voice": 240, "voiceInternationalSeconds": 125, "voiceLocalSeconds": 6 } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "usageRecord", "data": 18883100, "end": "2021-02-15T00:00:00Z", "labels": {}, "sms": 15, "start": "2021-02-14T00:00:00Z", "voice": 240 } } } } } }, "403": { "$ref": "#/components/responses/permissionDenied" }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/users/{user}/addresses/{address}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "$ref": "#/components/parameters/user" }, { "name": "address", "in": "path", "description": "The unique identifier for the address.", "required": true, "schema": { "type": "string", "examples": [ "adr_0SNlurA049MEWV5ELDmnaqVXgTFT" ] } } ], "get": { "tags": [ "User Addresses" ], "operationId": "UserAddressesRetrieve", "summary": "Retrieve a user address", "description": "Retrieves the details of an existing address for a given user.", "responses": { "200": { "description": "Returns the address if it exists and is owned by the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/userAddress" }, "examples": { "Example": { "summary": "Example", "value": { "object": "userAddress", "id": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "city": "New York City", "country": "US", "createdAt": "2021-01-21T19:38:34Z", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } }, "delete": { "tags": [ "User Addresses" ], "operationId": "UserAddressesDelete", "summary": "Delete a user address", "description": "Retrieves the details of an existing user address and deletes it.", "responses": { "200": { "description": "Returns the address after a successful deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/userAddress" }, "examples": { "Example": { "summary": "Example", "value": { "object": "userAddress", "id": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "city": "New York City", "country": "US", "createdAt": "2021-01-21T19:38:34Z", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/users/{user}/addresses": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "$ref": "#/components/parameters/user" } ], "get": { "tags": [ "User Addresses" ], "operationId": "UserAddressesList", "summary": "List all user addresses", "description": "Returns a list of addresses owned by the given user. The addresses returned are sorted by creation date, with the most recently created addresses appearing first.", "responses": { "200": { "description": "Returns a list of address objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `userAddress`.", "items": { "$ref": "#/components/schemas/userAddress" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "userAddress", "id": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "city": "New York City", "country": "US", "createdAt": "2021-01-21T19:38:34Z", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "userAddress", "id": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "city": "New York City", "country": "US", "createdAt": "2021-01-21T19:38:34Z", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } }, "post": { "tags": [ "User Addresses" ], "operationId": "UserAddressesCreate", "summary": "Create a user address", "description": "Create a new address for the given user with the provided parameters.\n\nIf any validations fail during the user address creation process,\ndetailed information will be provided in the error response body.\nIf applicable, suggested alternative values for properties that do not\npass the validations will also be included.\n\nPlease note that there is a maximum limit of 10 active addresses permitted per user.\nAttempts to exceed this limit will result in an error response. Addresses must also\nbe unique for a given user.\n", "requestBody": { "description": "User address attributes to create.", "content": { "application/json": { "schema": { "type": "object", "properties": { "city": { "type": "string", "description": "The city/municipality of the address.", "maxLength": 50, "examples": [ "New York City" ] }, "country": { "type": "string", "format": "ISO 3166-1 alpha-2", "description": "The ISO 3166-1 alpha-2 country code of the address.", "examples": [ "US" ] }, "line1": { "type": "string", "description": "The first line of the address, e.g. street and house number.", "maxLength": 50, "examples": [ "129 West 81st Street" ] }, "line2": { "type": [ "string", "null" ], "description": "The second line of the address, e.g. apartment number.", "maxLength": 50, "examples": [ "Apartment 5" ] }, "state": { "type": [ "string", "null" ], "description": "The state/province/region of the address. Required for US/CA addresses to be a valid ISO 3166-2 2 letter code.", "maxLength": 50, "examples": [ "NY" ] }, "postalCode": { "type": [ "string", "null" ], "description": "The postal code of the address. Required for countries with postal codes.", "maxLength": 15, "examples": [ "10024" ] } }, "required": [ "city", "country", "line1" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "city": "New York City", "country": "US", "line1": "129 West 81st Street", "line2": "Apartment 5", "state": "NY", "postalCode": "10024" } }, "Example - Required": { "summary": "Example - Required", "value": { "city": "New York City", "country": "US", "line1": "129 West 81st Street" } } } } }, "required": true }, "responses": { "201": { "description": "Returns the created address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/userAddress" }, "examples": { "Example": { "summary": "Example", "value": { "object": "userAddress", "id": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "city": "New York City", "country": "US", "createdAt": "2021-01-21T19:38:34Z", "line1": "129 West 81st Street", "line2": "Apartment 5", "postalCode": "10024", "state": "NY", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "description": "The address creation request can't be processed, due to an invalid parameter or incompatible system state.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error" }, { "type": "object", "properties": { "code": { "type": "string", "examples": [ "userAddressInvalid" ] }, "details": { "type": "array", "description": "Optional array containing specific information for the current error. Please note that this will only be populated for US addresses for now.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "items": { "allOf": [ { "$ref": "#/components/schemas/propertyErrorDetailError" }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "addressPropertyInvalid", "addressPropertyIncomplete" ], "examples": [ "addressPropertyInvalid" ] }, "message": { "type": "string", "enum": [ "Invalid value for property.", "The value for this property is incomplete or missing." ], "examples": [ "Invalid value for property." ] }, "property": { "type": "string", "enum": [ "city", "country", "line1", "line2", "state", "postalCode" ], "examples": [ "city" ] }, "suggestion": { "type": [ "string", "null" ], "description": "Suggested alternative to correct the corresponding property.\n\nFor example, if the value on the city field has a typo, such as\n`San Francis`, the suggestion value would read `San Francisco`.\nIf there is no available suggestion, the value will be `null`.\n" } } } ], "type": "object" } }, "message": { "type": "string", "examples": [ "The given address is not valid." ] } } } ], "type": "object" }, "examples": { "Invalid address response with suggestions and a missing field": { "summary": "Invalid address response with suggestions and a missing field", "value": { "object": "error", "code": "userAddressInvalid", "details": [ { "object": "propertyErrorDetail", "code": "addressPropertyInvalid", "message": "Invalid value for property.", "property": "city", "suggestion": "New York City" }, { "object": "propertyErrorDetail", "code": "addressPropertyInvalid", "message": "Invalid value for property.", "property": "line1", "suggestion": "129 West 81st Street" }, { "object": "propertyErrorDetail", "code": "addressPropertyInvalid", "message": "Invalid value for property.", "property": "postalCode", "suggestion": "10024" }, { "object": "propertyErrorDetail", "code": "addressPropertyInvalid", "message": "Invalid value for property.", "property": "state", "suggestion": "NY" } ], "message": "The given address is not valid.", "type": "invalid" } }, "Invalid address response with no correction suggestions": { "summary": "Invalid address response with no correction suggestions", "value": { "object": "error", "code": "userAddressInvalid", "message": "The given address is not valid.", "type": "invalid" } } } } } } } } }, "/projects/{project}/users": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "get": { "tags": [ "Users" ], "operationId": "UsersList", "summary": "List all users", "description": "Returns a list of users. The users returned are sorted by creation date, with the most recently created users appearing first.", "parameters": [ { "$ref": "#/components/parameters/listAfter" }, { "$ref": "#/components/parameters/listBefore" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of user objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `user`.", "items": { "$ref": "#/components/schemas/user" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } } } }, "post": { "tags": [ "Users" ], "operationId": "UsersCreate", "summary": "Create a user", "description": "Creates a new user with the given parameters.", "requestBody": { "description": "User attributes to create.", "content": { "application/json": { "schema": { "type": "object", "properties": { "birthday": { "type": [ "string", "null" ], "format": "date", "description": "The birthday of the user.", "examples": [ "2017-07-21" ] }, "email": { "type": "string", "format": "email", "description": "The primary verified email address of the user.", "examples": [ "jerry@example.com" ] }, "fullName": { "type": [ "string", "null" ], "description": "The user's full name. Some plans require the user name to be present when creating a subscription. Check the plan requirements for that.", "examples": [ "Jerry Seinfeld" ] }, "metadata": { "$ref": "#/components/schemas/metadataUpdate" }, "preferredLocale": { "type": [ "string", "null" ], "description": "The user's locale preference represented as an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag). It defaults to the project's preferred locale.", "examples": [ "en-US" ] } }, "required": [ "email" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "birthday": "2017-07-21", "email": "jerry@example.com", "fullName": "Jerry Seinfeld", "metadata": {}, "preferredLocale": "en-US" } }, "Example - Required": { "summary": "Example - Required", "value": { "email": "jerry@example.com" } } } } }, "required": true }, "responses": { "201": { "description": "Returns the created user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" }, "examples": { "Example": { "summary": "Example", "value": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } } } } } }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/users/{user}": { "parameters": [ { "$ref": "#/components/parameters/project" }, { "name": "user", "in": "path", "description": "The unique identifier for the user.", "required": true, "schema": { "type": "string", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } } ], "get": { "tags": [ "Users" ], "operationId": "UsersRetrieve", "summary": "Retrieve a user", "description": "Retrieves the details of an existing user. You need only supply the unique user identifier that was returned upon user creation.", "responses": { "200": { "description": "Returns the user object if the user exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" }, "examples": { "Example": { "summary": "Example", "value": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } } } } } }, "404": { "$ref": "#/components/responses/notFound" } } }, "delete": { "tags": [ "Users" ], "operationId": "UsersDelete", "summary": "Delete a user", "description": "Retrieves the details of an existing user and deletes it.", "responses": { "200": { "description": "Returns the user after a successful deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" }, "examples": { "Example": { "summary": "Example", "value": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } }, "patch": { "tags": [ "Users" ], "operationId": "UsersUpdate", "summary": "Update a user", "description": "Updates the specified user by setting the values of the parameters passed.", "requestBody": { "description": "User attributes to update.", "content": { "application/json": { "schema": { "type": "object", "properties": { "birthday": { "type": [ "string", "null" ], "format": "date", "description": "The birthday of the user.", "examples": [ "2017-07-21" ] }, "email": { "type": [ "string", "null" ], "format": "email", "description": "The primary verified email address of the user.", "examples": [ "jerry@example.com" ] }, "fullName": { "type": [ "string", "null" ], "description": "The user's full name. Required for some Plans.", "examples": [ "Jerry Seinfeld" ] }, "metadata": { "$ref": "#/components/schemas/metadataUpdate" }, "preferredLocale": { "type": [ "string", "null" ], "description": "The user's locale preference represented as an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag).", "examples": [ "en-US" ] } }, "required": [] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "birthday": "2017-07-21", "email": "jerry@example.com", "fullName": "Jerry Seinfeld", "metadata": {}, "preferredLocale": "en-US" } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": true }, "responses": { "200": { "description": "Returns the updated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" }, "examples": { "Example": { "summary": "Example", "value": { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/users/search": { "parameters": [ { "$ref": "#/components/parameters/project" } ], "post": { "tags": [ "Users" ], "operationId": "UsersSearch", "summary": "Search for users", "description": "Searches for existing users matching the given parameters.", "requestBody": { "description": "User attributes to search by.", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "format": "email", "description": "The primary email address of the user.", "examples": [ "jerry@example.com" ] } } }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "email": "jerry@example.com" } }, "Example - Required": { "summary": "Example - Required", "value": {} } } } }, "required": true }, "responses": { "200": { "description": "Returns the users matching the search criteria.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `user`.", "items": { "$ref": "#/components/schemas/user" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "user", "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "metadata": {}, "birthday": "2017-07-21", "createdAt": "2021-01-21T19:38:34Z", "email": "jerry@example.com", "emailVerified": true, "fullName": "Jerry Seinfeld", "preferredLocale": "en-US", "status": "active" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "404": { "$ref": "#/components/responses/notFound" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } } }, "components": { "schemas": { "actor": { "type": "object", "title": "Actor", "properties": { "apiKey": { "type": "string", "description": "The unique identifier for the API key.", "examples": [ "apk_0SNlurA049MEWV4wRq2ql6SYZxiY" ] }, "application": { "type": "string", "description": "The unique identifier for the application.", "examples": [ "app_0VGkeexD3f7CKhuFX4iUbB" ] }, "member": { "type": "string", "description": "The unique identifier for the member.", "examples": [ "mbr_0SNlurA020zhzt0CwsIr53" ] }, "user": { "type": "string", "description": "The unique identifier for the user.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] }, "type": { "type": "string", "enum": [ "apiKey", "application", "member", "user", "system" ], "description": "The type of actor." } }, "required": [ "type" ], "examples": [ { "type": "user", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" }, { "type": "apiKey", "apiKey": "apk_0SNlurA049MEWV4wRq2ql6SYZxiY" }, { "type": "application", "application": "app_0VGkeexD3f7CKhuFX4iUbB" }, { "type": "member", "member": "mbr_0SNlurA020zhzt0CwsIr53" }, { "type": "system" } ] }, "addon": { "type": "object", "title": "Add-on", "description": "Add-ons define features or top-ups that can be used to extend the functionality offered to the end user through their subscription's plan.", "properties": { "object": { "type": "string", "const": "addon", "description": "Type of object is always `addon`." }, "id": { "type": "string", "description": "Unique identifier for the add-on.", "examples": [ "add_0SNlurA049MEWV4VxLfwJc7PJtHc" ] }, "metadata": { "$ref": "#/components/schemas/metadata" }, "activationTrigger": { "type": "string", "enum": [ "creation", "networkLatch", "usageStarted" ], "description": "Indicates when a subscription add-on will take effect.\n\n- `creation`: As soon as it is created. The user does not need to take any further action.\n- `networkLatch`: When the user's data session ends, which can be forced by power cycling the device.\n- `usageStarted`: When the user starts using add-on allowance on their device.\n", "examples": [ "creation" ] }, "allowances": { "type": "object", "title": "Allowances", "description": "The allowances included in the add-on.", "properties": { "dataBytes": { "type": [ "integer", "null" ], "description": "The data allowance in bytes. A value of `null` indicates unlimited data.", "examples": [ 10000000000 ] }, "voiceSeconds": { "type": [ "integer", "null" ], "description": "The voice call allowance in seconds. A value of `null` indicates unlimited calls.", "examples": [ 30000 ] }, "smsMessages": { "type": [ "integer", "null" ], "description": "The SMS allowance in messages. A value of `null` indicates unlimited SMS.", "examples": [ 100 ] } }, "required": [ "dataBytes", "voiceSeconds", "smsMessages" ] }, "coverage": { "anyOf": [ { "$ref": "#/components/schemas/coverage" }, { "type": "null" } ], "description": "The geographic coverage of the add-on. A value of `null` indicates that coverage is not applicable for this add-on." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the add-on was created .", "examples": [ "2021-01-21T19:12:28Z" ] }, "description": { "type": [ "string", "null" ], "description": "The description of the add-on.", "examples": [ "Disable international roaming." ] }, "limits": { "type": [ "object", "null" ], "description": "Usage limits for a recurring add-on: how much data it gets each period, and when it's throttled. The value is `null` if the add-on has none.", "properties": { "dataBytes": { "type": "integer", "description": "The maximum amount of data in bytes each period, including the throttled part.", "examples": [ 13000000000 ] }, "throttling": { "type": "object", "description": "The throttling configuration for the add-on.", "properties": { "thresholdBytes": { "type": "integer", "description": "The threshold in bytes at which throttling will be applied.", "examples": [ 3000000000 ] }, "bandwidthBitsPerSecond": { "type": "integer", "description": "The bandwidth in bits per second that the add-on will be throttled to.", "examples": [ 256000 ] } }, "required": [ "thresholdBytes", "bandwidthBitsPerSecond" ] } }, "required": [ "dataBytes", "throttling" ] }, "name": { "type": "string", "description": "Name for the add-on.", "examples": [ "1GB Data Top-up" ] }, "plans": { "type": "array", "description": "The plans this add-on is compatible with.", "items": { "type": "string", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] } }, "price": { "$ref": "#/components/schemas/price", "description": "The price of the add-on." }, "provider": { "type": "string", "description": "The ID of the network provider supported by this add-on.", "examples": [ "p5" ] }, "recurrenceType": { "type": "string", "enum": [ "oneTime", "recurring" ], "description": "The recurrence type the add-on.", "examples": [ "oneTime" ] }, "status": { "type": "string", "enum": [ "draft", "available", "archived" ], "description": "The current status of the add-on." }, "type": { "type": "string", "enum": [ "topUp", "other" ], "description": "The type of the add-on.", "examples": [ "topUp" ] }, "validity": { "type": [ "object", "null" ], "description": "The validity period of the add-on. When the add-on is activated, it will expire after this\n duration. Not all add-ons have a validity period.", "properties": { "unit": { "type": "string", "enum": [ "day", "month" ], "description": "The time unit of the add-on, either `day` or `month`." }, "value": { "type": "integer", "description": "The amount of units (specified in the `unit` property).", "minimum": 1, "examples": [ 7 ] }, "totalPeriods": { "type": "integer", "default": 1, "description": "How many times the validity period repeats. It is `2` or more for recurring add-ons and `1` for one-time add-ons. The total lifetime (`value` times `unit` times `totalPeriods`) must not exceed 10 years.", "maximum": 3652, "minimum": 1, "examples": [ 1 ] } }, "required": [ "unit", "value" ] }, "data": { "type": "integer", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `allowances` instead.\n\n\nThe data allowance in bytes included in this add-on. A value of `-1` indicates unlimited data.", "examples": [ 10000000000 ], "deprecated": true }, "dataUnit": { "type": "string", "const": "byte", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `allowances` instead.\n\n\nThe unit of the data value is always `byte`.", "deprecated": true }, "sms": { "type": "integer", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `allowances` instead.\n\n\nThe sms allowance included in this add-on. A value of `-1` indicates unlimited sms.", "examples": [ 100 ], "deprecated": true }, "smsUnit": { "type": "string", "const": "message", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `allowances` instead.\n\n\nThe unit of the sms value is always `sms`.", "deprecated": true }, "voice": { "type": "integer", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `allowances` instead.\n\n\nThe voice call allowance in seconds included in this add-on. A value of `-1` indicates unlimited voice calls.", "examples": [ 30000 ], "deprecated": true }, "voiceUnit": { "type": "string", "const": "second", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `allowances` instead.\n\n\nThe unit of the voice value is always `second`.", "deprecated": true } }, "required": [ "object", "id", "metadata", "activationTrigger", "allowances", "coverage", "data", "dataUnit", "description", "limits", "name", "plans", "price", "provider", "recurrenceType", "sms", "smsUnit", "status", "type", "validity", "voice", "voiceUnit", "createdAt" ] }, "allowance": { "type": "object", "title": "Allowance", "description": "An allowance represents a specific usage limit (e.g., minutes, bytes, messages) the purchase of a product entitles a user to.", "properties": { "object": { "type": "string", "const": "allowance", "description": "Type of object is always `allowance`." }, "id": { "type": "string", "description": "Unique identifier for the allowance.", "examples": [ "alw_0SNlurA049MEWV3OMTRrGKbd99GH" ] }, "name": { "type": "string", "description": "The human-readable name of this allowance.", "examples": [ "Roaming data in Europe" ] }, "type": { "type": "string", "enum": [ "data", "voice", "sms" ], "description": "The type of usage permitted by this allowance." }, "coverage": { "$ref": "#/components/schemas/coverage", "description": "The geographic coverage of the allowance." }, "limit": { "type": [ "integer", "null" ], "description": "The amount of usage permitted by this allowance counted in `unit`. A value of `null` indicates an unlimited allowance.", "examples": [ 500 ] }, "unit": { "type": "string", "enum": [ "bytes", "seconds", "messages" ], "description": "The unit the usage permitted by this allowance is counted in." } }, "required": [ "object", "id", "name", "type", "coverage", "limit", "unit" ] }, "apiKey": { "type": "object", "title": "APIKey", "properties": { "object": { "type": "string", "const": "apiKey", "description": "Type of object is always `apiKey`." }, "id": { "type": "string", "description": "Unique identifier for the API key.", "examples": [ "apk_0SNlurA049MEWV4wRq2ql6SYZxiY" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the API key was created.", "examples": [ "2022-02-14T19:38:34Z" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the API key expires and won't be valid anymore.", "examples": [ "2022-02-21T19:38:34Z" ] }, "name": { "type": "string", "description": "Human readable name describing what the API key is used for.", "examples": [ "My first Gigs API integration" ] }, "token": { "type": "string", "description": "The bearer token to be used in HTTP Authorization. The full token is only available in the create response. In all other responses a redacted token will be returned, as we do not store the full token ourselves.", "examples": [ "gpk_2W4IoEFH••••" ] } }, "required": [ "object", "id", "name", "token", "createdAt", "expiresAt" ] }, "consentRequest": { "type": "object", "title": "ConsentRequest", "properties": { "object": { "type": "string", "const": "consentRequest", "description": "Type of object is always `consentRequest`." }, "id": { "type": "string", "description": "Unique identifier for the consent request.", "examples": [ "crq_0SNlurA049MEWV2jN9EvAfKMf7VU" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "The timestamp at which the consent request was created.", "examples": [ "2024-01-09T15:00:51Z" ] }, "deliveryMethod": { "type": [ "null", "string" ], "enum": [ null, "emailLink", "sms", "smsLink", "smsOTP" ], "description": "The method by which the consent request is delivered to the user.", "examples": [ "emailLink" ] }, "expiredAt": { "type": [ "null", "string" ], "format": "date-time", "description": "The timestamp at which the consent request expired.", "examples": [ "2024-01-09T15:00:51Z" ] }, "operation": { "type": "string", "enum": [ "change.phoneNumber", "change.provider", "exchange.sim", "issue.portOutCredentials", "portin.subscription" ], "description": "The operation being requested.", "examples": [ "exchange.sim" ] }, "status": { "type": "string", "enum": [ "approved", "bypassed", "canceled", "expired", "pending" ], "description": "The status of the consent request.", "examples": [ "pending" ] }, "subject": { "type": "string", "description": "The ID of resource being affected by the operation. It can be for example a port out ID, if the operation is `issue.portOutCredentials`.", "examples": [ "pto_0SNlurA049MEWV4DWEaT4SaeDI8s" ] }, "subscription": { "type": "string", "description": "Unique identifier for the subscription inferred from the resource associated with this consent request, e.g. a port-out, porting, or subscription change.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, "required": [ "object", "id", "deliveryMethod", "operation", "status", "subject", "subscription", "createdAt", "expiredAt" ] }, "coverage": { "type": "object", "title": "Coverage", "properties": { "object": { "type": "string", "const": "coverage", "description": "Type of object is always `coverage`." }, "id": { "type": "string", "description": "Unique identifier for the coverage configuration.", "examples": [ "de" ] }, "countries": { "type": "array", "description": "List of countries in ISO 3166-1 alpha-2 format covered by this coverage configuration.", "items": { "type": "string", "format": "ISO 3166-1 alpha-2", "examples": [ "DE" ] }, "examples": [ [ "DE", "FR", "US" ] ] }, "name": { "type": "string", "description": "A human-readable identifier of the coverage configuration, might not be unique.", "examples": [ "Europe" ] } }, "required": [ "object", "id", "countries", "name" ] }, "device": { "type": "object", "title": "Device", "description": "Devices are the phones or smartwatches that will be tied to a user’s plan.", "properties": { "object": { "type": "string", "const": "device", "description": "Type of object is always `device`." }, "id": { "type": "string", "description": "Unique identifier for the device.", "examples": [ "dev_0SNlurA049MEWV55CrA9qMvI2FVJ" ] }, "metadata": { "$ref": "#/components/schemas/metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the device was created.", "examples": [ "2021-02-14T19:38:34Z" ] }, "imei": { "type": [ "string", "null" ], "pattern": "^[0-9]{15,16}$", "description": "The IMEI (international mobile equipment identity) of the device if provided.", "examples": [ "492388841798923" ] }, "model": { "anyOf": [ { "$ref": "#/components/schemas/deviceModel" }, { "type": "null" } ] }, "name": { "type": [ "string", "null" ], "description": "An optional custom name for the device.", "examples": [ "Anna's iPhone 12 Pro" ] }, "sims": { "type": "array", "description": "List of SIMs added to this device.", "items": { "$ref": "#/components/schemas/sim" } }, "user": { "anyOf": [ { "$ref": "#/components/schemas/user" }, { "type": "null" } ] } }, "required": [ "object", "id", "metadata", "imei", "model", "name", "sims", "user", "createdAt" ] }, "deviceModel": { "type": "object", "title": "DeviceModel", "properties": { "object": { "type": "string", "const": "deviceModel", "description": "Type of object is always `deviceModel`." }, "id": { "type": "string", "description": "Unique identifier for the deviceModel.", "examples": [ "dmd_0SNlurA04OUskUGfGAn3Rh" ] }, "brand": { "type": "string", "description": "The brand of the device model.", "examples": [ "Apple" ] }, "hardwareIdentifiers": { "type": "array", "description": "List of hardware identifiers (e.g. the Android `Build.MODEL` string) associated with this device model.", "items": { "type": "string" }, "examples": [ [ "SM-S928U1" ] ] }, "name": { "type": "string", "description": "The device model's name.", "examples": [ "iPhone 12 Pro" ] }, "simTypes": { "type": "array", "description": "List of SIM types supported by this device model.", "items": { "type": "string", "enum": [ "eSIM", "pSIM" ] }, "examples": [ [ "eSIM", "pSIM" ] ] }, "type": { "type": "string", "enum": [ "car", "iot", "laptop", "router", "smartphone", "feature-phone", "smartwatch", "tablet", "wearable", "other" ], "description": "The type of the device model.", "examples": [ "smartphone" ] } }, "required": [ "object", "id", "brand", "name", "simTypes", "type", "hardwareIdentifiers" ] }, "deviceModelBrands": { "type": "object", "title": "DeviceModelBrands", "properties": { "object": { "type": "string", "const": "deviceModelBrands", "description": "List of device model brands." }, "items": { "type": "array", "description": "A list of brands.", "items": { "type": "string", "examples": [ "Apple" ] } } }, "required": [ "object", "items" ] }, "error": { "type": "object", "title": "Error", "properties": { "object": { "type": "string", "const": "error", "description": "Type of object is always `error`." }, "code": { "type": "string", "description": "An optional machine-readable description of the error. Present for errors that could be handled programmatically.", "examples": [ "unknown" ] }, "details": { "type": "array", "description": "Optional array containing specific information for the current error.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "items": { "$ref": "#/components/schemas/propertyErrorDetailError" } }, "documentation": { "type": "array", "description": "An optional list of URLs providing further information to resolve the error.", "items": { "type": "string", "examples": [ "https://developers.gigs.com/api/error-handling" ] } }, "hint": { "type": "string", "description": "An optional explanation how to resolve the error.", "examples": [ "Parameter iccid must match /^([0-9]{19}F?|[0-9]{20})$/i" ] }, "message": { "type": "string", "description": "A human readable description of the error.", "examples": [ "Invalid ICCID format." ] }, "type": { "type": "string", "description": "The type of [error](https://developers.gigs.com/api/error-handling) returned.", "examples": [ "invalid" ] } }, "required": [ "object", "message", "type" ] }, "eSimProfile": { "type": "object", "title": "EsimProfile", "properties": { "object": { "type": "string", "const": "eSimProfile", "description": "Type of object is always `eSimProfile`." }, "sim": { "$ref": "#/components/schemas/sim" }, "status": { "type": "string", "enum": [ "deleted", "disabled", "downloaded", "enabled", "installed", "unknown" ], "description": "The current status of the eSimProfile.\n\nSupported providers are `p3`, `p11`, `p12`, `p14`, `p15`, `p18` and `p32`.\n\nThis will be `unknown` when:\n - the SIM's provider is not supported; or\n - no lifecycle status has been received for the given SIM.\n\nRelated guide: [eSIM profile lifecycle](https://developers.gigs.com/docs/core/sims#e-sim-profile-lifecycle)\n" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time at which the eSIM profile was last updated.", "examples": [ "2024-03-13T15:36:01Z" ] } }, "required": [ "object", "sim", "status", "updatedAt" ] }, "metadata": { "type": "object", "title": "Metadata", "description": "A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource.", "additionalProperties": { "type": "string", "maxLength": 255 } }, "metadataUpdate": { "type": "object", "title": "Metadata", "description": "A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource.", "additionalProperties": { "type": [ "string", "null" ], "maxLength": 255 } }, "networkAvailability": { "type": "object", "title": "NetworkAvailability", "description": "\n> #### Preview\n>\n> This schema is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "properties": { "object": { "type": "string", "const": "networkAvailability", "description": "Type of object is always `networkAvailability`." }, "availability": { "type": "array", "description": "A list of availability details for the plans in the project.", "items": { "type": "object", "properties": { "plan": { "type": "string", "description": "The unique identifier for the plan.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] }, "provider": { "type": "string", "description": "The ID of the network provider supported by this plan.", "examples": [ "p11" ] }, "technologies": { "type": "object", "description": "The technologies supported by the network provider.", "examples": [ { "4G": { "strength": "good", "minDecibelMilliwatts": -90 }, "5G": { "strength": "fair", "minDecibelMilliwatts": -100 } } ], "additionalProperties": { "type": "object", "title": "NetworkAvailabilityDataPoint", "properties": { "strength": { "type": "string", "enum": [ "poor", "fair", "good", "excellent", "unknown" ], "description": "A qualitative description of the signal's strength.", "examples": [ "excellent" ] }, "minDecibelMilliwatts": { "type": "number", "description": "The minimum signal strength recorded in dBm.", "examples": [ -100 ] } }, "required": [ "strength", "minDecibelMilliwatts" ] } } }, "required": [ "plan", "provider", "technologies" ] } }, "location": { "type": "object", "description": "The location for which availability information is provided.", "properties": { "address": { "type": "object", "title": "NetworkAvailabilityAddress", "description": "The address for which availability information is provided.\n\n\n> #### Preview\n>\n> This schema is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "properties": { "city": { "type": "string", "description": "The city/municipality of the address.", "examples": [ "New York City" ] }, "country": { "type": "string", "description": "The ISO 3166-1 alpha-2 country code of the address.", "examples": [ "US" ] }, "line1": { "type": "string", "description": "The first line of the address, e.g. street and house number.", "examples": [ "129 West 81st Street" ] }, "line2": { "type": [ "string", "null" ], "description": "The second line of the address, e.g. apartment number.", "examples": [ "Apartment 5" ] }, "postalCode": { "type": [ "string", "null" ], "description": "The postal code of the address.", "examples": [ "10024" ] }, "state": { "type": [ "string", "null" ], "description": "The state/province/region of the address.", "examples": [ "NY" ] } }, "required": [ "city", "country", "line1" ] }, "coordinates": { "type": "object", "title": "NetworkAvailabilityCoordinates", "description": "The coordinates for which availability information is provided.\n\n\n> #### Preview\n>\n> This schema is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "properties": { "latitude": { "type": "number", "description": "The latitude coordinate for which availability information is provided.", "maximum": 90, "minimum": -90, "examples": [ 40.7831 ] }, "longitude": { "type": "number", "description": "The longitude coordinate for which availability information is provided.", "maximum": 180, "minimum": -180, "examples": [ -73.9712 ] } }, "required": [ "latitude", "longitude" ] } } } }, "required": [ "object", "availability", "location" ] }, "networkAvailabilityTileset": { "type": "object", "title": "NetworkAvailabilityTileset", "description": "\n> #### Preview\n>\n> This schema is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "properties": { "object": { "type": "string", "const": "networkAvailabilityTileset", "description": "Type of object is always `networkAvailabilityTileset`." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Time when the signed `urlTemplate` expires. Fetch the tilesets again before then.", "examples": [ "2026-08-04T12:00:00Z" ] }, "layers": { "type": "array", "description": "The layers inside the tiles, ordered from the broadest coverage to the fastest technology.", "items": { "type": "object", "properties": { "technology": { "type": "string", "description": "The network technology the layer covers.", "examples": [ "5G" ] }, "sourceLayer": { "type": "string", "description": "The layer's name inside a tile. Use it as the source layer in a map library.", "examples": [ "coverage_5g" ] } }, "required": [ "technology", "sourceLayer" ] } }, "maxZoom": { "type": "integer", "description": "The highest zoom level the tiles cover. Beyond it, map libraries scale up existing tiles instead of fetching new ones.", "examples": [ 10 ] }, "minZoom": { "type": "integer", "description": "The lowest zoom level the tiles cover.", "examples": [ 0 ] }, "urlTemplate": { "type": "string", "description": "Tile URL template in the standard XYZ format. Pass it to a map library unchanged: the library fills in the `{z}`, `{x}` and `{y}` placeholders.", "examples": [ "https://tiles.gigs.com/tiles/default/2026-08-03/{z}/{x}/{y}.pbf?URLPrefix=aHR0cHM6Ly90aWxlcy5naWdzLmNvbS90aWxlcy9kZWZhdWx0LzIwMjYtMDgtMDMv&Expires=1785844800&KeyName=tiles-key-20260930&Signature=pciE55nCNX-qhXzJNSAXaf34624=" ] } }, "required": [ "object", "expiresAt", "layers", "maxZoom", "minZoom", "urlTemplate" ] }, "organization": { "type": "object", "title": "Organization", "properties": { "object": { "type": "string", "const": "organization", "description": "Type of object is always `organization`." }, "id": { "type": "string", "description": "Unique identifier for the organization.", "examples": [ "org_0SNlurA04kOdemVEMVZQBF" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the organization was created.", "examples": [ "2021-02-01T13:21:30Z" ] }, "name": { "type": "string", "description": "Name for the organization.", "examples": [ "Gigs" ] } }, "required": [ "object", "id", "name", "createdAt" ] }, "period": { "type": "object", "title": "Period", "properties": { "number": { "type": "integer", "description": "Sequence number of the period.", "minimum": 1, "examples": [ 1 ] }, "start": { "type": "string", "format": "date-time", "description": "Beginning of the period.", "examples": [ "2021-01-21T19:32:13Z" ] }, "end": { "type": "string", "format": "date-time", "description": "End of the period.", "examples": [ "2021-02-20T19:38:34Z" ] } }, "required": [ "number", "start", "end" ] }, "plan": { "type": "object", "title": "Plan", "description": "Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users.", "properties": { "object": { "type": "string", "const": "plan", "description": "Type of object is always `plan`." }, "id": { "type": "string", "description": "Unique identifier for the plan.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] }, "metadata": { "$ref": "#/components/schemas/metadata" }, "activationTrigger": { "type": "string", "enum": [ "creation", "usageStarted" ], "description": "Indicates when a subscription will activate.\n\n- `creation`: As soon as it is created. The user does not need to take any further action.\n- `usageStarted`: When the user starts using subscription allowance on their device.\n", "examples": [ "creation" ] }, "allowances": { "type": "object", "title": "Allowances", "description": "Usage allowances included in the plan - i.e. how many bytes of data, voice minutes & sms messages the user has access to.", "properties": { "dataBytes": { "type": [ "integer", "null" ], "description": "The data allowance in bytes. A value of `null` indicates unlimited data.", "examples": [ 10000000000 ] }, "voiceSeconds": { "type": [ "integer", "null" ], "description": "The voice call allowance in seconds. A value of `null` indicates unlimited calls.", "examples": [ 30000 ] }, "smsMessages": { "type": [ "integer", "null" ], "description": "The SMS allowance in messages. A value of `null` indicates unlimited SMS.", "examples": [ 100 ] } }, "required": [ "dataBytes", "voiceSeconds", "smsMessages" ] }, "coverage": { "$ref": "#/components/schemas/coverage", "description": "The geographic coverage of the plan." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the plan was created.", "examples": [ "2021-01-21T19:38:34Z" ] }, "description": { "type": [ "string", "null" ], "description": "The plan's description, meant to be displayable to the users.", "examples": [ "A data plan you will love! Operates in most countries of the world." ] }, "firstPeriodTrigger": { "type": "string", "enum": [ "activation", "creation" ], "description": "Indicates when a subscription's first period will start.\n\n- `creation`: As soon as the subscription is created.\n- `activation`: When the subscription's status transitions from `pending` to `active`.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "creation" ] }, "image": { "type": [ "string", "null" ], "format": "url", "description": "The plan's image, meant to be displayable to the users.", "examples": [ "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png" ] }, "limits": { "type": "object", "title": "Limits", "description": "Usage limits for the plan - i.e. the maximum available bandwidth, fair-use data limits and throttling threshold.", "properties": { "dataBytes": { "type": [ "integer", "null" ], "description": "The maximum amount of data that can be used in bytes. A value of `null` indicates unlimited data.", "examples": [ 100000000000 ] }, "bandwidthBitsPerSecond": { "type": [ "integer", "null" ], "description": "The maximum bandwidth in bits per second. A value of `null` indicates the maximum bandwidth this network allows.", "examples": [ 100000000 ] }, "throttling": { "type": [ "object", "null" ], "description": "The throttling configuration for the plan, if any.", "properties": { "thresholdBytes": { "type": "integer", "description": "The threshold in bytes at which throttling will be applied.", "examples": [ 10000000000 ] }, "bandwidthBitsPerSecond": { "type": "integer", "description": "The bandwidth in bits per second that the plan will be throttled to.", "examples": [ 512000 ] } }, "required": [ "thresholdBytes", "bandwidthBitsPerSecond" ] } }, "required": [ "dataBytes", "bandwidthBitsPerSecond", "throttling" ] }, "name": { "type": "string", "description": "The plan's name, meant to be displayable to the users.", "examples": [ "Gigs Global" ] }, "price": { "$ref": "#/components/schemas/price", "description": "The price of the plan." }, "provider": { "type": "string", "description": "The ID of the network provider supported by this plan.", "examples": [ "p5" ] }, "requirements": { "type": "object", "description": "Required information that must be collected from the user in order to create a subscription with this plan.", "properties": { "address": { "type": "string", "enum": [ "none", "present", "verified" ], "description": "The address requirements that must be fulfilled before a user may purchase a subscription.", "examples": [ "present" ] }, "device": { "type": "string", "enum": [ "none", "present", "verified" ], "description": "The device requirements that must be fulfilled before a user may purchase a subscription." }, "user.birthday": { "type": "string", "enum": [ "none", "present", "verified" ], "description": "The user birthday requirements that must be fulfilled before a user may purchase a subscription." }, "user.fullName": { "type": "string", "enum": [ "none", "present", "verified" ], "description": "The user full name requirements that must be fulfilled before a user may purchase a subscription.", "examples": [ "present" ] } }, "required": [ "address", "device", "user.birthday", "user.fullName" ] }, "simTypes": { "type": "array", "description": "List of SIM types supported by this plan. Can be `eSIM`, `pSIM`, or both.", "items": { "type": "string", "enum": [ "eSIM", "pSIM" ] }, "examples": [ [ "eSIM", "pSIM" ] ] }, "status": { "type": "string", "enum": [ "available", "archived", "pending", "draft" ] }, "validity": { "type": "object", "title": "Validity", "description": "Plan validity information - i.e. subscription period length, and the minimum number of periods before the plan can be ended.", "properties": { "minimumPeriods": { "type": "integer", "description": "The minimum number of subscription periods that the plan must be renewed.", "minimum": 0, "examples": [ 12 ] }, "type": { "type": "string", "enum": [ "recurring", "oneTime" ], "description": "The validity type of this plan." }, "unit": { "type": "string", "enum": [ "day", "month" ], "description": "The time unit of the subscription period." }, "value": { "type": "integer", "description": "The amount of units (specified in the `unit` property) in each subscription period. The total validity duration (`value` times `unit`) must not exceed 10 years.", "minimum": 1, "examples": [ 7 ] } }, "required": [ "minimumPeriods", "type", "unit", "value" ] }, "data": { "type": "integer", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `allowances` instead.\n\n\nThe data allowance in bytes included in this plan. A value of `-1` indicates unlimited data.", "examples": [ 10000000000 ], "deprecated": true }, "dataUnit": { "type": "string", "const": "byte", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `allowances` instead.\n\n\nThe unit of the data value is always `byte`.", "deprecated": true }, "sms": { "type": "integer", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `allowances` instead.\n\n\nThe sms allowance included in this plan. A value of `-1` indicates unlimited sms.", "examples": [ 100 ], "deprecated": true }, "smsUnit": { "type": "string", "const": "message", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `allowances` instead.\n\n\nThe unit of the sms value is always `message`.", "deprecated": true }, "voice": { "type": "integer", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `allowances` instead.\n\n\nThe voice allowance included in this plan. A value of `-1` indicates unlimited voice.", "examples": [ 30000 ], "deprecated": true }, "voiceUnit": { "type": "string", "const": "second", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `allowances` instead.\n\n\nThe unit of the voice value is always `second`.", "deprecated": true } }, "required": [ "object", "id", "metadata", "activationTrigger", "allowances", "coverage", "data", "dataUnit", "description", "firstPeriodTrigger", "image", "limits", "name", "price", "provider", "requirements", "simTypes", "sms", "smsUnit", "status", "validity", "voice", "voiceUnit", "createdAt" ] }, "planDocument": { "type": "object", "title": "PlanDocument", "properties": { "object": { "type": "string", "const": "planDocument", "description": "Type of object is always `planDocument`." }, "id": { "type": "string", "description": "Unique identifier for the given document.", "examples": [ "pdc_0SNlurA049MEWV1S6e1qVqBV2xge" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "The time the document was created.", "examples": [ "2022-07-04T16:20:27.59Z" ] }, "language": { "type": [ "null", "string" ], "description": "The language of the document. The values follow the BCP 47 standard. That means, for instance, that a region can be specified in addition to the language.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "en-US" ] }, "name": { "type": "string", "description": "The name of the document.", "examples": [ "My Plan Contract" ] }, "plan": { "type": "string", "description": "Unique identifier for the plan associated to this document.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] }, "type": { "type": "string", "description": "The MIME type for the given document.", "examples": [ "application/pdf" ] }, "url": { "type": "string", "description": "The URL at which the document can be retrieved.", "examples": [ "https://a.gigscdn.net/p/my-project/01G74ZPB5PQTDESM4JGYR2CWB9.pdf" ] } }, "required": [ "object", "id", "language", "name", "plan", "type", "url", "createdAt" ] }, "porting": { "type": "object", "title": "Porting", "description": "Porting is required when a user wants to keep their phone number when changing their subscription. There are multiple steps involved between the user, their previous carrier, and the new subscriber", "properties": { "object": { "type": "string", "const": "porting", "description": "Type of object is always `porting`." }, "id": { "type": "string", "description": "Unique identifier for the porting.", "examples": [ "prt_0SNlurA049MEWV39s2kSYqaat7ZS" ] }, "accountNumber": { "type": [ "string", "null" ], "description": "The account number on the donor service provider.", "examples": [ "123456789" ] }, "accountPinExists": { "type": "boolean", "description": "Whether the account PIN has been provided.", "examples": [ true ] }, "accountType": { "type": [ "string", "null" ], "enum": [ null, "postpaidMulti", "postpaidSingle", "prepaidRegistered", "prepaidUnregistered" ], "description": "The type of account on the donor service provider. This field is only used for portings in Ireland and may be `null` otherwise.", "examples": [ "prepaidUnregistered" ] }, "address": { "type": [ "object", "null" ], "description": "The address of the account holder on the donor service provider.", "properties": { "city": { "type": "string", "description": "The city/municipality of the address.", "examples": [ "New York City" ] }, "country": { "type": "string", "description": "The ISO 3166-1 alpha-2 country code of the address.", "examples": [ "US" ] }, "line1": { "type": "string", "description": "The first line of the address, e.g. street and house number.", "examples": [ "129 West 81st Street" ] }, "line2": { "type": [ "string", "null" ], "description": "TThe second line of the address, e.g. apartment number.", "examples": [ "Apartment 5" ] }, "postalCode": { "type": "string", "description": "The postal code of the address.", "examples": [ "10024" ] }, "state": { "type": [ "string", "null" ], "description": "The state/province/region of the address.", "examples": [ "NY" ] } }, "required": [ "city", "country", "line1", "line2", "postalCode", "state" ] }, "behavior": { "type": "string", "enum": [ "cancelOnly", "portIn" ], "description": "The behavior of the porting.\n\nA value of `portIn` indicates that this porting\nwill transfer the phone number from the previous provider.\n\nA porting with behavior `cancelOnly` will cancel\nthe previous service without transferring the number. This behavior is\ncurrently only available for local plans in the United Kingdom.\n", "examples": [ "portIn" ] }, "billingPinExists": { "type": "boolean", "description": "Whether the billing PIN has been provided.", "examples": [ true ] }, "birthday": { "type": [ "string", "null" ], "format": "date", "description": "The birthday of the account holder on the donor service provider.", "examples": [ "2017-07-21" ] }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the porting was canceled.", "examples": [ "2021-01-21T19:39:53Z" ] }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the porting was completed.", "examples": [ "2021-01-21T19:36:57Z" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the porting was created.", "examples": [ "2021-01-21T19:12:28Z" ] }, "declinedAttempts": { "type": "integer", "description": "The number of declined porting attempts so far.", "minimum": 0, "examples": [ 0 ] }, "declinedCode": { "type": [ "string", "null" ], "description": "The code reason for the declined porting.", "examples": [ "portingPhoneNumberPortProtected" ] }, "declinedMessage": { "type": [ "string", "null" ], "description": "The reason description for the declined porting.", "examples": [ "The phone number has port protection on the provider." ] }, "donorProvider": { "anyOf": [ { "$ref": "#/components/schemas/serviceProvider" }, { "type": "null" } ], "description": "The service provider from whom the number is ported." }, "donorProviderApproval": { "type": [ "boolean", "null" ], "description": "Whether the donor provider has approved or not the porting.", "examples": [ true ] }, "expiredAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the porting was expired.", "examples": [ "2021-01-21T19:39:53Z" ] }, "failedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the porting was failed.", "examples": [ "2021-01-21T19:39:53Z" ] }, "failureReason": { "type": [ "string", "null" ], "enum": [ null, "consentCodeAttemptsExceeded", "consentNotGiven", "consentRequestCanceled" ], "description": "The reason for the porting failure. Only recorded when the porting failed because user consent could not be obtained.", "examples": [ "consentNotGiven" ] }, "firstName": { "type": [ "string", "null" ], "description": "The first name of the account holder on the donor service provider.", "examples": [ "Jerry" ] }, "lastDeclinedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the porting was last declined.", "examples": [ "2021-01-21T19:31:13Z" ] }, "lastName": { "type": [ "string", "null" ], "description": "The last name of the account holder on the donor service provider.", "examples": [ "Seinfeld" ] }, "lastRequestedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the porting was last requested.", "examples": [ "2021-01-21T19:22:31Z" ] }, "phoneNumber": { "type": "string", "format": "E.164", "description": "The phone number to port in E.164 string_format.", "examples": [ "+19591234567" ] }, "provider": { "type": "string", "description": "The ID of the recipient network provider.", "examples": [ "p9" ] }, "recipientProvider": { "$ref": "#/components/schemas/serviceProvider", "description": "The service provider to whom the number is ported." }, "requestBehavior": { "type": "string", "enum": [ "automatic", "manual" ], "description": "Controls when the porting is submitted to the recipient network provider.\n\nWhen `automatic`, the porting is requested automatically as soon as all required information is present.\n\nWhen `manual`, that automatic submission is withheld until the porting is requested explicitly via the [request a porting](https://developers.gigs.com/core/portings#request-a-porting) endpoint. A `manual` porting that has all required information waits in the `informationRequired` status, or in `declined` if it was declined, until it is requested.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "automatic" ] }, "required": { "type": "array", "description": "List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.", "items": { "type": "string" }, "examples": [ [ "accountNumber", "accountPin", "accountType", "address", "birthday", "donorProvider", "donorProviderApproval", "firstName", "lastName" ] ] }, "scheduledOn": { "type": [ "string", "null" ], "format": "date", "description": "Date when the porting is scheduled to take effect.\n\nFor most providers this returns the provider-confirmed date when available,\notherwise the user-requested date. For Concierge scheduled porting (p18), this\nreturns the user-facing expected completion date and does not reflect the\ninternal batch run date.\n\nScheduling a port-in is only supported in France, Ireland, Sweden and the United Kingdom. For other regions this reflects the provider-confirmed date when available or `null` otherwise.\n", "examples": [ "2021-01-21" ] }, "status": { "type": "string", "enum": [ "draft", "initiated", "pending", "informationRequired", "requested", "declined", "completed", "canceled", "expired", "failed" ], "description": "The current status of the porting." }, "subscription": { "type": [ "string", "null" ], "description": "Unique identifier for the porting subscription.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] }, "user": { "type": "string", "description": "Unique identifier for the user this porting is for.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, "required": [ "object", "id", "accountNumber", "accountPinExists", "accountType", "address", "behavior", "billingPinExists", "scheduledOn", "birthday", "declinedAttempts", "declinedCode", "declinedMessage", "donorProvider", "donorProviderApproval", "firstName", "lastName", "phoneNumber", "provider", "recipientProvider", "requestBehavior", "required", "status", "subscription", "user", "canceledAt", "completedAt", "createdAt", "expiredAt", "failedAt", "failureReason", "lastDeclinedAt", "lastRequestedAt" ] }, "portOut": { "type": "object", "title": "PortOut", "description": "Port out is required when a user wants to keep their number when cancelling their subscription. There are multiple steps involved between the user, the current carrier, and the new carrier.", "properties": { "object": { "type": "string", "const": "portOut", "description": "Type of object is always `portOut`." }, "id": { "type": "string", "description": "Unique identifier for the port out.", "examples": [ "pto_0SNlurA049MEWV4DWEaT4SaeDI8s" ] }, "behavior": { "type": "string", "enum": [ "cancelOnly", "portOut" ], "description": "The behavior of the port out.\n\nA value of `portOut` indicates that using this\nport out will transfer the phone number to the recipient provider.\n\nPort out with behavior `cancelOnly`\nwill cancel the service without transferring the number. This behavior is\ncurrently only available for local plans in the United Kingdom.\n", "examples": [ "portOut" ] }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the port out is completed successfully.", "examples": [ "2022-02-21T19:38:34Z" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the port out was created.", "examples": [ "2020-01-01T00:00:00Z" ] }, "expirationRequestedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when early expiration of the port out was requested.", "examples": [ "2022-02-21T19:38:12Z" ] }, "expiredAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the port out expires and won't be valid anymore.", "examples": [ "2022-02-21T19:38:34Z" ] }, "failureReason": { "type": [ "string", "null" ], "enum": [ null, "consentNotGiven", "consentRequestCanceled" ], "description": "The reason for the port out failure.", "examples": [ "consentNotGiven" ] }, "status": { "type": "string", "enum": [ "completed", "expired", "failed", "initiated", "issued", "processing" ], "description": "The current status of the port out.", "examples": [ "issued" ] }, "subscription": { "type": "string", "description": "Unique identifier of the subscription affected.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] }, "user": { "type": "string", "description": "Unique identifier for the user this port out credentials are for.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, "required": [ "object", "id", "behavior", "completedAt", "createdAt", "subscription", "expirationRequestedAt", "expiredAt", "status", "user", "failureReason" ] }, "deprecatedPortOutCredential": { "type": "object", "title": "DeprecatedPortOutCredentials", "properties": { "object": { "type": "string", "const": "portOutCredentials", "description": "Type of object is always `portOutCredentials`." }, "accountNumber": { "type": "string", "description": "The account number on the service provider.", "examples": [ "123456789" ] }, "accountPin": { "type": [ "string", "null" ], "description": "The account pin on the service provider. This value will always be null in all events.", "examples": [ "1234" ] }, "behavior": { "type": "string", "enum": [ "cancelOnly", "portOut" ], "description": "The behavior of the port out credentials.\n\nA value of `portOut` indicates that using these\nport out credentials will transfer the phone number to the recipient provider.\n\nPort out credentials with behavior `cancelOnly`\nwill cancel the service without transferring the number. This behavior is\ncurrently only available for local plans in the United Kingdom.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "portOut" ] }, "expiresAt": { "type": "string", "format": "date-time", "description": "Time when the port-out credentials expire and won't be valid anymore.", "examples": [ "2022-02-21T19:38:34Z" ] }, "subscription": { "type": "string", "description": "Unique identifier of the subscription affected.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, "required": [ "object", "accountNumber", "accountPin", "behavior", "subscription", "expiresAt" ], "deprecated": true }, "portOutCredentials": { "type": "object", "title": "PortOutCredentials", "description": "Port out credentials issued by network provider and used for the porting process at the target provider.", "properties": { "object": { "type": "string", "const": "portOutCredentials", "description": "Type of object is always `portOutCredentials`." }, "accountNumber": { "type": [ "string", "null" ], "description": "The account number on the service provider. Account number is `null` if no account number is issued in the respective country.", "examples": [ "123456789" ] }, "accountPin": { "type": "string", "description": "The account pin from the service provider.", "examples": [ "1234" ] }, "portOut": { "type": "string", "description": "Unique identifier of the port out this credentials are for.", "examples": [ "pto_0SNlurA049MEWV4DWEaT4SaeDI8s" ] } }, "required": [ "object", "accountNumber", "accountPin", "portOut" ] }, "price": { "type": "object", "title": "Price", "properties": { "amount": { "type": "integer", "description": "The price amount in the currency's minor unit, e.g. \"cents\" for many currencies.\n\nMost currencies have two decimals, so USD 9.99 is `999`. These currencies have a different number of decimals, e.g. JPY 28,500 is `28500`:\n\n- 0 decimals: CLP, ISK, JPY, KRW\n", "minimum": 0, "examples": [ 999 ] }, "currency": { "type": "string", "format": "ISO 4217", "description": "Three-letter ISO 4217 currency code. Must be a supported currency.", "examples": [ "USD" ] } }, "required": [ "amount", "currency" ] }, "project": { "type": "object", "title": "Project", "description": "A project is where all of the user, subscription, plan, device, and SIM information lives.", "properties": { "object": { "type": "string", "const": "project", "description": "Type of object is always `project`." }, "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,28}[a-z0-9]$", "description": "Globally unique identifier for the project.", "examples": [ "gigs" ] }, "billing": { "type": [ "object", "null" ], "description": "Configuration parameters for the project use of billing. Present when the Billing API is enabled.", "properties": { "advanceInvoicingDays": { "type": [ "integer", "null" ], "description": "Number of days before renewal when invoices are generated. A value of `null` indicates that invoices are generated immediately after the renewal.", "examples": [ 7 ] }, "invoiceGracePeriodDays": { "type": "integer", "description": "Number of days after renewal that an invoice can remain unpaid before it becomes overdue. After this period, the action specified in `invoiceOverdueAction` is triggered.", "examples": [ 3 ] }, "invoiceOverdueDays": { "type": "integer", "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use `invoiceGracePeriodDays` instead.\n\n\nNumber of days after renewal that an invoice can remain unpaid before it becomes overdue. After this period, the action specified in `invoiceOverdueAction` is triggered.", "examples": [ 3 ], "deprecated": true }, "invoiceOverduePeriodDays": { "type": [ "integer", "null" ], "description": "Number of days that invoices can remain overdue before subscriptions are ended. A value of `null` indicates that the subscriptions are ended at the end of the period.\n\nRelevant when subscriptions are not ended immediately after an invoice becomes overdue.\n", "examples": [ 1 ] }, "invoiceOverdueAction": { "type": "string", "enum": [ "end", "none", "restrict" ], "description": "Indicates what happens to the subscription when a renewal invoice becomes overdue. One of:\n\n- `none`: Leave the subscription as is.\n- `end`: End the subscription immediately.\n- `restrict`: Restrict the subscription's connectivity.\n" }, "currency": { "type": "string", "format": "ISO 4217", "description": "Three-letter ISO 4217 currency code representing the currency for the project use of billing. Must be a supported currency.", "examples": [ "USD" ] }, "restrictBehavior": { "type": [ "string", "null" ], "enum": [ null, "incomingOnly", "noData", "throttledData" ], "description": "Present when `invoiceOverdueAction` is `restrict`; nil otherwise.\nDetermines how subscriptions are restricted when an invoice becomes overdue. It can have one of the following values:\n\n- `incomingOnly`: The subscription line can receive calls & SMS, but cannot make calls, send SMS, or use data.\n- `noData`: The subscription line can make and receive calls & SMS, but cannot use data.\n- `throttledData`: The subscription line can still make and receive calls & SMS, and use up to 1GB of data at a reduced speed.\n" }, "restoreBehavior": { "type": [ "string", "null" ], "enum": [ null, "keepPeriodAnchor", "resetPeriodAnchor" ], "description": "Present when `invoiceOverdueAction` is `restrict`; nil otherwise.\nDetermines how subscriptions are restored once a subscription is restored (e.g. after payment of an overdue invoice). It can have one of the following values:\n\n- `resetPeriodAnchor`: The subscription cycle is reset to the date of restoration. This means the user has a whole new period to use their plan allowance that was just restored.\n- `keepPeriodAnchor`: The subscription cycle remains unchanged. The next renewal date stays the same as before the restriction.\n" }, "paymentBehavior": { "type": "string", "enum": [ "manual", "none" ], "description": "Determines how invoices are paid. It can have one of the following values:\n\n- `manual`: Invoices are not automatically paid without explicit action.\n- `none`: No payment is performed and invoices are marked as paid automatically.\n" }, "taxBehavior": { "type": "string", "enum": [ "exclusive", "inclusive" ], "description": "Determines whether taxes are included in the product price. It can have one of the following values:\n\n- `exclusive`: Taxes are not included in the product price. The total amount is the sum of the product price and any applicable taxes.\n- `inclusive`: Taxes are already included in the product price. The total amount is the product price and the taxes are deducted from it.\n" }, "recoveryFeePercentage": { "type": [ "number", "null" ], "description": "The recovery fee percentage to be applied to invoices for local plans in the United States.\nIf both `recoveryFeePercentage` and `recoveryFeeAmount` are `null`, a default percentage will be used.\nNote: `recoveryFeePercentage` and `recoveryFeeAmount` cannot both be present at the same time.\n", "maximum": 100, "minimum": 0, "examples": [ 10 ] }, "recoveryFeeAmount": { "anyOf": [ { "$ref": "#/components/schemas/price" }, { "type": "null" } ], "description": "The recovery fee amount to be added to invoices for local plans in the United States.\nIf both `recoveryFeePercentage` and `recoveryFeeAmount` are `null`, a default percentage will be used.\nNote: `recoveryFeePercentage` and `recoveryFeeAmount` cannot both be present at the same time.\n", "examples": [ { "amount": 150, "currency": "USD" } ] } }, "required": [ "advanceInvoicingDays", "currency", "invoiceGracePeriodDays", "invoiceOverdueAction", "invoiceOverdueDays", "invoiceOverduePeriodDays", "paymentBehavior", "recoveryFeeAmount", "recoveryFeePercentage", "restrictBehavior", "restoreBehavior", "taxBehavior" ] }, "consent": { "type": [ "object", "null" ], "description": "Configuration parameters for the project's user consent collection. When absent, user consent is not checked or required.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "properties": { "deliveryMethods": { "type": "array", "description": "List of available delivery methods for consent requests.", "items": { "type": "string", "enum": [ "emailLink", "sms", "smsLink", "smsOTP" ] } }, "approvalBaseUrl": { "type": "string", "format": "uri", "default": "https://consent.gigs.com/consent", "description": "Base URL for consent approvals the user opens as a link. Absent when none of `deliveryMethods` delivers one." } } }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the project was created.", "examples": [ "2021-01-21T19:32:13Z" ] }, "image": { "type": [ "string", "null" ], "description": "Small-resolution project icon with an aspect ratio of `1:1`.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "https://a.gigscdn.net/p/gigs/icon.png" ] }, "legal": { "type": [ "object", "null" ], "description": "The legal address for the company that manages the project.", "properties": { "name": { "type": "string", "description": "The company's legal name.", "examples": [ "Gigs Inc." ] }, "city": { "type": "string", "description": "The city/municipality of the address.", "examples": [ "New York City" ] }, "country": { "type": "string", "description": "The ISO 3166-1 alpha-2 country code of the address.", "examples": [ "US" ] }, "line1": { "type": "string", "description": "The first line of the address, e.g. street and house number.", "examples": [ "129 West 81st Street" ] }, "line2": { "type": [ "string", "null" ], "description": "The second line of the address, e.g. apartment number.", "examples": [ "Apartment 5" ] }, "postalCode": { "type": "string", "description": "The postal code of the address.", "examples": [ "10024" ] }, "state": { "type": [ "string", "null" ], "description": "The state/province/region of the address.", "examples": [ "NY" ] } }, "required": [ "name", "city", "country", "line1", "line2", "postalCode", "state" ] }, "locales": { "type": "array", "description": "List of supported locales represented as [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag), ordered by preference.", "items": { "type": "string" }, "examples": [ [ "en-US" ] ] }, "name": { "type": "string", "description": "A human-readable name for the project.", "examples": [ "Gigs Connect" ] }, "organization": { "$ref": "#/components/schemas/organization" }, "payments": { "type": [ "object", "null" ], "description": "Configuration parameters for the project use of payments.", "properties": { "currency": { "type": "string", "format": "ISO 4217", "description": "Three-letter ISO 4217 currency code representing the currency of the project. Must be a supported currency.", "examples": [ "USD" ] }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "\n> #### Deprecated\n>\n> This property is deprecated and will be removed in the future.\n> Use the root-level field `type` instead.\n\n\nThe mode in which the payments operate.", "deprecated": true } }, "required": [ "currency", "mode" ] }, "subscriptionOwner": { "type": "string", "enum": [ "user", "company" ], "description": "Indicates which entity will be registered as the owner of the subscription with the providers. When `company` is selected the legal address associated with the project will be used for the registration." }, "support": { "type": [ "object", "null" ], "description": "Contact details for consumer support requests regarding the project.", "properties": { "email": { "type": [ "string", "null" ], "format": "email", "description": "A publicly available email address for consumer support requests regarding the project.", "examples": [ "support@gigs.com" ] }, "phoneNumber": { "type": [ "string", "null" ], "format": "E.164", "description": "A publicly available phone number in E.164 format for consumer support requests regarding the project.", "examples": [ "+12345678900" ] } }, "required": [ "email", "phoneNumber" ] }, "tax": { "type": [ "object", "null" ], "description": "Tax configuration for the project.", "properties": { "country": { "type": [ "string", "null" ], "description": "The ISO 3166-1 alpha-2 country code for tax purposes. This will be used as the fallback country for tax calculations when a more specific country cannot be determined (e.g. user address).", "examples": [ "US" ] } }, "required": [ "country" ] }, "type": { "type": "string", "enum": [ "live", "test" ], "description": "Indicates whether this is a live or test project. In live projects, subscriptions are invoiced to your organization, and any payments and taxes are real. The type cannot be changed after project creation.", "examples": [ "live" ] } }, "required": [ "object", "id", "billing", "consent", "image", "legal", "locales", "name", "organization", "payments", "subscriptionOwner", "support", "tax", "type", "createdAt" ] }, "projectCredentials": { "type": "object", "title": "ProjectCredentials", "properties": { "object": { "type": "string", "const": "projectCredentials", "description": "Type of object is always `projectCredentials`." }, "paymentsKey": { "type": [ "string", "null" ], "description": "Publishable API key for payment integration.", "examples": [ "pk_test_XXooYYauvdEDq12NiTphI7sa" ] } }, "required": [ "object", "paymentsKey" ] }, "propertyErrorDetailError": { "type": "object", "title": "PropertyErrorDetail", "properties": { "object": { "type": "string", "const": "propertyErrorDetail", "description": "Type of object is always `propertyErrorDetail`." }, "code": { "type": "string", "description": "A machine-readable description of the error.", "examples": [ "propertyRequired" ] }, "message": { "type": "string", "description": "A human readable description of the error.", "examples": [ "Invalid value for property." ] }, "property": { "type": "string", "description": "Name of the property associated with the error.", "examples": [ "property1" ] }, "suggestion": { "type": [ "string", "null" ], "description": "Suggested alternative value for the field.", "examples": [ "alternative_value" ] } }, "required": [ "object", "code", "message", "property", "suggestion" ] }, "serviceProvider": { "type": "object", "title": "ServiceProvider", "properties": { "object": { "type": "string", "const": "serviceProvider", "description": "Type of object is always `serviceProvider`." }, "id": { "type": "string", "description": "Unique identifier for the service provider.", "examples": [ "svp_0SNlurA01K6GY5L0XJffY8" ] }, "country": { "type": "string", "format": "ISO 3166-1 alpha-2", "description": "The ISO 3166-1 alpha-2 country code of the service provider.", "examples": [ "US" ] }, "name": { "type": "string", "description": "The name of the service provider, usually a brand name.", "examples": [ "AT&T" ] }, "recipientProviders": { "type": "array", "default": [ "p3" ], "description": "List of network providers IDs that can receive portings from the service provider.", "items": { "type": "string", "examples": [ "p3" ] } } }, "required": [ "object", "id", "country", "name", "recipientProviders" ] }, "sim": { "type": "object", "title": "Sim", "description": "A SIM is a unique card that identifies itself to a specific mobile network and provides voice, text, and data connectivity to a user’s device. There are two types of available SIMs: eSIM and pSIM. eSIMs can be activated and installed instantly on any eSIM compatible device, pSIMs (physical SIMs) must be provided to the user or installed into the device beforehand.", "properties": { "object": { "type": "string", "const": "sim", "description": "Type of object is always `sim`." }, "id": { "type": "string", "description": "Unique identifier for the SIM.", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] }, "metadata": { "$ref": "#/components/schemas/metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the SIM was created.", "examples": [ "2021-01-21T19:38:34Z" ] }, "iccid": { "type": "string", "pattern": "^[0-9]{19,20}$", "description": "The ICCID (integrated circuit card identifier) associated with the SIM.", "examples": [ "89883070000007537119" ] }, "provider": { "type": "string", "description": "The ID of the network provider of the SIM.", "examples": [ "p9" ] }, "status": { "type": "string", "enum": [ "inactive", "active", "retired" ], "description": "The status of the SIM. Can be `active` or `inactive`." }, "suspension": { "type": [ "object", "null" ], "description": "The suspension of the SIM. A suspended SIM has no voice, SMS or data. `null` when the SIM is not suspended.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "properties": { "status": { "type": "string", "enum": [ "suspended", "suspending", "unsuspending" ], "description": "The status of the suspension. It can have one of the following values:\n\n- `suspending`: The suspension was requested and the network provider has not confirmed it yet.\n- `suspended`: The network provider confirmed the suspension.\n- `unsuspending`: A request to unsuspend the SIM was made and the network provider has not confirmed it yet. The SIM still has no service.\n", "examples": [ "suspended" ] }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time of the last transition of the suspension.", "examples": [ "2026-09-24T10:00:00Z" ] } }, "required": [ "status", "updatedAt" ], "examples": [ null ] }, "type": { "type": "string", "enum": [ "eSIM", "pSIM" ], "description": "The type of the SIM. Can be `eSIM` or `pSIM`." } }, "required": [ "object", "id", "metadata", "iccid", "provider", "status", "suspension", "type", "createdAt" ] }, "simCredentials": { "type": "object", "title": "SimCredentials", "properties": { "object": { "type": "string", "const": "simCredentials", "description": "Type of object is always `simCredentials`." }, "activationCode": { "type": [ "string", "null" ], "description": "eSIM activation code to download and install the profile in a device. Only available for type `eSIM`.", "examples": [ "LPA:1$smdp.gigs.com$2M-3L0MX-F8HE2" ] }, "androidInstallUrl": { "type": [ "string", "null" ], "description": "URL to install the eSIM profile on Android devices. Only available for type `eSIM`.\n\n\n\n> Be careful how you share this URL, it contains the credentials required to install the eSIM profile.", "examples": [ "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.gigs.com$2M-3L0MX-F8HE2" ] }, "iosInstallUrl": { "type": [ "string", "null" ], "description": "URL to install the eSIM profile on iOS devices. Only available for type `eSIM`.\n\n\n\n> Be careful how you share this URL, it contains the credentials required to install the eSIM profile.", "examples": [ "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.gigs.com$2M-3L0MX-F8HE2" ] }, "puk1": { "type": [ "string", "null" ], "description": "The first PUK code for the SIM. Not available for all network providers.", "examples": [ "12345678" ] }, "puk2": { "type": [ "string", "null" ], "description": "The second PUK code for the SIM. Not available for all network providers.", "examples": [ "12345678" ] }, "qrCodeUrl": { "type": [ "string", "null" ], "description": "URL of the activation code in QR-Code format. Only available for type `eSIM`.\n\n\n\n> Be careful how you share this URL, it can be accessed publicly without authentication.", "examples": [ "https://files.gigs.com/qrcode/example/pUNIvfeLBNQ.png" ] }, "sim": { "type": "string", "description": "Unique identifier for the SIM this credentials are for.", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] } }, "required": [ "object", "activationCode", "androidInstallUrl", "iosInstallUrl", "puk1", "puk2", "qrCodeUrl", "sim" ] }, "subscription": { "type": "object", "title": "Subscription", "description": "Subscriptions are tied to a user and are created once a user has a plan and SIM. This allows connectivity for their device and SIM.", "properties": { "object": { "type": "string", "const": "subscription", "description": "Type of object is always `subscription`." }, "id": { "type": "string", "description": "Unique identifier for the subscription.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] }, "metadata": { "$ref": "#/components/schemas/metadata" }, "activatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the subscription was activated.", "examples": [ "2021-01-21T19:38:34Z" ] }, "billing": { "type": [ "object", "null" ], "description": "Billing details for the subscription. Present when Billing is enabled on your project.", "properties": { "discount": { "type": [ "object", "null" ], "description": "Discount currently applied to the subscription. A discount created from a voucher with\nthe `once` recurrence type is used up by the first invoice it applies to, and is `null`\nafterwards. This includes the response to the request that applied it, and events\npublished later such as `subscription.activated`.\n", "properties": { "voucher": { "type": "string", "description": "The voucher that was applied to create this discount.", "examples": [ "vou_0SNlurA049MEWV0h2jfjkdiOdplN" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the discount expires. It may be in the past, if it has already expired.", "examples": [ "2021-02-20T19:38:34Z" ] } }, "required": [ "voucher", "expiresAt" ] }, "invoiceGracePeriodDays": { "type": [ "integer", "null" ], "description": "Number of days after renewal that an invoice can remain unpaid before it becomes overdue. After this period, the action specified in `invoiceOverdueAction` is triggered.\n\nWhen configured, this property takes precedence over the value set at the project level.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ 3 ] }, "invoiceOverduePeriodDays": { "type": [ "integer", "null" ], "description": "Number of days that invoices can remain overdue before subscriptions are ended.\n\nRelevant when subscriptions are not ended immediately after an invoice becomes overdue.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ 1 ] }, "invoiceOverdueAction": { "type": [ "string", "null" ], "enum": [ null, "end", "none", "restrict" ], "description": "Indicates what happens to the subscription when a renewal invoice becomes overdue. One of:\n\n- `none`: Leave the subscription as is.\n- `end`: End the subscription immediately.\n- `restrict`: Restrict the subscription's connectivity.\n\nWhen configured, this property takes precedence over the value set at the project level.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n" }, "restrictBehavior": { "type": [ "string", "null" ], "enum": [ null, "incomingOnly", "noData", "throttledData" ], "description": "Present when `invoiceOverdueAction` is `restrict`; nil otherwise.\nDetermines how subscriptions are restricted when an invoice becomes overdue. It can have one of the following values:\n\n- `incomingOnly`: The subscription line can receive calls & SMS, but cannot make calls, send SMS, or use data.\n- `noData`: The subscription line can make and receive calls & SMS, but cannot use data.\n- `throttledData`: The subscription line can still make and receive calls & SMS, and use up to 1GB of data at a reduced speed.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n" }, "restoreBehavior": { "type": [ "string", "null" ], "enum": [ null, "keepPeriodAnchor", "resetPeriodAnchor" ], "description": "Present when `invoiceOverdueAction` is `restrict`; nil otherwise.\nDetermines how subscriptions are restored once a subscription is restored (e.g. after payment of an overdue invoice). It can have one of the following values:\n\n- `resetPeriodAnchor`: The subscription cycle is reset to the date of restoration. This means the user has a whole new period to use their plan allowance that was just restored.\n- `keepPeriodAnchor`: The subscription cycle remains unchanged. The next renewal date stays the same as before the restriction.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n" } }, "required": [ "discount", "invoiceGracePeriodDays", "invoiceOverduePeriodDays", "invoiceOverdueAction", "restrictBehavior", "restoreBehavior" ] }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the subscription was canceled.", "examples": [ "2021-01-29T13:22:51Z" ] }, "cancellationDetails": { "type": [ "object", "null" ], "description": "Details about the cancellation of the subscription.", "properties": { "cause": { "type": [ "string", "null" ], "enum": [ "cancellationRequested", "deviceBlocked", "deviceNotSupported", "invoiceUnpaid", "paymentDisputed", "paymentFailed", "phoneNumberExpired", "phoneNumberPortedOut", "portingExpired", "projectDeleted", "simSuspensionExpired", "simUnusable", "subscriptionEnded", "suspectedPortOut", "userDeleted" ], "description": "Cause of subscription cancellation." }, "userComment": { "type": [ "string", "null" ], "description": "Comment from the user explaining the cancellation reason. It is only present when the userReason is other." }, "userReason": { "type": [ "string", "null" ], "enum": [ "connectivityIssues", "customerService", "noDetails", "other", "tooExpensive", "unused" ], "description": "Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested" } } }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the subscription was created.", "examples": [ "2021-01-21T19:32:13Z" ] }, "currentPeriod": { "anyOf": [ { "$ref": "#/components/schemas/period" }, { "type": "null" } ], "description": "Current subscription period. Only present for active subscriptions." }, "earliestEndAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest time at which the subscription can currently be ended. This\ndepends on the minimum period of the plan. This value is present after\nthe first period has already started, and before the subscription has\nended.\"\n", "examples": [ "2021-02-20T19:38:34Z" ] }, "endedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the subscription will end or has ended. This field is populated in different scenarios:\n- When a subscription is canceled, this represents the future date when it will be terminated\n- When a subscription has already ended, this represents the past date when it was terminated\n- For active subscriptions, this field is null\n", "examples": [ "2021-02-20T19:38:34Z" ] }, "firstUsageAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the subscription was first used.", "examples": [ "2021-01-21T19:38:34Z" ] }, "lastPorting": { "anyOf": [ { "$ref": "#/components/schemas/porting" }, { "type": "null" } ], "description": "Last porting (if any) related with the subscription." }, "phoneNumber": { "type": [ "string", "null" ], "format": "E.164", "description": "The phone number attached to the SIM in E.164 string_format. Only available for voice plans.", "examples": [ "+19591234567" ] }, "plan": { "$ref": "#/components/schemas/plan" }, "restoreRequestedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when a restore was requested for the subscription. It is set when a restore is accepted and cleared once the restore completes.", "examples": [ "2021-02-21T19:38:34Z" ] }, "restrictedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the subscription was restricted.", "examples": [ "2021-02-21T19:38:34Z" ] }, "restrictionDetails": { "type": [ "object", "null" ], "description": "Details about the restriction applied to the subscription. Present when the subscription is restricted.", "properties": { "restrictBehavior": { "type": "string", "enum": [ "incomingOnly", "noData", "throttledData" ], "description": "Determines how the subscription is restricted. It can have one of the following values:\n\n- `incomingOnly`: The subscription line can receive calls & SMS, but cannot make calls, send SMS, or use data.\n- `noData`: The subscription line can make and receive calls & SMS, but cannot use data.\n- `throttledData`: The subscription line can still make and receive calls & SMS, and use up to 1GB of data at a reduced speed.\n", "examples": [ "incomingOnly" ] }, "restoreBehavior": { "type": "string", "enum": [ "keepPeriodAnchor", "resetPeriodAnchor" ], "description": "Determines how the subscription is restored. It can have one of the following values:\n\n- `resetPeriodAnchor`: The subscription cycle is reset to the date of restoration. This means the user has a whole new period to use their plan allowance that was just restored.\n- `keepPeriodAnchor`: The subscription cycle remains unchanged. The next renewal date stays the same as before the restriction.\n", "examples": [ "resetPeriodAnchor" ] }, "cause": { "type": "string", "enum": [ "invoiceOverdue", "restrictionRequested" ], "description": "Determines the cause that triggered the subscription restriction. It can have one of the following values:\n\n- `invoiceOverdue`: The subscription was automatically restricted due to an unpaid invoice that has become overdue.\n- `restrictionRequested`: The subscription was manually restricted due to an explicit request.\n", "examples": [ "invoiceOverdue" ] } }, "required": [ "restrictBehavior", "restoreBehavior", "cause" ] }, "sim": { "anyOf": [ { "$ref": "#/components/schemas/sim" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "initiated", "active", "restricted", "ended" ], "description": "The current status of the subscription. Note that the `initiated` status\nis currently only available when using the Billing API, where it implies\nthat the subscription's first invoice has not yet been paid.\n" }, "user": { "$ref": "#/components/schemas/user" }, "userAddress": { "type": [ "string", "null" ], "description": "Current [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) identifier (if any) related with the subscription.", "examples": [ "adr_0SNlurA049MEWV5ELDmnaqVXgTFT" ] }, "porting": { "anyOf": [ { "$ref": "#/components/schemas/porting" }, { "type": "null" } ], "description": "First porting requested by the user. Refer to `lastPorting` to get the latest porting information.", "deprecated": true } }, "required": [ "object", "id", "metadata", "billing", "cancellationDetails", "currentPeriod", "lastPorting", "phoneNumber", "plan", "restrictionDetails", "sim", "status", "user", "userAddress", "porting", "activatedAt", "restrictedAt", "restoreRequestedAt", "canceledAt", "createdAt", "earliestEndAt", "endedAt", "firstUsageAt" ] }, "subscriptionAddon": { "type": "object", "title": "SubscriptionAddon", "description": "Subscription add-ons are features or top-ups that extend the functionality offered to the end user through their subscription, as defined by the associated add-on.", "properties": { "object": { "type": "string", "const": "subscriptionAddon", "description": "Type of object is always `subscriptionAddon`." }, "id": { "type": "string", "description": "Unique identifier for the subscription add-on.", "examples": [ "sad_0SNlurA049MEWV2UNWPbDfW5B40U" ] }, "activatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the subscription add-on was activated.", "examples": [ "2021-01-15T12:36:57Z" ] }, "addon": { "$ref": "#/components/schemas/addon", "description": "The add-on associated to the subscription add-on." }, "billing": { "type": [ "object", "null" ], "description": "Billing details for the subscription add-on. Present when the add-on has billing settings.", "properties": { "discount": { "type": [ "object", "null" ], "description": "Discount currently applied to the subscription add-on. A discount created from a voucher\nwith the `once` recurrence type is used up by the first invoice it applies to, and is\n`null` afterwards. This includes the response to the request that applied it and events\npublished later.\n", "properties": { "voucher": { "type": "string", "description": "The voucher that was applied to create this discount.", "examples": [ "vou_0SNlurA049MEWV0h2jfjkdiOdplN" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the discount expires. It may be in the past, if it has already expired.", "examples": [ "2021-02-20T19:38:34Z" ] } }, "required": [ "voucher", "expiresAt" ] } }, "required": [ "discount" ] }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the subscription add-on was canceled.", "examples": [ "2021-01-22T19:39:53Z" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the subscription add-on was created.", "examples": [ "2021-01-15T12:30:28Z" ] }, "currentPeriod": { "anyOf": [ { "$ref": "#/components/schemas/period" }, { "type": "null" } ], "description": "Current subscription add-on period. The value is `null` unless the subscription add-on is active. For a recurring add-on, `number` counts from `1` to the add-on's `validity.totalPeriods`, and each period lasts one validity period of the add-on, the first one starting when the subscription add-on was activated." }, "endedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the subscription add-on will end or has ended. This field is populated in different scenarios:\n- For an active recurring add-on, this represents the future date when its last period ends. It is set shortly after activation\n- When a subscription add-on has ended, this represents the past date when it ended\n- Otherwise, this field is null\n", "examples": [ "2021-01-30T23:12:28Z" ] }, "status": { "type": "string", "enum": [ "pending", "initiated", "active", "ended" ], "description": "The current status of the subscription add-on.\n\n- `initiated`: Created, but waiting on a prerequisite (typically an unpaid invoice) before it can be activated.\n- `pending`: Cleared to activate and awaiting provisioning on the network provider.\n- `active`: Provisioned and usable.\n- `ended`: Terminated, for example when its allowance is used up, its validity elapses, or it is removed.\n" }, "subscription": { "type": "string", "description": "Unique identifier of the subscription the add-on applies to.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] }, "user": { "type": "string", "description": "Unique identifier of the user the subscription add-on belongs to.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, "required": [ "object", "id", "addon", "billing", "currentPeriod", "status", "subscription", "user", "activatedAt", "createdAt", "endedAt", "canceledAt" ] }, "subscriptionChange": { "type": "object", "title": "SubscriptionChange", "description": "Any change to a user’s subscription, such as swapping a SIM, or upgrading or downgrading a subscription.", "properties": { "object": { "type": "string", "const": "subscriptionChange", "description": "Type of object is always `subscriptionChange`." }, "id": { "type": "string", "description": "Unique identifier for the subscription change.", "examples": [ "sch_0SNlurA049MEWV3bE0SMtbIEJApp" ] }, "appliedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the subscription change was applied.", "examples": [ "2021-01-21T19:36:57Z" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the subscription change was created.", "examples": [ "2021-01-21T19:12:28Z" ] }, "failureCode": { "type": [ "string", "null" ], "description": "An error code indicating the reason for a failed subscription change.", "examples": [ "consentNotGiven" ] }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/plan" }, { "type": "null" } ], "description": "The plan to which the subscription should be changed." }, "requestedChange": { "type": "object", "description": "Object with the requested changes.", "properties": { "plan": { "type": [ "string", "null" ], "description": "Unique identifier of the target plan, to which the subscription should be changed. The new plan must have the same type of validity as the one it's replacing. E.g. a `oneTime` plan cannot be replaced by a `recurring` one. If the new plan's validity has a different `unit` or `value` than the plan it's replacing, then the change must be scheduled for the next renewal. See property `\"when\"` for more information about scheduling options for subscription change.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] }, "sim": { "type": [ "string", "null" ], "description": "Unique identifier of the target SIM, to which the subscription should be changed. Can also be set to \"auto\", in which case an eSIM will be automatically allocated.", "examples": [ "sim_0SNlurA049MEWV1BAAmWZULA4lf6" ] }, "phoneNumber": { "type": [ "string", "null" ], "description": "Set to \"auto\" when the subscription's phone number should be changed to a new one assigned by the network provider.", "examples": [ "auto" ] }, "when": { "type": "string", "enum": [ "now", "renewal" ], "description": "When the change should take effect. If set to `\"now\"`, the change will take effect immediately. If set to `\"renewal\"`, the change will instead take effect at the next subscription renewal date. Plan changes can always happen on `\"renewal\"`, but only selected network providers allow `\"now\"` changes. SIM changes can only happen `\"now\"`.", "examples": [ "renewal" ] } }, "required": [ "sim", "plan", "phoneNumber", "when" ] }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Approximate time when the change should take place. This is typically set for changes scheduled at renewal. For changes that take effect immediately (when `requestedChange.when` is `\"now\"`), this may be null.", "examples": [ "2021-01-21T19:12:28Z" ] }, "sim": { "anyOf": [ { "$ref": "#/components/schemas/sim" }, { "type": "null" } ], "description": "The SIM to which the subscription should be changed." }, "status": { "type": "string", "enum": [ "pending", "initiated", "applied", "failed", "deleted" ], "description": "The current status of the subscription change. Note that the `initiated` status\nis currently only available when using the Billing API, where it implies that\nthe subscription change invoice has not yet been paid.\n" }, "subscription": { "type": [ "string", "null" ], "description": "Unique identifier of the subscription to be changed.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, "required": [ "object", "id", "failureCode", "plan", "requestedChange", "scheduledAt", "sim", "status", "subscription", "appliedAt", "createdAt" ] }, "subscriptionGroup": { "type": "object", "title": "SubscriptionGroup", "description": "A subscription group represents a collection of subscriptions.\n\n\n> #### Preview\n>\n> This schema is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "properties": { "object": { "type": "string", "const": "subscriptionGroup", "description": "Type of object is always `subscriptionGroup`." }, "id": { "type": "string", "description": "Unique identifier for the subscription group.", "examples": [ "sgr_0SNlurA049MEWV26leJMWPp4o23C" ] }, "subscriptions": { "type": "array", "description": "List of subscription identifiers that belong to this group.", "items": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, "type": { "type": "string", "enum": [ "discountGroup", "familyPlan" ], "description": "The type of the subscription group. The object with the same name holds the fields of that type.", "examples": [ "familyPlan" ] }, "status": { "type": "string", "enum": [ "active", "draft" ], "description": "The status of the subscription group.", "examples": [ "active" ] }, "discountGroup": { "type": [ "object", "null" ], "description": "Fields of a group with the `discountGroup` type. Only present when `type` is `discountGroup`.", "properties": {} }, "familyPlan": { "type": [ "object", "null" ], "description": "Fields of a group with the `familyPlan` type. Only present when `type` is `familyPlan`.", "properties": { "primarySubscription": { "type": [ "string", "null" ], "description": "The subscription that receives the consent requests for the other subscriptions in the group. Cannot be changed once the group is active.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] }, "plan": { "type": "string", "description": "The plan that every subscription in the family plan must be on. Cannot be changed after creation.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] } }, "required": [ "primarySubscription", "plan" ] }, "activatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the subscription group was activated. A discount group is activated when it is created. A family plan is activated through the activate subscription group endpoint. It is null while the family plan is a draft.", "examples": [ "2021-01-21T19:38:34Z" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the subscription group was created.", "examples": [ "2021-01-21T19:32:13Z" ] } }, "required": [ "object", "id", "subscriptions", "type", "status", "activatedAt", "createdAt" ] }, "usageBalance": { "type": "object", "title": "UsageBalance", "description": "A usage balance represents the amount of usage consumed from an [Allowance](https://developers.gigs.com/core/schemas/allowance) for a given [Subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource) in a certain Period.", "properties": { "object": { "type": "string", "const": "usageBalance", "description": "Type of object is always `usageBalance`." }, "id": { "type": "string", "description": "Unique identifier for the usage balance.", "examples": [ "ubl_0V9n0zo90CE0NuvcsN0j88" ] }, "allowance": { "$ref": "#/components/schemas/allowance", "description": "The [Allowance](https://developers.gigs.com/core/schemas/allowance) this usage balance is tracking." }, "subscription": { "type": "string", "description": "Unique identifier of the [Subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource) the usage balance is related to.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] }, "source": { "$ref": "#/components/schemas/usageBalanceSource", "description": "The entity providing the allowance to the [Subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource)." }, "unit": { "type": "string", "enum": [ "bytes", "seconds", "messages" ], "description": "The unit the usage is counted in." }, "used": { "type": "integer", "description": "The amount of usage consumed, counted in `unit`.", "examples": [ 230 ] }, "limit": { "type": [ "integer", "null" ], "description": "The amount of usage permitted by the associated allowance counted in `unit`. A value of `null` indicates an unlimited allowance.", "examples": [ 500 ] }, "remaining": { "type": [ "integer", "null" ], "description": "The amount remaining that can still be consumed, counted in `unit`. A value of `null` indicates an unlimited allowance.", "examples": [ 270 ] }, "usedPercent": { "type": [ "integer", "null" ], "description": "The percentage of `limit` that has been used, expressed as an integer between 0 and 100. A value of `null` indicates an unlimited allowance.", "examples": [ 46 ] }, "remainingPercent": { "type": [ "integer", "null" ], "description": "The percentage of `limit` that has not been used, expressed as an integer between 0 and 100. A value of `null` indicates an unlimited allowance.", "examples": [ 54 ] }, "usableFrom": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp representing the beginning of this usage balance's validity. A value of `null` indicates a Balance that is not yet active, for example when a Subscription is still pending.", "examples": [ "2026-01-03T13:41:24Z" ] }, "usableUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp representing the end of this usage balance's validity. A value of `null` indicates a Balance that is not yet active, for example when a Subscription is still pending.", "examples": [ "2026-02-03T13:41:24Z" ] } }, "required": [ "object", "id", "allowance", "subscription", "source", "unit", "used", "limit", "remaining", "usedPercent", "remainingPercent", "usableFrom", "usableUntil" ], "examples": [ { "object": "usageBalance", "id": "ubl_0V9n0zo90CE0NuvcsN0j88", "allowance": { "object": "allowance", "id": "alw_0SNlurA049MEWV3OMTRrGKbd99GH", "name": "Roaming data in Europe", "type": "data", "coverage": { "object": "coverage", "id": "de", "countries": [ "DE", "FR", "US" ], "name": "Europe" }, "limit": 500, "unit": "bytes", "priority": 1 }, "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "source": { "type": "subscriptionPeriod", "subscriptionPeriod": 4, "subscriptionAddon": null }, "unit": "bytes", "used": 230, "limit": 500, "remaining": 270, "usedPercent": 46, "remainingPercent": 54, "usableFrom": "2026-01-03T13:41:24Z", "usableUntil": "2026-02-03T13:41:24Z" } ] }, "usageBalanceSource": { "type": "object", "title": "UsageBalanceSource", "description": "The entity providing the [Allowance](https://developers.gigs.com/core/allowances#the-allowance-resource) to the [Subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource).", "properties": { "type": { "type": "string", "enum": [ "subscriptionPeriod", "subscriptionAddon" ], "description": "The entity type providing the allowance." }, "subscriptionPeriod": { "type": [ "integer", "null" ], "description": "When the allowance is provided by the subscription's plan, the subscription period this usage balance is bound by.", "examples": [ 4 ] }, "subscriptionAddon": { "type": [ "string", "null" ], "description": "When the allowance is provided by a [Subscription Add-on](https://developers.gigs.com/core/subscription-add-ons#the-subscription-add-on-resource), the subscription add-on this usage balance is provided by.", "examples": [ "sad_0SNlurA049MEWV2UNWPbDfW5B40U" ] } }, "required": [ "type" ], "examples": [ { "type": "subscriptionPeriod", "subscriptionPeriod": 4, "subscriptionAddon": null }, { "type": "subscriptionAddon", "subscriptionPeriod": null, "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U" } ] }, "usageRecord": { "type": "object", "title": "UsageRecord", "description": "Usage records track subscription usage for users. This includes data, voice, and text usage. Note that there is a delay in usage data that varies between carriers.", "properties": { "object": { "type": "string", "const": "usageRecord", "description": "Type of object is always `usageRecord`." }, "data": { "type": "integer", "description": "Amount of data used in bytes.", "examples": [ 18883100 ] }, "dataDeviceBytes": { "type": "integer", "description": "Amount of on-device data used in bytes.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ 30029300 ] }, "dataTetheringBytes": { "type": "integer", "description": "Amount of tethering data used in bytes.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ 30029300 ] }, "end": { "type": "string", "format": "date-time", "description": "Timestamp representing the exclusive upper bound of the aggregation period (e.g. the end of a 24 hour period, subscription period or user-defined set of dates).", "examples": [ "2021-02-15T00:00:00Z" ] }, "labels": { "type": "object", "description": "An object containing optional metadata about the usage record.", "properties": { "country": { "type": "string", "description": "The ISO 3166-1 alpha-2 country code of the country in which the usage occurred.", "examples": [ "US" ] }, "roaming": { "type": "string", "enum": [ "none", "international", "domestic" ], "description": "The roaming mode the usage occurred in.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n" }, "subscription": { "type": "string", "description": "The unique identifier for the subscription to which the usage is attributed.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, "required": [], "additionalProperties": true }, "sms": { "type": "integer", "description": "Amount of SMS messages sent and received.", "examples": [ 15 ] }, "smsInternationalMessages": { "type": "integer", "description": "Amount of SMS messages sent internationally.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ 6 ] }, "smsLocalMessages": { "type": "integer", "description": "Amount of SMS messages sent locally.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ 6 ] }, "start": { "type": "string", "format": "date-time", "description": "Timestamp representing the inclusive lower bound of the aggregation period (e.g. the start of a 24 hour period, subscription period or user-defined set of dates)", "examples": [ "2021-02-14T00:00:00Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "description": "The time at which the aggregation was last updated.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "2024-02-15T12:13:14Z" ] }, "voice": { "type": "integer", "description": "Amount of voice usage in seconds.", "examples": [ 240 ] }, "voiceInternationalSeconds": { "type": "integer", "description": "Amount of international voice usage in seconds.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ 125 ] }, "voiceLocalSeconds": { "type": "integer", "description": "Amount of local voice usage in seconds.\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ 6 ] } }, "required": [ "object", "data", "end", "labels", "sms", "start", "voice" ] }, "user": { "type": "object", "title": "User", "description": "Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions.", "properties": { "object": { "type": "string", "const": "user", "description": "Type of object is always `user`." }, "id": { "type": "string", "description": "Unique identifier for the user.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] }, "metadata": { "$ref": "#/components/schemas/metadata" }, "birthday": { "type": [ "string", "null" ], "format": "date", "description": "The birthday of the user.", "examples": [ "2017-07-21" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the user was created.", "examples": [ "2021-01-21T19:38:34Z" ] }, "email": { "type": "string", "format": "email", "description": "The primary email address of the user. Must be unique across all users.", "examples": [ "jerry@example.com" ] }, "emailVerified": { "type": "boolean", "description": "Whether the user's primary email address is verified or not.", "examples": [ true ] }, "fullName": { "type": [ "string", "null" ], "description": "The user's full name. Required for some Plans.", "examples": [ "Jerry Seinfeld" ] }, "preferredLocale": { "type": "string", "description": "The user's locale preference represented as an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag).", "examples": [ "en-US" ] }, "status": { "type": "string", "enum": [ "active", "blocked", "deleted" ], "description": "The current status of the user." } }, "required": [ "object", "id", "metadata", "birthday", "email", "emailVerified", "fullName", "preferredLocale", "createdAt", "status" ] }, "userAddress": { "type": "object", "title": "UserAddress", "properties": { "object": { "type": "string", "const": "userAddress", "description": "Type of object is always `userAddress`." }, "id": { "type": "string", "description": "Unique identifier for the address.", "examples": [ "adr_0SNlurA049MEWV5ELDmnaqVXgTFT" ] }, "city": { "type": "string", "description": "The city/municipality of the address.", "examples": [ "New York City" ] }, "country": { "type": "string", "description": "The ISO 3166-1 alpha-2 country code of the address.", "examples": [ "US" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "The time the address was created.", "examples": [ "2021-01-21T19:38:34Z" ] }, "line1": { "type": "string", "description": "The first line of the address, e.g. street and house number.", "examples": [ "129 West 81st Street" ] }, "line2": { "type": [ "string", "null" ], "description": "The second line of the address, e.g. apartment number.", "examples": [ "Apartment 5" ] }, "postalCode": { "type": [ "string", "null" ], "description": "The postal code of the address.", "examples": [ "10024" ] }, "state": { "type": [ "string", "null" ], "description": "The state/province/region of the address.", "examples": [ "NY" ] }, "user": { "type": "string", "description": "Unique identifier for the address user.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, "required": [ "object", "id", "city", "country", "line1", "line2", "postalCode", "state", "user", "createdAt" ] }, "virtualNumber": { "type": "object", "title": "VirtualNumber", "description": "Virtual numbers are additional numbers that can be added for a user. Any calls made or texts sent to an active virtual number will be received by the primary number of the `subscription`. Note that this is an experimental feature that is only available in select projects.\n\n\n> #### Preview\n>\n> This schema is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "properties": { "object": { "type": "string", "const": "virtualNumber", "description": "Type of object is always `virtualNumber`." }, "id": { "type": "string", "description": "Unique identifier for the virtual number.", "examples": [ "vnr_0SNlurA049MEWV29mxRtSMDnKtUD" ] }, "activatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the virtual number was activated.", "examples": [ "2020-01-01T00:00:07Z" ] }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the virtual number was canceled.", "examples": [ "2020-07-15T00:00:00Z" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the virtual number was created.", "examples": [ "2020-01-01T00:00:00Z" ] }, "endedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the virtual number will end or has ended. This field is populated in different scenarios:\n- When a virtual number is canceled, this represents the future date when it will be terminated\n- When a virtual number has already ended, this represents the past date when it was terminated\n", "examples": [ "2020-08-01T00:00:00Z" ] }, "phoneNumber": { "type": [ "string", "null" ], "format": "E.164", "description": "The virtual phone number.", "examples": [ "+447700900000" ] }, "status": { "type": "string", "enum": [ "active", "ended", "initiated", "processing" ], "description": "The current status of the virtual number.", "examples": [ "active" ] }, "subscription": { "type": "string", "description": "Unique identifier for the subscription this virtual number belongs to.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] }, "user": { "type": "string", "description": "Unique identifier for the user this virtual number belongs to.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, "required": [ "object", "id", "activatedAt", "canceledAt", "createdAt", "endedAt", "phoneNumber", "status", "subscription", "user" ] } }, "responses": { "badRequest": { "description": "The request has incorrect syntax, such as an unparseable JSON body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "error", "code": "unknown", "details": [ { "object": "propertyErrorDetail", "code": "propertyRequired", "message": "Invalid value for property.", "property": "property1", "suggestion": "alternative_value" } ], "documentation": [ "https://developers.gigs.com/api/error-handling" ], "hint": "Parameter iccid must match /^([0-9]{19}F?|[0-9]{20})$/i", "message": "Invalid ICCID format.", "type": "invalid" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "error", "message": "Invalid ICCID format.", "type": "invalid" } } } } } }, "notFound": { "description": "The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "error", "code": "unknown", "details": [ { "object": "propertyErrorDetail", "code": "propertyRequired", "message": "Invalid value for property.", "property": "property1", "suggestion": "alternative_value" } ], "documentation": [ "https://developers.gigs.com/api/error-handling" ], "hint": "Parameter iccid must match /^([0-9]{19}F?|[0-9]{20})$/i", "message": "Invalid ICCID format.", "type": "invalid" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "error", "message": "Invalid ICCID format.", "type": "invalid" } } } } } }, "permissionDenied": { "description": "The authenticated user doesn't have permissions to perform the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "error", "code": "unknown", "details": [ { "object": "propertyErrorDetail", "code": "propertyRequired", "message": "Invalid value for property.", "property": "property1", "suggestion": "alternative_value" } ], "documentation": [ "https://developers.gigs.com/api/error-handling" ], "hint": "Parameter iccid must match /^([0-9]{19}F?|[0-9]{20})$/i", "message": "Invalid ICCID format.", "type": "invalid" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "error", "message": "Invalid ICCID format.", "type": "invalid" } } } } } }, "conflict": { "description": "The request conflicts with another request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "error", "code": "unknown", "details": [ { "object": "propertyErrorDetail", "code": "propertyRequired", "message": "Invalid value for property.", "property": "property1", "suggestion": "alternative_value" } ], "documentation": [ "https://developers.gigs.com/api/error-handling" ], "hint": "Parameter iccid must match /^([0-9]{19}F?|[0-9]{20})$/i", "message": "Invalid ICCID format.", "type": "invalid" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "error", "message": "Invalid ICCID format.", "type": "invalid" } } } } } }, "unprocessableEntity": { "description": "The request can't be processed, often due to an invalid parameter or incompatible system state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "error", "code": "unknown", "details": [ { "object": "propertyErrorDetail", "code": "propertyRequired", "message": "Invalid value for property.", "property": "property1", "suggestion": "alternative_value" } ], "documentation": [ "https://developers.gigs.com/api/error-handling" ], "hint": "Parameter iccid must match /^([0-9]{19}F?|[0-9]{20})$/i", "message": "Invalid ICCID format.", "type": "invalid" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "error", "message": "Invalid ICCID format.", "type": "invalid" } } } } } }, "notImplemented": { "description": "The type of request is not supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "error", "code": "unknown", "details": [ { "object": "propertyErrorDetail", "code": "propertyRequired", "message": "Invalid value for property.", "property": "property1", "suggestion": "alternative_value" } ], "documentation": [ "https://developers.gigs.com/api/error-handling" ], "hint": "Parameter iccid must match /^([0-9]{19}F?|[0-9]{20})$/i", "message": "Invalid ICCID format.", "type": "invalid" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "error", "message": "Invalid ICCID format.", "type": "invalid" } } } } } }, "serviceUnavailable": { "description": "The network provider required to perform the request is currently unavailable. Please check [documentation](https://developers.gigs.com/api/error-handling#common-errors) for details on how to handle this error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "error", "code": "unknown", "details": [ { "object": "propertyErrorDetail", "code": "propertyRequired", "message": "Invalid value for property.", "property": "property1", "suggestion": "alternative_value" } ], "documentation": [ "https://developers.gigs.com/api/error-handling" ], "hint": "Parameter iccid must match /^([0-9]{19}F?|[0-9]{20})$/i", "message": "Invalid ICCID format.", "type": "invalid" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "error", "message": "Invalid ICCID format.", "type": "invalid" } } } } } } }, "parameters": { "addon": { "name": "addon", "in": "path", "description": "The unique identifier for the add-on.", "required": true, "schema": { "type": "string", "examples": [ "add_0SNlurA049MEWV4VxLfwJc7PJtHc" ] } }, "listAfter": { "name": "after", "in": "query", "description": "A cursor for use in pagination. The `after` parameter takes an object ID that defines the position in the list, only items immediately following the item with that ID will be returned.", "required": false, "schema": { "type": "string" } }, "listBefore": { "name": "before", "in": "query", "description": "A cursor for use in pagination. The `before` parameter takes an object ID that defines the position in the list, only items immediately preceding the item with that ID will be returned.", "required": false, "schema": { "type": "string" } }, "listLimit": { "name": "limit", "in": "query", "description": "The limit of items to be returned in the list, between 0 and 200.", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 200, "minimum": 0, "examples": [ 20 ] } }, "plan": { "name": "plan", "in": "path", "description": "The unique identifier for the plan.", "required": true, "schema": { "type": "string", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] } }, "project": { "name": "project", "in": "path", "description": "The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource).", "required": true, "schema": { "type": "string", "examples": [ "gigs" ] } }, "subscriptionGroup": { "name": "subscriptionGroup", "in": "path", "description": "The unique identifier for the subscription group.", "required": true, "schema": { "type": "string", "examples": [ "sgr_0SNlurA049MEWV26leJMWPp4o23C" ] } }, "user": { "name": "user", "in": "path", "description": "The unique identifier for the user.", "required": true, "schema": { "type": "string", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Add-ons", "description": "Operations to manage add-ons." }, { "name": "Consent Requests", "description": "Operations to manage consent requests." }, { "name": "Devices", "description": "Operations to manage devices." }, { "name": "Network Availabilities", "description": "Operations to lookup network availability information." }, { "name": "Plans", "description": "Operations to manage plans." }, { "name": "Portings", "description": "Operations to manage portings." }, { "name": "Port Outs", "description": "Operations to manage port outs." }, { "name": "Projects", "description": "Operations to manage projects." }, { "name": "SIMs", "description": "Operations to manage SIMs." }, { "name": "Subscriptions", "description": "Operations to manage subscriptions." }, { "name": "Subscription Add-ons", "description": "Operations to manage subscription add-ons." }, { "name": "Subscription Changes", "description": "Operations to manage subscription changes." }, { "name": "Usage", "description": "View usage records." }, { "name": "Usage Balances", "description": "Operations to manage usage balances." }, { "name": "Users", "description": "Operations to manage users." }, { "name": "User Addresses", "description": "Operations to manage user addresses." } ] }