PicChat

Contatos

Buscar contato por celular ou e-mail

GEThttps://api.picchat.com.br/contacts/find

Busca um contato da conta pelo celular e/ou e-mail (pelo menos um), com a mesma normalização do create-or-update, e devolve o registro com as propriedades num mapa properties ({ internal_name: valor }). Em propriedades de seleção o valor é o internal_name da opção. Contato inexistente responde 200 com corpo vazio (não 404). Sem mobilephone nem email a API responde 500. Se os dois vierem e casarem com contatos diferentes, volta um deles, sem ordem garantida.

Autenticação: Bearer tokenPermissão: Token da conta (Bearer). Estas rotas não passam pelo grupo de permissão do usuário.

Parâmetros de consulta (query)

  • mobilephonestring

    Celular em qualquer formato (só os dígitos contam; DDI 55 é adicionado quando faltar).

  • emailstring

    E-mail (sem diferenciar maiúsculas).

  • propertiesstring

    Lista separada por vírgula de `internal_name` para limitar as propriedades devolvidas. Omitido, devolve todas.

Respostas

200Contato encontrado (ou corpo vazio quando não existe).

  • idstring (uuid)

    ID do contato (UUID v7).

  • first_namestring | null

    Nome.

  • last_namestring | null

    Sobrenome.

  • statusstring | null

    Status livre do contato.

  • emailstring | null

    E-mail, sempre em minúsculas.

  • mobilephonestring | null

    Celular só com dígitos e DDI (ex.: 5511999990000), ou ID de grupo.

  • is_marketingboolean | null

    Aceita comunicação de marketing.

  • opt_outboolean | null

    Pediu para não receber mais mensagens.

  • is_groupboolean | null

    É um grupo de WhatsApp.

  • descriptionstring | null

    Descrição livre.

  • account_idstring (uuid)

    Conta dona do contato (a do token).

  • user_idstring (uuid) | null

    Usuário responsável; esta rota grava sempre null em contatos novos.

  • imagestring | null

    URL da foto.

  • font_detailstring | null

    Detalhe livre da origem (ex.: nome do formulário).

  • fontstring

    Origem do contato. Valor fora da lista derruba a requisição com 500.

    referralsorganic_searchofflinesocial_mediapaid_searchpaid_socialemail_marketingother_campaignsdirect_trafficdirect_insertionimportation

  • numberValidboolean | null

    Marcação de número validado (padrão false = "não validado", não "inválido").

  • invalid_numberboolean | null

    Número marcado como inválido pela plataforma.

  • invalid_emailboolean | null

    E-mail com bounce permanente.

  • emailValidboolean | null

    Marcação de e-mail validado (padrão false = "não validado").

  • deletedboolean | null

    Contato excluído.

  • is_verified_userboolean | null

    Usado por canais do Instagram.

  • follower_countinteger | null

    Usado por canais do Instagram.

  • userNamestring | null

    Usuário no Instagram.

  • is_user_follow_businessboolean | null

    Usado por canais do Instagram.

  • is_business_follow_userboolean | null

    Usado por canais do Instagram.

  • insta_idstring | null

    ID no Instagram.

  • wa_group_idstring | null

    ID do grupo na Cloud API (só grupos).

  • wa_invite_linkstring | null

    Link de convite do grupo (só grupos).

  • created_atstring (date-time)

    Criação.

  • updated_atstring (date-time)

    Última atualização.

  • propertiesobject

    Mapa `{ internal_name: valor }`. Em propriedades de seleção o valor é o `internal_name` da opção escolhida.

403Foi enviado um `account_id` (query ou corpo) diferente da conta do token.

498Token ausente, inválido, de conta inexistente ou revogado. Status não padrão (498), usado em toda a API.

500Nem `mobilephone` nem `email` informados (ou celular em formato não reconhecido).