openapi: 3.0.0
info:
  title: Number Lookup Api
  description: Use the Number Lookup API to look up the carrier and line type of a phone number.
  license:
    name: MIT
    url: "https://www.sinch.com/toc"
  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
security:
  - Basic: []
  - Application: []
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: "+1555449999"
              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:
  securitySchemes:
    Basic:
      type: http
      scheme: basic
      description: For more information about basic authentication, see [Basic Authentication](/docs/number-lookup-api/api-reference/authentication/).
    Application:
      type: apiKey
      in: header
      name: Authentication
      description: For more information about application request signing authentication, see [Request Signing](/docs/number-lookup-api/api-reference/authentication/signed-request).
  schemas:
    NumberLookupResponse:
      type: object
      additionalProperties: false
      properties:
        line:
          type: object
          description: LineType feature response
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/LineResponse'
        simSwap:
          type: object
          description: SimSwap feature response
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/SimSwapResponse'
        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/LineType'
        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'
    LineType:
      type: string
      description: ''
      x-enumNames:
      - Landline
      - Mobile
      - VoIP
      - Special
      - Freephone
      - Other
      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/SwapPeriod'
        error:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/ErrorResponse'
    SwapPeriod:
      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
    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/Feature'
    Feature:
      type: string
      description: This enum is used in the CDR field containing the features that were executed, please take care when changing the values, since those are displayed in the Dashboard.
      x-enumNames:
      - LineType
      - SimSwap
      - RND
      enum:
      - LineType
      - SimSwap
      - RND