> ## Documentation Index > Fetch the complete documentation index at: https://umbrella-docs.info/llms.txt > Use this file to discover all available pages before exploring further. # Phone ID Service > Phone ID Service API Documentation For a usage description of the Phone ID Service, please refer to the [Phone ID](/essentials/phoneServices) page. ## Endpoint **POST** `/phone-service/phoneid` ## Swagger ## OpenAPI ````yaml POST /phone-service/phoneid openapi: 3.1.0 info: title: Umbrella API version: 1.0.0 description: >- API documentation for Umbrella services including KYB, KYC, AML, payments, phone intelligence, onboarding, and address verification. servers: - url: https://api-umbrella.io/api/services description: Production - url: https://sandbox-umbrella-api.azurewebsites.net/api/services description: Sandbox security: - bearerAuth: [] paths: /phone-service/phoneid: post: summary: Phone ID description: >- The Phone ID service provides identity checks and enriched data linked to a phone number. It includes optional modules like age verification, breached data, call forwarding detection, contact info, contact match, number deactivation, subscriber status, porting history, porting status, and SIM swap. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PhoneIDRequest' examples: default: value: phoneNumber: '11234567890' accountLifecycleEvent: create externalId: CustomExternalID7349 originatingIp: 203.0.113.45 addons: ageVerify: ageThreshold: 21 contact: email: test@example.com contactMatch: firstName: string lastName: string address: string city: string postalCode: string state: string country: string inputUsed: email contactPlus: billingPostalCode: '95110' numberDeactivation: carrierName: Verizon lastDeactivated: '2016-04-05T00:00:00Z' trackingSince: '2014-10-06T00:00:00Z' status: code: 2800 description: Request successfully completed recycledSinceLastVerification: notRecycled portingHistory: pastXDays: 10 breachedData: {} callForwardDetection: {} subscriberStatus: {} portingStatus: {} simSwap: {} consent: method: 1 timestamp: '2018-05-05T00:00:00Z' responses: '200': description: Successfully retrieved phone ID information. content: application/json: schema: $ref: '#/components/schemas/PhoneIDResponse' examples: default: value: status: true data: referenceId: 0123456789ABCDEF0123456789ABCDEF externalId: null status: code: 300 description: Transaction successfully completed updatedOn: '2025-01-01T00:00:00Z' location: city: Countrywide state: null zip: null metroCode: null county: null country: name: Exampleland iso2: EX iso3: EXL coordinates: latitude: null longitude: null timeZone: name: null utcOffsetMax: '+0' utcOffsetMin: '+0' blocklisting: blocked: false blockCode: 0 blockDescription: Not blocked numbering: cleansing: call: countryCode: '99' phoneNumber: '5550123456' cleansedCode: 100 minLength: 7 maxLength: 13 sms: countryCode: '99' phoneNumber: '5550123456' cleansedCode: 100 minLength: 7 maxLength: 13 original: completePhoneNumber: '+995550123456' countryCode: '99' phoneNumber: '5550123456' phoneType: code: '2' description: MOBILE carrier: name: Example Mobile Ltd '400': description: Bad Request - Malformed syntax in the request. content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Authentication failed. content: application/json: schema: $ref: '#/components/schemas/Error401' '404': description: Not Found - The server could not find the requested resource. content: application/json: schema: $ref: '#/components/schemas/Error404' '429': description: Too Many Requests - Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error429' '500': description: >- Invalid Transaction - Transaction not attempted due to a system issue. content: application/json: schema: $ref: '#/components/schemas/Error500' '503': description: Service Unavailable - System is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/Error503' components: schemas: PhoneIDRequest: type: object required: - phoneNumber properties: phoneNumber: type: string description: >- Phone number to query, including country code (no spaces or symbols). example: '11234567890' accountLifecycleEvent: type: string description: Stage of the user journey. enum: - create - sign-in - transact - update - delete example: create externalId: type: string description: Customer-defined ID echoed in the response. example: CustomExternalID7349 originatingIp: type: string description: End user's IP address (IPv4 or IPv6). example: 203.0.113.45 addons: type: object description: Add-on services to enrich the phone lookup. properties: ageVerify: type: object properties: ageThreshold: type: integer description: Age threshold to verify against. example: 21 breachedData: type: object description: >- Checks whether the phone number has appeared in known data breaches. callForwardDetection: type: object description: >- Detects whether call forwarding is active and under what conditions. contact: type: object description: Returns known contact details such as name, address, and email. properties: email: type: string example: test@example.com contactMatch: type: object description: >- Compares submitted contact data against the carrier’s data and returns a match score. properties: firstName: type: string lastName: type: string address: type: string city: type: string postalCode: type: string state: type: string country: type: string inputUsed: type: string description: e.g., 'phoneNumber and email' or 'email'. contactPlus: type: object description: Enhanced contact information module. properties: billingPostalCode: type: string example: '95110' numberDeactivation: type: object description: Indicates if/when the number was deactivated. properties: carrierName: type: string example: Verizon lastDeactivated: type: string format: date-time example: '2016-04-05T00:00:00Z' trackingSince: type: string format: date-time example: '2014-10-06T00:00:00Z' status: type: object properties: code: type: integer example: 2800 description: type: string example: Request successfully completed recycledSinceLastVerification: type: string example: notRecycled subscriberStatus: type: object description: >- Provides subscriber account details like type, tenure, and activation. portingHistory: type: object description: Shows porting history of the number across carriers. properties: pastXDays: type: integer example: 10 portingStatus: type: object description: >- Displays current carrier and whether the number was recently ported. simSwap: type: object description: Detects recent SIM changes and evaluates risk. consent: type: object description: >- Consent record for querying the number — required for certain add-ons. properties: method: type: integer description: Numeric code for how consent was collected. enum: - 1 - 2 - 3 - 4 example: 1 timestamp: type: string format: date-time description: ISO 8601 timestamp of when consent was collected. example: '2018-05-05T00:00:00Z' PhoneIDResponse: type: object required: - status - data properties: status: type: boolean description: Indicates if the API request itself was successful. data: type: object properties: referenceId: type: string description: Unique 32-character hex ID for the transaction. externalId: type: string nullable: true description: Echoed custom ID if provided. status: type: object properties: code: type: integer description: Processing status code (e.g., 300 for success). description: type: string description: Human-readable description of the transaction status. updatedOn: type: string description: ISO 8601/RFC 3339 timestamp of last update. phoneType: type: object properties: code: type: string description: type: string blocklisting: type: object properties: blocked: type: boolean blockCode: type: integer blockDescription: type: string carrier: type: object properties: name: type: string numbering: type: object properties: original: type: object properties: completePhoneNumber: type: string countryCode: type: string phoneNumber: type: string cleansing: type: object properties: call: type: object properties: countryCode: type: string phoneNumber: type: string cleansedCode: type: integer minLength: type: integer maxLength: type: integer sms: type: object properties: countryCode: type: string phoneNumber: type: string cleansedCode: type: integer minLength: type: integer maxLength: type: integer location: type: object properties: city: type: string nullable: true state: type: string nullable: true zip: type: string nullable: true metroCode: type: string nullable: true county: type: string nullable: true country: type: object properties: name: type: string nullable: true iso2: type: string nullable: true iso3: type: string nullable: true coordinates: type: object properties: latitude: type: number nullable: true longitude: type: number nullable: true timeZone: type: object properties: name: type: string nullable: true utcOffsetMax: type: string nullable: true utcOffsetMin: type: string nullable: true Error400: required: - message type: object properties: message: type: string example: Invalid request payload Error401: required: - message type: object properties: message: type: string example: Unauthorized request Error404: type: object properties: message: type: string example: Journey not found Error429: type: object properties: error: type: string example: Too Many Requests message: type: string example: Rate limit exceeded. code: type: string example: '429' Error500: required: - message type: object properties: message: type: string example: Internal Server Error Error503: type: object properties: error: type: string example: Service Unavailable message: type: string example: Service is unavailable. code: type: string example: '503' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Bearer token obtained from POST /auth. Valid for 60 minutes. ````