> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectadesk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar ou atualizar pelo número

> Cria o contato se o número ainda não estiver cadastrado, ou atualiza o contato que já tem esse número.



## OpenAPI

````yaml /api-reference/openapi.yaml post /contacts/upsert
openapi: 3.0.3
info:
  title: Connecta DESK API pública
  version: 1.0.0
  description: >
    API pública do Connecta DESK, disponível em `/api/v1`. O acesso é feito com
    um token gerado no módulo de tokens. Cada token tem permissões por **módulo
    × método**, e toda leitura de lista é paginada.


    ## Autenticação


    ```

    Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

    ```


    O token pertence a uma **empresa**, e não a um usuário. A empresa usada é
    sempre a do token, então enviar `companyId` no corpo não tem efeito. Token
    ausente, inválido, revogado ou expirado recebe a mesma resposta `401`.


    ## Ordem de verificação


    1. **token** → `401`

    2. **empresa ativa** → `403`

    3. **API habilitada no plano** → `403 ERR_API_NOT_ENABLED` (não se aplica a
    on-premise)

    4. **rate limit da empresa** → `429`

    5. **permissão do token** → `403 ERR_API_FORBIDDEN_SCOPE`


    ## Ids de usuário


    Todo id de usuário na API é o id do usuário **nesta empresa**, o mesmo que
    `GET /users` devolve. Vale para o que a API responde (`user.id`,
    `assignedTo.id`, `userCreated.id`) e para o que ela aceita (`userId`,
    `userIds`, `assignedToUserId` e o `{id}` das rotas de usuário).


    A mesma pessoa pode trabalhar em várias empresas, com nome e perfil
    diferentes em cada uma, e tem um id diferente em cada empresa.


    Um id que não pertence a esta empresa responde `404`, com a mesma mensagem
    de um id inexistente.


    ## Paginação


    Todo `GET` de lista é paginado. O `meta` traz apenas `page`, `perPage` e
    `hasMore`, sem o total de registros. Para percorrer tudo, avance `page`
    enquanto `hasMore` for `true`.


    ## Idempotência


    Opcional em `POST`/`PUT`, pelo header `Idempotency-Key`. Se você repetir a
    chamada com a mesma chave e o mesmo corpo, recebe a resposta já gravada (com
    `Idempotent-Replay: true`). Com a mesma chave e um corpo diferente, a
    resposta é `409`.
servers:
  - url: https://api.connectadesk.com/api/v1
    description: Produção
security:
  - apiToken: []
tags:
  - name: contacts
    description: Cadastro de contatos, campos extras e origem de marketing.
  - name: tickets
    x-displayName: Conversas
    description: Abertura, transferência, encerramento e qualificação de conversas.
  - name: messages
    description: Envio assíncrono e leitura de mensagens.
  - name: tags
    description: Tags e vínculo com atendimentos.
  - name: queues
    description: Filas de atendimento e seus atendentes.
  - name: wrapups
    description: Tipos de qualificação.
  - name: users
    description: Atendentes e administradores.
  - name: schedules
    description: Mensagens programadas.
  - name: quick-messages
    description: Respostas rápidas.
  - name: campaigns
    description: Disparos em massa.
  - name: crm
    description: Painéis, etapas, cards e indicadores.
  - name: channels
    description: Canais (somente leitura).
  - name: reports
    description: Relatórios e dashboards.
  - name: products
    description: Catálogo de produtos, categorias e desempenho nas vendas.
  - name: custom-fields
    description: >-
      Campos personalizados de contato e de card, e variáveis globais da
      empresa.
  - name: profiles
    description: Perfis de permissões da empresa (somente leitura).
  - name: webchat
    description: >-
      Webchat nativo pelo seu sistema: abrir sessão de um visitante, enviar e
      ler mensagens. O token precisa do escopo `webchat` (GET e POST).
