x-generator: NSwag v14.4.0.0 (NJsonSchema v11.3.2.0 (Newtonsoft.Json v13.0.0.0))
openapi: 3.0.0
info:
  title: Number Lookup Api
  description: This is public api specification, for number lookup product.
  contact:
    name: Sinch
    url: https://www.sinch.com/contact-us/
    email: support@sinch.com
  version: 0.1.0
servers:
- url: https://number-lookup.api.sinch.com
paths:
  /v1/lookups:
    post:
      tags:
      - NumberLookup
      summary: Performs a number lookup.
      operationId: NumberLookup_Lookup
      requestBody:
        x-name: numberLookupRequest
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberLookupRequest'
            example:
              number: "+1235559988"
              features:
                - LineType
                - SimSwap
        x-position: 1
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberLookupResponse'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        401:
          description: Invalid Authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        402:
          description: Account Locked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        403:
          description: API disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        429:
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        500:
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    NumberLookupResponse:
      type: object
      additionalProperties: false
      properties:
        line:
          type: object
          description: An object containing information about the line type of the number.
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/LineResponse'
        simSwap:
          type: object
          description: An object containing information about the SimSwap verification performed on the number.
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/SimSwapResponse'
        voIPDetection:
          type: object
          description: An object containing information about the VoIP detection performed on the number.
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/VoIPDetectionResponse'
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 two-letter country identifier
        traceId:
          type: string
          description: The identifier for a trace.
          example: 00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00
        number:
          type: string
          description: Requested MSISDN in E.164 format.
          example: +12312312312
    LineResponse:
      type: object
      additionalProperties: false
      properties:
        carrier:
          type: string
          description: Name of the carrier.
          nullable: true
          example: T-Mobile USA
        type:
          type: object
          description: Number type e.g. wireless, mobile, fixed.
          nullable: true
          example: Mobile
          oneOf:
          - $ref: '#/components/schemas/ApiLineType'
        mobileCountryCode:
          type: string
          description: A numeric code (MCC) that uniquely identifies a country within the international telecommunications network.
          nullable: true
          example: 310
        mobileNetworkCode:
          type: string
          description: A distinct identifier assigned to a mobile network operator within a specific country, used in combination with MCC.
          nullable: true
          example: 260
        ported:
          type: boolean
          description: Indicates if a phone number has been transferred from its original network to a different provider.
          nullable: true
          example: true
        portingDate:
          type: string
          description: Specifies the date, in ISO 8601 format, when a phone number was transferred from its original network to a new provider.
          nullable: true
          example: 2000-01-01T00:00:00.0000000+00:00
        error:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/ErrorResponse'
    ApiLineType:
      type: string
      description: ''
      x-enumDescriptions:
        Landline: A landline phone number.
        Mobile: A mobile network phone number.
        VoIP: A Voice over IP phone number.
        Special: A specialty type of number, such as a satellite phone or fax line.
        Freephone: A freephone type phone number.
        Other: Another type.
      enum:
      - Landline
      - Mobile
      - VoIP
      - Special
      - Freephone
      - Other
    ErrorResponse:
      type: object
      additionalProperties: false
      properties:
        status:
          type: integer
          description: The error status code.
          format: int32
        title:
          type: string
          description: A short, human-readable summary of the error type.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the error.
        type:
          type: string
          description: A URI reference that identifies the error type.
          nullable: true
    SimSwapResponse:
      type: object
      additionalProperties: false
      properties:
        swapped:
          type: boolean
          description: Indicates whether SIM was changed.
          nullable: true
          example: true
        swapPeriod:
          type: object
          description: Threshold for sim swap check.
          nullable: true
          example: SP24H
          oneOf:
          - $ref: '#/components/schemas/ApiSwapPeriod'
        error:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/ErrorResponse'
    ApiSwapPeriod:
      type: string
      description: ''
      x-enumNames:
      - Undefined
      - SP4H
      - SP12H
      - SP24H
      - SP48H
      - SP5D
      - SP7D
      - SP14D
      - SP30D
      - SPMAX
      enum:
      - Undefined
      - SP4H
      - SP12H
      - SP24H
      - SP48H
      - SP5D
      - SP7D
      - SP14D
      - SP30D
      - SPMAX
    VoIPDetectionResponse:
      type: object
      additionalProperties: false
      properties:
        probability:
          type: object
          description: Probability of number being VoIP based on the AI analysis.
          nullable: true
          example: High
          oneOf:
          - $ref: '#/components/schemas/ApiVoIPProbability'
        error:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/ErrorResponse'
    ApiVoIPProbability:
      type: string
      description: ''
      x-enumNames:
      - Unknown
      - Low
      - Likely
      - High
      enum:
      - Unknown
      - Low
      - Likely
      - High
    ProblemDetails:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type.
          nullable: true
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code.
          format: int32
        traceId:
          type: string
          description: The identifier for a trace.
          example: 00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00
    NumberLookupRequest:
      type: object
      additionalProperties: false
      properties:
        number:
          type: string
          description: MSISDN in E.164 format to query.
          example: +12312312312
        features:
          type: array
          items:
            $ref: '#/components/schemas/ApiFeature'
    ApiFeature:
      type: string
      description: ''
      x-enumNames:
      - LineType
      - SimSwap
      - VoIPDetection
      - RND
      enum:
      - LineType
      - SimSwap
      - VoIPDetection
      - RND
  securitySchemes:
    Basic:
      type: http
      description: For more information about basic authentication, see [Basic Authentication](/docs/number-lookup-api/api-reference/authentication/).
      scheme: basic
    Application:
      type: apiKey
      description: For more information about application request signing authentication, see [Request Signing](/docs/number-lookup-api/api-reference/authentication/signed-request).
      name: Authentication
      in: header