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: >-
    With quick and easy access to Number Lookup, you can enhance your
    communications and keep your database as clean as a whistle. Number Lookup
    checks against first-party numbering sources and provides real-time
    feedback. Improve communication by validating and verifying numbers,
    boosting delivery conversion rates, and saving money on marketing campaigns.
    Test numbers to ensure your recipients are ready and waiting to receive your
    messages!
  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:
      summary: Lookup number
      description: >-
        Performs a number lookup. You can make a minimal request or add
        additional options to the `features` array.
      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'
            examples:
              minRequest:
                summary: Minimum request
                value:
                  number: '+12312312312'
              additionalOptions:
                summary: Request with additional features
                value:
                  number: '+12312312312'
                  features:
                    - LineType
                    - RND
                    - SimSwap
                    - VoIPDetection
                  rndFeatureOptions: '2025-01-01'
        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: Use to return line type information for the phone number.
        SimSwap: Use to determine whether the phone number is SIM swapped.
        VoIPDetection: >-
          Use to determine if the carrier is associated with a VoIP provider
          (alpha).
        RND: >-
          Use to determine whether the phone number has been disconnected
          (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: {}