paths:
  /contacts/upsert:
    post:
      tags:
        - contacts
      summary: Criar ou atualizar pelo número
      description: >-
        Cria o contato se o número ainda não estiver cadastrado, ou atualiza o
        contato que já tem esse número.
      parameters:
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            examples:
              exemplo:
                summary: Corpo da requisição
                value:
                  number: '5511999999999'
                  name: Marina Alves
                  email: marina@exemplo.com.br
                  code: CLI-8842
            schema:
              $ref: '#/components/schemas/ContactInput'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  parameters:
    idempotencyKey:
      name: Idempotency-Key
      in: header
      description: >-
        Chave única da operação. Se você repetir a chamada com a mesma chave e o
        mesmo corpo, recebe a resposta já gravada.
      schema:
        type: string
        maxLength: 200
      example: pedido-88213-confirmacao
  schemas:
    ContactInput:
      type: object
      description: >-
        Campos que podem ser gravados em um contato. A foto (`profilePicUrl`)
        não pode ser alterada por aqui, porque vem do provedor
        (WhatsApp/Instagram) e é atualizada por ele. Ela continua sendo
        devolvida na leitura.
      required:
        - name
      properties:
        name:
          type: string
          description: Nome do contato, como aparece na lista e no atendimento.
          example: Marina Alves
        number:
          type: string
          description: >-
            Telefone com DDI e DDD. Pode vir formatado, como `+55 (11)
            99999-9999`, e só os dígitos são gravados. O país do contato
            (`numberCountry`) é deduzido do DDI, e um número sem DDI de país
            válido responde `422`. Ele identifica o contato no `upsert` e define
            o destinatário no envio de mensagens.
          example: '5511999999999'
        email:
          type: string
          description: >-
            E-mail do contato. Não serve para login, já que contato não é
            usuário do sistema.
          example: marina@exemplo.com.br
        code:
          type: string
          description: >-
            Identificador do contato **no seu sistema**. Se você preencher desde
            a criação, pode reencontrar o contato depois com `GET
            /contacts?code=...`, sem depender do telefone, que pode mudar.
          example: CLI-8842
        origin:
          type: string
          description: Origem do contato. Texto livre, usado nos relatórios.
          example: Site
        cpfcnpj:
          type: string
          description: CPF ou CNPJ. Gravado exatamente como enviado, sem formatação.
          example: '12345678909'
        instagramUsername:
          type: string
          description: Usuário do Instagram, sem o `@`.
          example: marina.alves
        customFields:
          type: array
          description: >
            Campos personalizados a gravar. Identifique cada campo pela `key`,
            que não muda, enquanto o `name` pode ser renomeado no painel a
            qualquer momento.


            Um valor vazio **remove** o campo do contato. Campos que não
            aparecem no corpo ficam como estão.


            A gravação é tudo ou nada. Se algum valor não passar na validação do
            tipo, a resposta é `400` e nenhum campo é gravado.
          items:
            $ref: '#/components/schemas/CustomFieldInputValue'
        sourceUrl:
          type: string
          description: >-
            Página em que o contato converteu, como a URL do anúncio ou do
            formulário.
          example: https://loja.exemplo.com.br/promo
        sourceId:
          type: string
          description: Id, no provedor, do anúncio ou da publicação que originou o contato.
          example: '23851234567890123'
        headline:
          type: string
          description: Título do anúncio ou da publicação de origem.
          example: Coleção de inverno
        utmSource:
          type: string
          description: Parâmetro `utm_source` da origem. É usado no relatório de conversas.
          example: instagram
        utmMedium:
          type: string
          description: Parâmetro `utm_medium`.
          example: cpc
        utmCampaign:
          type: string
          description: Parâmetro `utm_campaign`.
          example: inverno-2026
        utmId:
          type: string
          description: Parâmetro `utm_id`, quando a plataforma de anúncios o envia.
          example: '6543210987'
    Contact:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Nome exibido.
        number:
          type: string
        numberCountry:
          type: string
          nullable: true
          description: >-
            País do número, no padrão ISO 3166-1 alfa-2. Deduzido do DDI quando
            o número é gravado pela API.
          example: BR
        email:
          type: string
          nullable: true
          example: marina@exemplo.com.br
        code:
          type: string
          nullable: true
        cpfCnpj:
          type: string
          nullable: true
          example: '12345678909'
        origin:
          type: string
          nullable: true
        profilePicUrl:
          type: string
          nullable: true
          example: https://cdn.exemplo.com.br/avatar/1042.jpg
        isGroup:
          type: boolean
          description: O contato é um grupo, e não uma pessoa.
        instagramUsername:
          type: string
          nullable: true
          example: marina.alves
        lid:
          type: string
          nullable: true
          example: '178452961234567'
        sourceUrl:
          type: string
          nullable: true
          example: https://loja.exemplo.com.br/promo
        sourceId:
          type: string
          nullable: true
          example: '23851234567890123'
        headline:
          type: string
          nullable: true
          example: Coleção de inverno
        mediaType:
          type: string
          nullable: true
          example: image
        mediaUrl:
          type: string
          nullable: true
          example: https://cdn.exemplo.com.br/anuncios/inverno.jpg
        utmSource:
          type: string
          nullable: true
          example: instagram
        utmMedium:
          type: string
          nullable: true
          example: cpc
        utmCampaign:
          type: string
          nullable: true
          example: inverno-2026
        utmId:
          type: string
          nullable: true
          example: '6543210987'
        fbclid:
          type: string
          nullable: true
          example: IwAR0xYzAbC123
        gclid:
          type: string
          nullable: true
        ctwaClid:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
                description: Nome exibido.
              color:
                type: string
                description: Cor em hexadecimal, com `#`.
                example: '#6941C6'
        customFields:
          type: array
          description: >-
            Campos personalizados de contato preenchidos. Sempre vem na
            resposta, como lista vazia quando o contato não tem nenhum.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
        lastChannel:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
              description: Nome exibido.
            type:
              type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      example:
        id: 842
        name: Maria Silva
        number: '5511987654321'
        numberCountry: BR
        email: maria.silva@exemplo.com.br
        code: CLI-00842
        cpfCnpj: '12345678909'
        origin: site
        profilePicUrl: https://cdn.exemplo.com/avatars/842.jpg
        isGroup: false
        instagramUsername: maria.silva
        lid: null
        sourceUrl: https://loja.exemplo.com.br/promo
        sourceId: '23851234567890123'
        headline: Coleção de inverno
        mediaType: image
        mediaUrl: https://cdn.exemplo.com/anuncios/inverno.jpg
        utmSource: instagram
        utmMedium: cpc
        utmCampaign: inverno-2026
        utmId: '6543210987'
        fbclid: IwAR0xYzAbC123
        gclid: null
        ctwaClid: null
        tags:
          - id: 3
            name: Cliente VIP
            color: '#6941C6'
        customFields:
          - key: plano
            value: Ouro
            customFieldId: 91
            name: Plano
            type: select
        lastChannel:
          id: 11
          name: Instagram Loja
          type: instagram
        createdAt: '2026-07-14T13:22:05.412Z'
        updatedAt: '2026-08-18T09:41:17.883Z'
    CustomFieldInputValue:
      type: object
      description: Campo personalizado a gravar.
      required:
        - id
      properties:
        id:
          description: >-
            Pode ser a `key` do campo (recomendado), o id numérico ou o nome. A
            `key` é a única das três que não muda quando alguém edita o campo no
            painel.
          oneOf:
            - type: string
            - type: integer
          example: plano
        value:
          type: string
          nullable: true
          description: Valor a gravar. Um valor vazio remove o campo do registro.
          example: Ouro
      example:
        id: plano
        value: Ouro
    CustomFieldValue:
      type: object
      description: >-
        Valor de um campo personalizado, junto com a definição do campo. Assim
        você não precisa chamar `GET /custom-fields` para saber qual é o campo
        91.
      properties:
        key:
          type: string
          nullable: true
          description: >-
            Identificador fixo do campo. Use-o para indicar o campo ao gravar
            valores, porque o `name` pode ser renomeado no painel e a integração
            deixaria de funcionar sem aviso.
        value:
          type: string
          description: Valor preenchido no campo, no formato definido pelo tipo.
        customFieldId:
          type: integer
          description: Id da definição do campo personalizado.
          example: 91
        name:
          type: string
          nullable: true
          description: Nome exibido.
        type:
          type: string
          nullable: true
          description: Tipo do campo, que define o formato aceito no valor.
      example:
        key: plano
        value: Ouro
        customFieldId: 91
        name: Plano
        type: select
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Código fixo do erro, para você tratar cada caso no seu sistema.
              example: ERR_API_FORBIDDEN_SCOPE
            message:
              type: string
            details: {}
  responses:
    BadRequest:
      description: Corpo da requisição inválido.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_VALIDATION
              message: O campo `number` é obrigatório.
    UnprocessableEntity:
      description: >-
        O corpo está bem formado, mas falta um campo obrigatório ou algum valor
        não é aceito. Por exemplo, `application` diferente de `contact`/`card`,
        `orderedIds` vazio ou `name` em branco.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_VALIDATION
              message: >-
                O parâmetro `application` é obrigatório e aceita "contact" ou
                "card".
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      description: Token da API no formato `sk_live_…`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.