openapi: 3.0.0 info: title: PNV version: 1.0.0 description: > The purpose of this specification is to describe the Syniverse Phone Number Verification(PNV) service capabilities, core concepts, and API set. The PNV offers a rich suite of RESTful APIs that allow lookup of salient phone number data, batch lookup of number data, scheduling of number lookup and proactive monitoring of numbers of interest for changes to critical attributes. Number lookup returns salient attributes of a phone number e.g., validity, country, carrier, deactivation and disconnection details). The lookup and response can be tailored by specifying a feature set. Different feature sets provide different sets of information, i.e. feature set 2 provides standard routing information, and feature set 5 provides additional information on when a phone number was last disconnected. See the User Guide for more information on the different feature sets. servers: - url: https://api.syniverse.com/numberidentity/v3 paths: /lookup: post: security: - bearerAuth: [] parameters: - name: ext_trx_id in: header description: This is the unique identifier sent by the customer in the request header to track the request/response chain. The value of this attribute is extracted from the header of the POST request. required: false schema: type: string - name: ext_reseller_cust_id in: header description: This attribute represents the customer of our customer using the service. The value is extracted from the POST request header. required: false schema : type: string responses: '200': description: Successful operation content: application/json: schema: title: PNV type: object properties: numberidentity: type: string SucessResponse: type: object properties: number: type: string example: +1XXXXXXXX70 validity: type: string example: true carrier_id: type: string example: 1234 carrier_name: type: string example: SPRINT PCS number_type: type: string example: M country_iso_code: type: string example: USA country: type: string example: United States carrier_mcc: type: string example: 123 carrier_mnc: type: string example: 214 last_known_event: type: string example: Disconnect previous_carrier_id: type: string previous_carrier_name: type: string disconnect_date: type: string format: date-time example: 2018-08-10T00:00Z tracking_id: type: string tracking_id: type: string example: "101580180391472739483159" ext_trx_id: type: string example: "string" ext_reseller_cust_id: type: string example: "string" '400': description: > Bad Request. Possible Error Codes: * **NIS04000001** - Invalid Phone format - Non-retryable error code - **Suggested action:** Number format should be corrected to be in E.164 format, i.e. +1XXXXXXXX70 * **NIS04000001** - Phone number attribute missing in the request - Non-retryable error code. - **Suggested action:** update request to include phone number * **NIS04000002** - Invalid Feature - Non-retryable error code - **Suggested action:** change the feature value to be a supported value such as fs5 (or) fs2 (or) fs23 (or) fs1. * **NIS04000003** - Canadian Number, Further authorization is required - Non-retryable error code - **Suggested action:** Please work with your Customer Support Executive to get Canadian numbers enabled. . content: application/json: schema: title: Error Response type: object properties: error_code: type: string example: NIS04000001 error_description: type: string example: Invalid Phone format - Non-retryable error code '401': description: | Unauthorized. The request requires user authentication. Possible Error Codes: * **NIS04010001** - Unauthorized - Non-retryable error code - **Suggested actions:** please check the CompanyID is correct and the Bearer Token is valid. content: application/json: schema: title: Error Response type: object properties: error_code: type: string example: NIS04010001 error_description: type: string example: Unauthorized - Non-retryable error code '403': description: > Forbidden. The user does not have permission to access the specified resource. Possible Error Codes: * **NIS04030001** - Forbidden operation - Non-retryable error code - **Suggested Action:** Please check you are not using a PUT, or DELETE operation * **NIS04000003** - Invalid parameters provided. Please check the documentation for valid values - Non-retryable error code - **Suggested action:** Please check the parameter values against the documentation and correct as needed. content: application/json: schema: title: Error Response type: object properties: error_code: type: string example: NIS04030001 error_description: type: string example: Forbidden operation - Non-retryable error code '404': description: > Wrong URL is specified. **Suggested action:** Please check and correct the URL to match the PNV Lookup API specification Example : 404 Status report Runtime Error No matching resource found for given API Request '405': description: > Below error throws when the HTTP method set is not POST. **Suggested action:** Set HTTP method to POST. Example : 405 Status report Runtime Error Method not allowed for given API resource '500': description: > Server Error. An error has been encountered while processing this request. Possible Error Codes: * **NIS05000001** - Internal Server Error - Retryable error code. **Suggested action:** if problems keeps re-occurring contact customer support. content: application/json: schema: title: Error Response type: object properties: error_code: type: string example: NIS05000001 error_description: type: string example: Internal Server Error - Retryable error code '503': description: | Service Unavailable. N.B. No Error code or description are provided for this error. **Suggested action:** Please check for any communcation related to service maintenace (or) contact customer support. description: ' Returns all information on the phone number including validity, number type, carrier identifier, carrier name, country, porting detail, deactivation details, mcc, and mnc. Values returned depend on the feature set selected in request and any optional parameters included in the request.' operationId: POST_lookup requestBody: content: application/json: schema: type: string example: {'phone_number':'+1XXXXXXXX70','feature':'fs5'} required: false parameters: [] components: schemas: {} responses: {} parameters: {} examples: {} requestBodies: {} headers: {} securitySchemes: bearerAuth: # arbitrary name for the security scheme type: http scheme: bearer bearerFormat: JWT # optional, arbitrary value for documentation purposes links: {} callbacks: {}