> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.omni-ward.com/llms.txt > Use this file to discover all available pages before exploring further. # Localizar pessoa por telefone, e-mail ou nome > SERVICE_LOCATE_BY_PHONE · Encontra os cadastros ligados a um telefone, a um e-mail ou a um nome (com data de nascimento opcional). Homônimos voltam como vários candidatos, para quem consulta escolher o certo. > [!NOTE] > > Alias: `SERVICE_LOCATE_BY_PHONE` · Preço: **R\$ 0,25** por consulta · Exige `purpose` Encontra os cadastros ligados a um telefone, a um e-mail ou a um nome (com data de nascimento opcional). Homônimos voltam como vários candidatos, para quem consulta escolher o certo. Execute pelo endpoint único [`POST /v1/services`](https://api-docs.omni-ward.com/api-reference/executar-servicos). Você pode combinar este serviço com outros na mesma chamada, enviando cada identificador uma vez. ## Campos do request | Campo | Obrigatório | Descrição | | - | - | - | | `services` | sim | Inclua `"SERVICE_LOCATE_BY_PHONE"` na lista. | | `phone` | sim | Telefone com DDD, só dígitos. | | `purpose` | sim | Finalidade do tratamento. Este serviço trata dados pessoais. | ## Campos em `result` | Campo | Descrição | Tipo | | - | - | - | | `BasicData` | Objeto principal de retorno do dataset, contendo as informações consolidadas relacionadas à pessoa consultada. | object | | `BasicData.TaxIdNumber` | O número do documento da pessoa. | string | | `BasicData.TaxIdCountry` | País de registro do documento. | string | | `BasicData.AlternativeIdNumbers` | Números de documentos alternativos referentes a pessoa. Por exemplo passaporte, CNH, Titulo de Eleitor, etc. | object | | `BasicData.ExtendedDocumentInformation` | Informações adicionais sobre outros documentos referentes a pessoa. | object | | `BasicData.Name` | Nome completo da pessoa. | string | | `BasicData.Aliases` | Possiveis nomes que a pessoa pode também se referir. Por exemplo: Nome social, Nome artistico, Apelido criminal etc. | object | | `BasicData.Aliases.CommonName` | Nome comum da pessoa. | string | | `BasicData.Aliases.SocialName` | Nome social da pessoa. | string | | `BasicData.Aliases.StandardizedName` | Nome padronizado da pessoa. | string | | `BasicData.Gender` | Gênero da pessoa. Pode ser: M ou F. | string | | `BasicData.NameWordCount` | Número de nomes no nome completo da pessoa. | integer | | `BasicData.InputNameMatchPercentage` | Porcentagem de semelhança entre o nome da pessoa e o nome utilizado como entrada. Só mostrado quando um nome é fornecido. | number | | `BasicData.InputMotherNameMatchPercentage` | Porcentagem de semelhança entre o nome da mãe que possuimos em nossas bases e o utilizado como entrada. Só é exibido quando o 'mothername' é fornecido. | number | | `BasicData.InputFatherNameMatchPercentage` | Porcentagem de semelhança entre o nome do pai que possuímos em nossas bases e o utilizado como entrada. Só é exibido quando o 'fathername' é fornecido. | number | | `BasicData.NumberOfFullNameNamesakes` | Indica a quantidade de pessoas de mesmo nome completo. | integer | | `BasicData.NameUniquenessScore` | Indica quão único é o nome completo da pessoa. 1 sendo único 0 sendo extremamente comum. | number | | `BasicData.FirstNameUniquenessScore` | Indica quão único é o primeiro nome da pessoa. 1 sendo único 0 sendo extremamente comum. | number | | `BasicData.FirstAndLastNameUniquenessScore` | Indica quão único é o primeiro e último nome da pessoa. 1 sendo único 0 sendo extremamente comum. | number | | `BasicData.BirthDate` | Data de nascimento da pessoa. | string | | `BasicData.CapturedBirthDateFromRFSource` | Data de nascimento capturada diretamente da Receita Federal, retornada no formato yyyy-MM-dd. Especialmente útil em casos onde a data capturada é lógicamente inválida (como 31 de fevereiro, por exemplo). | string | | `BasicData.IsValidBirthDateInRFSource` | Indica se a data de nascimento informada na Receita Federal é válida do ponto de vista de calendário (o dia/mês/ano existe). | boolean | | `BasicData.InputBirthDateMatch` | Indica se a data de nascimento passada de entrada é igual a retornada. | boolean | | `BasicData.Age` | A idade da pessoa no momento da consulta. | integer | | `BasicData.ZodiacSign` | Signo do zodíaco da pessoa de acordo com a data de nascimento. | string | | `BasicData.ChineseSign` | Signo do zodíaco chinês da pessoa de acordo com a data de nascimento. | string | | `BasicData.BirthCountry` | País de nascimento da pessoa. | string | | `BasicData.MotherName` | Nome da mãe da pessoa. | string | | `BasicData.FatherName` | Nome do pai da pessoa. | string | | `BasicData.MaritalStatusData` | Dados de estado civil da pessoa. | object | | `BasicData.MaritalStatusData.MaritalStatus` | Estado civil da pessoa. | string | | `BasicData.MaritalStatusData.MaritalStatusSource` | Fonte em que o dado de estado civil da pessoa foi capturado. | string | | `BasicData.MaritalStatusData.MaritalStatusLastUpdateDate` | Data de última atualização do estado civil da pessoa. | string | | `BasicData.TaxIdStatus` | Status da pessoa na Receita Federal. Valores possíveis: REGULAR, PENDENTE DE REGULARIZACAO, SUSPENSA, CANCELADA, NULA, TITULAR FALECIDO, CPF COM DADOS INCOMPLETOS, BIRTH DATE AND DOCUMENT DOESN'T MATCH, CPF DOES NOT EXIST IN RECEITA FEDERAL DATABASE, INVALID DOCUMENT | string | | `BasicData.TaxIdOrigin` | Fonte de onde foi capturada a informação de status do documento. | string | | `BasicData.TaxIdFiscalRegion` | Região fiscal na qual o documento pertence. | string | | `BasicData.HasObitIndication` | Indica se houve óbito para aquela pessoa. | boolean | | `BasicData.ObitIndicationOrigin` | Fonte de onde foi capturada a informação de óbito. | string | | `BasicData.ObitIndicationYear` | Indica o ano de óbito da pessoa consultada. | string | | `BasicData.TaxIdStatusDate` | Data da última alteração do status do indíviduo nas bases de dados da o provedor. | string | | `BasicData.TaxIdStatusRegistrationDate` | Data de registro do documento na Receita Federal. | string | | `BasicData.CreationDate` | Data de criação do registro nos bancos internos da BDC. | string | | `BasicData.LastUpdateDate` | Data da última consulta feita pela o provedor à Receita Federal para a atualização do registro do documento consultado. | string | Todo `result` traz também `outcome`, o resumo da consulta: `clear`, `alert`, `match`, `no_match` ou `not_found`. ```bash cURL theme={null} curl --request POST 'https://api.omni-ward.com/v1/services' \ --header 'Authorization: Bearer $OMNI_WARD_API_KEY' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: $(uuidgen)' \ --data '{ "services": [ "SERVICE_LOCATE_BY_PHONE" ], "phone": "11999999999", "purpose": "Abertura de conta" }' ``` ```javascript Node.js theme={null} const res = await fetch('https://api.omni-ward.com/v1/services', { method: 'POST', headers: { Authorization: `Bearer ${process.env.OMNI_WARD_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID(), }, body: JSON.stringify({ "services": [ "SERVICE_LOCATE_BY_PHONE" ], "phone": "11999999999", "purpose": "Abertura de conta" }), }); const { results } = await res.json(); ``` ```python Python theme={null} import os, uuid, requests res = requests.post( "https://api.omni-ward.com/v1/services", headers={"Authorization": f"Bearer {os.environ['OMNI_WARD_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}, json={ "services": [ "SERVICE_LOCATE_BY_PHONE" ], "phone": "11999999999", "purpose": "Abertura de conta" }, timeout=90, ) results = res.json()["results"] ``` ```php PHP theme={null} $ch = curl_init("https://api.omni-ward.com/v1/services"); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("OMNI_WARD_API_KEY"), "Content-Type: application/json", "Idempotency-Key: " . bin2hex(random_bytes(16)), ], CURLOPT_POSTFIELDS => '{"services":["SERVICE_LOCATE_BY_PHONE"],"phone":"11999999999","purpose":"Abertura de conta"}', ]); $results = json_decode(curl_exec($ch), true)["results"]; ``` ```java Java theme={null} var body = """ { "services": [ "SERVICE_LOCATE_BY_PHONE" ], "phone": "11999999999", "purpose": "Abertura de conta" } """; var request = HttpRequest.newBuilder(URI.create("https://api.omni-ward.com/v1/services")) .header("Authorization", "Bearer " + System.getenv("OMNI_WARD_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", UUID.randomUUID().toString()) .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString()); ``` ```json 200 theme={null} { "results": [ { "service": "SERVICE_LOCATE_BY_PHONE", "status": { "code": 200, "message": "Success" }, "result": { "BasicData": { "TaxIdNumber": "150*****794", "TaxIdCountry": "BRAZIL", "AlternativeIdNumbers": {}, "ExtendedDocumentInformation": { "RG": { "DocumentLast4Digits": "3265", "CreationDate": "2019-10-29T23:03:31.212Z", "LastUpdateDate": "2019-10-29T23:03:31.212Z", "Sources": [ "ENADE" ] } }, "Name": "VIC************NTO", "Aliases": { "CommonName": "VIC******NTO", "StandardizedName": "VIC************NTO" }, "Gender": "M", "NameWordCount": 3, "NumberOfFullNameNamesakes": 1, "NameUniquenessScore": 1, "FirstNameUniquenessScore": "0,001", "FirstAndLastNameUniquenessScore": "0,001", "BirthDate": "1996-08-05T00:00:00Z", "CapturedBirthDateFromRFSource": "1996-08-05", "IsValidBirthDateInRFSource": true, "Age": 29, "ZodiacSign": "LEAO", "ChineseSign": "Rat", "BirthCountry": "BRASILEIRA", "MotherName": "LED****************IRA", "FatherName": "", "MaritalStatusData": {}, "TaxIdStatus": "REGULAR", "TaxIdOrigin": "RECEITA FEDERAL", "TaxIdFiscalRegion": "ES-RJ", "HasObitIndication": false, "TaxIdStatusDate": "2016-08-23T00:00:00Z", "TaxIdStatusRegistrationDate": "2009-12-14T00:00:00Z", "CreationDate": "2016-08-23T00:00:00Z", "LastUpdateDate": "2025-08-20T00:00:00Z" }, "outcome": "clear" }, "simulated": false, "costMinor": 25 } ], "totalCostMinor": 25 } ``` ```json 422 theme={null} { "error": { "code": "validation_failed", "message": "Alguns serviços não podem ser executados. Nada foi consultado nem cobrado.", "correlationId": "4f1c9a7e-2b1d-4c55-9a51-0d2f6f1c2a10", "details": { "results": [ { "service": "SERVICE_LOCATE_BY_PHONE", "status": { "code": 422, "message": "Validation failed" }, "result": null, "errors": [ { "field": "phone", "code": "required", "message": "Informe telefone: este serviço exige o campo." } ] } ] } } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.