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 v2
  description: This is public api specification, for number lookup product.
  contact:
    name: Sinch
    url: https://www.sinch.com/contact-us/
    email: support@sinch.com
  license:
    url: "https://www.sinch.com/toc"
    name: "MIT"
  version: 0.1.0
servers:
- url: https://lookup.api.sinch.com
security:
  - Basic: []
  - OAuth2: []
paths:
  /v2/projects/{projectId}/lookups:
    post:
      tags:
      - NumberLookupV2
      summary: Performs a number lookup.
      operationId: NumberLookupV2_Lookup
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
        x-position: 1
      requestBody:
        x-name: numberLookupRequest
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberLookupRequest'
        x-position: 2
      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:
          description: An object containing information about the line type of the number.
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/LineResponse'
        simSwap:
          description: An object containing information about the SimSwap verification performed on the number.
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/SimSwapResponse'
        voIPDetection:
          description: An object containing information about the VoIP detection performed on the number.
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/VoIPDetectionResponse'
        rnd:
          description: An object containing information whether number is disconnected.
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RndResponse'
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 two-letter country identifier
        traceId:
          type: string
          description: The identifier for a trace.
          example: 84c1fd4063c38d9f3900d06e56542d48
        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:
          description: Number type e.g. wireless, mobile, fixed.
          type: string
          nullable: true
          example: Mobile
          allOf:
            - $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
          allOf:
            - $ref: '#/components/schemas/ErrorResponse'
    ApiLineType:
      type: string
      description: Represents the type of a phone line.
      x-enumNames:
      - Landline
      - Mobile
      - VoIP
      - Special
      - Freephone
      - Other
      enum:
      - Landline
      - Mobile
      - VoIP
      - Special
      - Freephone
      - Other
      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.
    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:
          description: Threshold for sim swap check.
          type: string
          nullable: true
          example: SP24H
          allOf:
            - $ref: '#/components/schemas/ApiSwapPeriod'
        error:
          type: object
          nullable: true
          allOf:
            - $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
      x-enumDescriptions:
        Undefined: Undefined
        SP4H: 4 Hours
        SP12H: 12 Hours
        SP24H: 24 Hours
        SP48H: 48 Hours
        SP5D: 5 Days
        SP7D: 7 Days
        SP14D: 14 Days
        SP30D: 30 Days
        SPMAX: Maximum
    VoIPDetectionResponse:
      type: object
      additionalProperties: false
      properties:
        probability:
          description: Probability of number being VoIP based on the AI analysis.
          type: string
          nullable: true
          example: High
          allOf:
            - $ref: '#/components/schemas/ApiVoIPProbability'
        error:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ErrorResponse'
    ApiVoIPProbability:
      type: string
      description: ''
      x-enumNames:
      - Unknown
      - Low
      - Likely
      - High
      enum:
      - Unknown
      - Low
      - Likely
      - High
      x-enumDescriptions:
        Unknown: Undefined
        Low: Low
        Likely: Likely
        High: High
    RndResponse:
      type: object
      additionalProperties: false
      properties:
        disconnected:
          type: boolean
          description: Provides information whether the number was disconnected after provided last contact date.
          nullable: true
        error:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ErrorResponse'
    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
      required:
      - number
      properties:
        number:
          type: string
          description: MSISDN in E.164 format to query.
          minLength: 1
          example: '+12312312312'
        features:
          type: array
          description: Contains requested features. Fallback to LineType if not provided.
          items:
            $ref: '#/components/schemas/ApiFeature'
        rndFeatureOptions:
          description: Required when RND feature is requested.
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RndFeatureOptions'
    ApiFeature:
      type: string
      description: ''
      x-enumNames:
      - LineType
      - SimSwap
      - VoIPDetection
      - RND
      enum:
      - LineType
      - SimSwap
      - VoIPDetection
      - RND
      x-enumDescriptions:
        LineType: LineType
        SimSwap: SimSwap
        VoIPDetection: VoIPDetection (alpha).
        RND: RND (alpha).
    RndFeatureOptions:
      type: object
      additionalProperties: false
      properties:
        contactDate:
          type: string
          description: Last contact date in YYYY-MM-DD format.
          format: date
  securitySchemes:
    Basic:
      type: http
      description: For more information about basic authentication, see [Basic Authentication](/docs/number-lookup-api/api-reference/authentication/).
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.sinch.com/oauth2/token
          scopes: {}