swagger: '2.0'
info:
title: Microsoft Azure Programmable Connectivity
version: 2024-02-09-preview
description: >-
Azure Programmable Connectivity (APC) provides a unified interface to the
Network APIs of multiple Telecom Operators. Note that Operators may
deprecate a Network API with less advance notice than the Azure standard, in
which case APC will also deprecate that Network API.
x-typespec-generated:
- emitter: '@azure-tools/typespec-autorest'
schemes:
- https
x-ms-parameterized-host:
hostTemplate: '{endpoint}'
useSchemePrefix: false
parameters:
- name: endpoint
in: path
description: >-
An Azure Programmable Connectivity Endpoint providing access to Network
APIs, for example https://{region}.apcgatewayapi.azure.com
required: true
type: string
produces:
- application/json
consumes:
- application/json
security:
- OAuth2Auth:
- https://management.azure.com//.default
securityDefinitions:
OAuth2Auth:
type: oauth2
flow: implicit
authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
scopes:
https://management.azure.com//.default: ''
tags:
- name: Device Location
- name: Device Network
- name: Number Verification
- name: Sim Swap
paths:
/device-location/location:verify:
post:
operationId: microsoftAzureDevicelocationVerify
description: >-
Verifies whether a device is within a specified location area, defined
as an accuracy (radius) around a point, specified by longitude and
latitude.
parameters:
- $ref: '#/parameters/Azure.Core.Foundations.ApiVersionParameter'
- $ref: '#/parameters/Azure.Core.ClientRequestIdHeader'
- $ref: '#/parameters/ApcGatewayIdHeader'
- name: body
in: body
required: true
schema:
$ref: '#/definitions/DeviceLocationVerificationContent'
responses:
'200':
description: The request has succeeded.
schema:
$ref: '#/definitions/DeviceLocationVerificationResult'
headers:
x-ms-client-request-id:
type: string
format: uuid
description: >-
An opaque, globally-unique, client-generated string identifier
for the request.
x-ms-request-id:
type: string
format: uuid
description: >-
An opaque, globally-unique, server-generated string identifier
for the request.
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/Azure.Core.Foundations.ErrorResponse'
headers:
x-ms-error-code:
type: string
description: String error code indicating what went wrong.
x-ms-examples:
DeviceLocation_Verify:
$ref: ./examples/DeviceLocation_Verify_MaximumSet_Gen.json
summary: Microsoft Azure Post Device Location Location:verify
tags:
- Device Location
/device-network/network:retrieve:
post:
operationId: microsoftAzureDevicenetworkRetrieve
description: >-
Retrieves the network a given device is on. Returns network in a
networkCode format that can be used for other APIs.
parameters:
- $ref: '#/parameters/Azure.Core.Foundations.ApiVersionParameter'
- $ref: '#/parameters/Azure.Core.ClientRequestIdHeader'
- $ref: '#/parameters/ApcGatewayIdHeader'
- name: body
in: body
required: true
schema:
$ref: '#/definitions/NetworkIdentifier'
responses:
'200':
description: The request has succeeded.
schema:
$ref: '#/definitions/NetworkRetrievalResult'
headers:
x-ms-client-request-id:
type: string
format: uuid
description: >-
An opaque, globally-unique, client-generated string identifier
for the request.
x-ms-request-id:
type: string
format: uuid
description: >-
An opaque, globally-unique, server-generated string identifier
for the request.
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/Azure.Core.Foundations.ErrorResponse'
headers:
x-ms-error-code:
type: string
description: String error code indicating what went wrong.
x-ms-examples:
DeviceNetwork_Retrieve:
$ref: ./examples/DeviceNetwork_Retrieve_MaximumSet_Gen.json
summary: Microsoft Azure Post Device Network Network:retrieve
tags:
- Device Network
/number-verification/number:verify:
post:
operationId: microsoftAzureNumberverificationVerifywithoutcode
description: >-
Verifies the phone number (MSISDN) associated with a device. As part of
the frontend authorization flow, the device is redirected to the
operator network to authenticate directly.
parameters:
- $ref: '#/parameters/Azure.Core.Foundations.ApiVersionParameter'
- $ref: '#/parameters/Azure.Core.ClientRequestIdHeader'
- $ref: '#/parameters/ApcGatewayIdHeader'
- name: body
in: body
required: true
schema:
$ref: '#/definitions/NumberVerificationWithoutCodeContent'
responses:
'302':
description: Redirection
headers:
location:
type: string
format: uri
description: >-
The URI of the network's authorization endpoint, which should be
followed by the front-end application.
x-ms-client-request-id:
type: string
format: uuid
description: >-
An opaque, globally-unique, client-generated string identifier
for the request.
x-ms-request-id:
type: string
format: uuid
description: >-
An opaque, globally-unique, server-generated string identifier
for the request.
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/Azure.Core.Foundations.ErrorResponse'
headers:
x-ms-error-code:
type: string
description: String error code indicating what went wrong.
x-ms-examples:
NumberVerification_VerifyWithoutCode:
$ref: ./examples/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json
summary: Microsoft Azure Post Number Verification Number:verify
tags:
- Number Verification
/sim-swap/sim-swap:retrieve:
post:
operationId: microsoftAzureSimswapRetrieve
description: Provides timestamp of latest SIM swap
parameters:
- $ref: '#/parameters/Azure.Core.Foundations.ApiVersionParameter'
- $ref: '#/parameters/Azure.Core.ClientRequestIdHeader'
- $ref: '#/parameters/ApcGatewayIdHeader'
- name: body
in: body
required: true
schema:
$ref: '#/definitions/SimSwapRetrievalContent'
responses:
'200':
description: The request has succeeded.
schema:
$ref: '#/definitions/SimSwapRetrievalResult'
headers:
x-ms-client-request-id:
type: string
format: uuid
description: >-
An opaque, globally-unique, client-generated string identifier
for the request.
x-ms-request-id:
type: string
format: uuid
description: >-
An opaque, globally-unique, server-generated string identifier
for the request.
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/Azure.Core.Foundations.ErrorResponse'
headers:
x-ms-error-code:
type: string
description: String error code indicating what went wrong.
x-ms-examples:
SimSwap_Retrieve:
$ref: ./examples/SimSwap_Retrieve_MaximumSet_Gen.json
summary: Microsoft Azure Post Sim Swap Sim Swap:retrieve
tags:
- Sim Swap
/sim-swap/sim-swap:verify:
post:
operationId: microsoftAzureSimswapVerify
description: >-
Verifies if a SIM swap has been performed during a past period (defined
in the request with 'maxAgeHours' attribute). Returns 'True' if a SIM
swap has occured.
parameters:
- $ref: '#/parameters/Azure.Core.Foundations.ApiVersionParameter'
- $ref: '#/parameters/Azure.Core.ClientRequestIdHeader'
- $ref: '#/parameters/ApcGatewayIdHeader'
- name: body
in: body
required: true
schema:
$ref: '#/definitions/SimSwapVerificationContent'
responses:
'200':
description: The request has succeeded.
schema:
$ref: '#/definitions/SimSwapVerificationResult'
headers:
x-ms-client-request-id:
type: string
format: uuid
description: >-
An opaque, globally-unique, client-generated string identifier
for the request.
x-ms-request-id:
type: string
format: uuid
description: >-
An opaque, globally-unique, server-generated string identifier
for the request.
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/Azure.Core.Foundations.ErrorResponse'
headers:
x-ms-error-code:
type: string
description: String error code indicating what went wrong.
x-ms-examples:
SimSwap_Verify:
$ref: ./examples/SimSwap_Verify_MaximumSet_Gen.json
summary: Microsoft Azure Post Sim Swap Sim Swap:verify
tags:
- Sim Swap
x-ms-paths:
/number-verification/number:verify?_overload=verifyWithCode:
post:
operationId: NumberVerification_VerifyWithCode
description: Verifies the phone number (MSISDN) associated with a device.
parameters:
- $ref: '#/parameters/Azure.Core.Foundations.ApiVersionParameter'
- $ref: '#/parameters/Azure.Core.ClientRequestIdHeader'
- $ref: '#/parameters/ApcGatewayIdHeader'
- name: body
in: body
required: true
schema:
$ref: '#/definitions/NumberVerificationWithCodeContent'
responses:
'200':
description: The request has succeeded.
schema:
$ref: '#/definitions/NumberVerificationResult'
headers:
x-ms-client-request-id:
type: string
format: uuid
description: >-
An opaque, globally-unique, client-generated string identifier
for the request.
x-ms-request-id:
type: string
format: uuid
description: >-
An opaque, globally-unique, server-generated string identifier
for the request.
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/Azure.Core.Foundations.ErrorResponse'
headers:
x-ms-error-code:
type: string
description: String error code indicating what went wrong.
x-ms-examples:
NumberVerification_VerifyWithCode:
$ref: ./examples/NumberVerification_VerifyWithCode_MaximumSet_Gen.json
definitions:
APCVersions:
type: string
description: APC Versions
enum:
- 2024-02-09-preview
x-ms-enum:
name: APCVersions
modelAsString: true
values:
- name: v2024_02_09_preview
value: 2024-02-09-preview
description: Version 2024-02-09-preview
ApcError:
type: object
description: A custom error for APC.
properties:
code:
type: string
description: One of a server-defined set of error codes.
message:
type: string
description: A human-readable representation of the error.
target:
type: string
description: The target of the error.
details:
type: array
description: >-
An array of details about specific errors that led to this reported
error.
items:
$ref: '#/definitions/Azure.Core.Foundations.Error'
x-ms-identifiers: []
innererror:
$ref: '#/definitions/Azure.Core.Foundations.InnerError'
description: >-
An object containing more specific information than the current object
about the error.
consentUrl:
type: string
format: uri
description: The consent URL in case of a consent failure
required:
- code
- message
ApcErrorResponse:
type: object
description: A custom error response for APC.
properties:
error:
$ref: '#/definitions/ApcError'
description: Error returned by APC
required:
- error
Azure.Core.Foundations.Error:
type: object
description: The error object.
properties:
code:
type: string
description: One of a server-defined set of error codes.
message:
type: string
description: A human-readable representation of the error.
target:
type: string
description: The target of the error.
details:
type: array
description: >-
An array of details about specific errors that led to this reported
error.
items:
$ref: '#/definitions/Azure.Core.Foundations.Error'
x-ms-identifiers: []
innererror:
$ref: '#/definitions/Azure.Core.Foundations.InnerError'
description: >-
An object containing more specific information than the current object
about the error.
required:
- code
- message
Azure.Core.Foundations.ErrorResponse:
type: object
description: A response containing error details.
properties:
error:
$ref: '#/definitions/Azure.Core.Foundations.Error'
description: The error object.
required:
- error
Azure.Core.Foundations.InnerError:
type: object
description: >-
An object containing more specific information about the error. As per
Microsoft One API guidelines -
https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
properties:
code:
type: string
description: One of a server-defined set of error codes.
innererror:
$ref: '#/definitions/Azure.Core.Foundations.InnerError'
description: Inner error.
DeviceLocationEndpoint:
type: object
description: Static endpoint to access the Device Location API family.
properties:
location:
type: string
description: Static endpoint
enum:
- location
x-ms-enum:
modelAsString: false
readOnly: true
required:
- location
DeviceLocationVerificationContent:
type: object
description: Request to verify Location
properties:
networkIdentifier:
$ref: '#/definitions/NetworkIdentifier'
description: >-
Network to query for this device, or device information to enable
network routing.
latitude:
type: number
format: double
description: Latitude of location to be verified
minimum: -90
maximum: 90
longitude:
type: number
format: double
description: Longitude of location to be verified
minimum: -180
maximum: 180
accuracy:
type: integer
format: int32
description: Accuracy expected for location verification in kilometers
minimum: 2
maximum: 100
device:
$ref: '#/definitions/LocationDevice'
description: >-
The device to find the location for. Exactly one of Network Access
Code, Phone Number, IPv4 address, or IPv6 address
required:
- networkIdentifier
- latitude
- longitude
- accuracy
- device
DeviceLocationVerificationResult:
type: object
description: Response verifying location
properties:
verificationResult:
type: boolean
description: True if the location is in the specified area, False otherwise
required:
- verificationResult
DeviceNetworkRetrievalEndpoint:
type: object
description: Static endpoint to access the Device Network API family.
properties:
network:
type: string
description: Static endpoint
enum:
- network
x-ms-enum:
modelAsString: false
readOnly: true
required:
- network
Ipv4Address:
type: object
description: IPv4 device indicator
properties:
ipv4:
type: string
description: >-
An IPv4 address. This may be specified as an exact address, or as a
subnet in CIDR notation.
port:
type: integer
format: int32
description: User equipment port.
required:
- ipv4
- port
Ipv4AddressModel:
type: object
description: IPv4 address and port of the device
properties:
ipv4Address:
$ref: '#/definitions/Ipv4Address'
description: The Ipv4 address
Ipv6Address:
type: object
description: IPv6 device indicator
properties:
ipv6:
type: string
description: >-
An IPv6 address. This may be specified as an exact address, or as a
subnet in CIDR notation.
port:
type: integer
format: int32
description: User equipment port.
required:
- ipv6
- port
Ipv6AddressModel:
type: object
description: IPv4 address and port of the device
properties:
ipv6Address:
$ref: '#/definitions/Ipv6Address'
description: The Ipv6 address
LocationDevice:
type: object
description: >-
Device information needed by operator to provide location information.
Include exactly one of these properties to identify your device.
properties:
networkAccessIdentifier:
type: string
description: External identifier or network access identifier of the device
phoneNumber:
type: string
description: >-
Phone number in E.164 format (starting with country code), and
optionally prefixed with '+'
pattern: ^\+?[0-9]{5,15}$
ipv4Address:
$ref: '#/definitions/Ipv4Address'
description: The Ipv4 address
ipv6Address:
$ref: '#/definitions/Ipv6Address'
description: The Ipv6 address
NetworkAccessIdentifierModel:
type: object
description: The network access ID/external ID of the device
properties:
networkAccessIdentifier:
type: string
description: External identifier or network access identifier of the device
NetworkIdentifier:
type: object
description: Identifier for the network to be queried
properties:
identifierType:
type: string
description: >-
The type of identifier for the network. one of: 'IPv4', 'IPv6',
'NetworkCode'
identifier:
type: string
description: >-
The network identifier, based on the identifierType: an IPv4 address,
and IPv6 address, or a Network Code.
A Network Code may be obtained from APC documentation or from the APC
/Network:retrieve endpoint.
required:
- identifierType
- identifier
NetworkRetrievalResult:
type: object
description: The network that the device is on.
properties:
networkCode:
type: string
description: >-
The identifier for the network. This can be used as the
networkIdentifier for the service APIs.
pattern: '[a-z0-9-]+$'
required:
- networkCode
NumberDevice:
type: object
description: >-
Device information to verify phone number. Include exactly one form of
phone number.
properties:
phoneNumber:
type: string
description: >-
Phone number in E.164 format (starting with country code), and
optionally prefixed with '+'
pattern: ^\+?[0-9]{5,15}$
hashedPhoneNumber:
type: string
description: >-
Hashed phone number. SHA-256 (in hexadecimal representation) of the
mobile phone number in **E.164 format (starting with country code)**.
Optionally prefixed with '+'.
NumberVerificationEndpoint:
type: object
description: Static endpoint to access Number Verification API family
properties:
number:
type: string
description: Static endpoint
enum:
- number
x-ms-enum:
modelAsString: false
readOnly: true
required:
- number
NumberVerificationResult:
type: object
description: Response verifying number of device
properties:
verificationResult:
type: boolean
description: True if number if the phone number matches the device, False otherwise
required:
- verificationResult
NumberVerificationWithCodeContent:
type: object
description: Request to verify number of device - second call
properties:
apcCode:
type: string
description: The code provided by APC in exchange for the operator code.
required:
- apcCode
NumberVerificationWithoutCodeContent:
type: object
description: Request to verify number of device - first call
properties:
networkIdentifier:
$ref: '#/definitions/NetworkIdentifier'
description: Identifier for the network to query for this device.
phoneNumber:
type: string
description: >-
Phone number in E.164 format (starting with country code), and
optionally prefixed with '+'
pattern: ^\+?[0-9]{5,15}$
hashedPhoneNumber:
type: string
description: >-
Hashed phone number. SHA-256 (in hexadecimal representation) of the
mobile phone number in **E.164 format (starting with country code)**.
Optionally prefixed with '+'.
redirectUri:
type: string
format: uri
description: Redirect URI to backend application.
required:
- networkIdentifier
- redirectUri
PhoneNumberModel:
type: object
description: The phone number of the device.
properties:
phoneNumber:
type: string
description: >-
Phone number in E.164 format (starting with country code), and
optionally prefixed with '+'
pattern: ^\+?[0-9]{5,15}$
SimSwapDevice:
type: object
description: Device information needed by operator to find sim swap information.
properties:
phoneNumber:
type: string
description: >-
Phone number in E.164 format (starting with country code), and
optionally prefixed with '+'
pattern: ^\+?[0-9]{5,15}$
SimSwapEndpoint:
type: object
description: Static endpoint to access the Sim Swap API family
properties:
simSwap:
type: string
description: Static endpoint
enum:
- sim-swap
x-ms-enum:
modelAsString: false
readOnly: true
required:
- simSwap
SimSwapRetrievalContent:
type: object
description: Request to retrieve SimSwap date
properties:
phoneNumber:
type: string
description: >-
Phone number in E.164 format (starting with country code), and
optionally prefixed with '+'
pattern: ^\+?[0-9]{5,15}$
networkIdentifier:
$ref: '#/definitions/NetworkIdentifier'
description: Network to query for this device
required:
- networkIdentifier
SimSwapRetrievalResult:
type: object
description: Response with SimSwap date
properties:
date:
type: string
format: date-time
description: Datetime of most recent swap for SIM
SimSwapVerificationContent:
type: object
description: Request to verify SimSwap in period
properties:
phoneNumber:
type: string
description: >-
Phone number in E.164 format (starting with country code), and
optionally prefixed with '+'
pattern: ^\+?[0-9]{5,15}$
maxAgeHours:
type: integer
format: int32
description: Maximum lookback for SimSwap verification
default: 240
minimum: 1
maximum: 2400
networkIdentifier:
$ref: '#/definitions/NetworkIdentifier'
description: Identifier for the network to query for this device.
required:
- networkIdentifier
SimSwapVerificationResult:
type: object
description: Response verifying SimSwap in period
properties:
verificationResult:
type: boolean
description: True if the SIM has swapped in the specified period, False otherwise
required:
- verificationResult
parameters:
ApcGatewayIdHeader:
name: apc-gateway-id
in: header
description: >-
The identifier of the APC Gateway resource which should handle this
request.
required: true
type: string
x-ms-parameter-location: method
x-ms-client-name: apcGatewayId
Azure.Core.ClientRequestIdHeader:
name: x-ms-client-request-id
in: header
description: >-
An opaque, globally-unique, client-generated string identifier for the
request.
required: false
type: string
format: uuid
x-ms-parameter-location: method
x-ms-client-name: clientRequestId
Azure.Core.Foundations.ApiVersionParameter:
name: api-version
in: query
description: The API version to use for this operation.
required: true
type: string
minLength: 1
x-ms-parameter-location: method
x-ms-client-name: apiVersion