> ## 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.

# Create contact

> A number that already belongs to another contact in your company returns `409` (`ERR_DUPLICATED_CONTACT`).



## OpenAPI

````yaml /api-reference/openapi.en.yaml post /contacts
openapi: 3.0.3
info:
  title: Connecta DESK Public API
  version: 1.0.0
  description: >-
    Public API of Connecta DESK, available at `/api/v1`. Access uses a token
    generated in the tokens module. Each token has permissions per **module ×
    method**, and every list read is paginated.


    ## Authentication


    ```

    Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

    ```


    The token belongs to a **company**, not to a user. The company used is
    always the token's company, so sending `companyId` in the body has no
    effect. A missing, invalid, revoked or expired token gets the same `401`
    response.


    ## Order of checks


    1. **token** → `401`

    2. **active company** → `403`

    3. **API enabled on the plan** → `403 ERR_API_NOT_ENABLED` (does not apply
    to on-premise)

    4. **company rate limit** → `429`

    5. **token permission** → `403 ERR_API_FORBIDDEN_SCOPE`


    ## User ids


    Every user id in the API is the user's id **in this company**, the same one
    `GET /users` returns. This applies to what the API returns (`user.id`,
    `assignedTo.id`, `userCreated.id`) and to what it accepts (`userId`,
    `userIds`, `assignedToUserId` and the `{id}` in user routes).


    The same person can work in several companies, with a different name and
    profile in each one, and has a different id in each company.


    An id that does not belong to this company returns `404`, with the same
    message as an id that does not exist.


    ## Pagination


    Every list `GET` is paginated. The `meta` contains only `page`, `perPage`
    and `hasMore`, without the total number of records. To go through
    everything, keep advancing `page` while `hasMore` is `true`.


    ## Idempotency


    Optional on `POST`/`PUT`, through the `Idempotency-Key` header. If you
    repeat the call with the same key and the same body, you get the stored
    response (with `Idempotent-Replay: true`). With the same key and a different
    body, the response is `409`.
servers:
  - url: https://api.connectadesk.com/api/v1
    description: Production
security:
  - apiToken: []
tags:
  - name: contacts
    description: Contact records, extra fields and marketing source.
  - name: tickets
    x-displayName: Tickets
    description: Opening, transferring, closing and wrap-up of tickets.
  - name: messages
    description: Asynchronous sending and reading of messages.
  - name: tags
    description: Tags and their link to tickets.
  - name: queues
    description: Service queues and their agents.
  - name: wrapups
    description: Wrap-up types.
  - name: users
    description: Agents and administrators.
  - name: schedules
    description: Scheduled messages.
  - name: quick-messages
    description: Quick replies.
  - name: campaigns
    description: Bulk sending.
  - name: crm
    description: Boards, stages, cards and metrics.
  - name: channels
    description: Channels (read only).
  - name: reports
    description: Reports and dashboards.
  - name: products
    description: Product catalog, categories and sales performance.
  - name: custom-fields
    description: Custom fields for contacts and cards, plus company-wide global variables.
  - name: profiles
    description: Company permission profiles (read only).
  - name: webchat
    description: >-
      Native webchat from your own system: open a visitor session, send and read
      messages. The token needs the `webchat` scope (GET and POST).
paths:
  /contacts:
    post:
      tags:
        - contacts
      summary: Create contact
      description: >-
        A number that already belongs to another contact in your company returns
        `409` (`ERR_DUPLICATED_CONTACT`).
      parameters:
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactInput'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  parameters:
    idempotencyKey:
      name: Idempotency-Key
      in: header
      description: >-
        Unique key for the operation. If you repeat the call with the same key
        and the same body, you get the stored response.
      schema:
        type: string
        maxLength: 200
      example: pedido-88213-confirmacao
  schemas:
    ContactInput:
      type: object
      description: >-
        Fields that can be saved on a contact. The photo (`profilePicUrl`)
        cannot be changed here, because it comes from the provider
        (WhatsApp/Instagram) and is updated by it. It is still returned when you
        read the contact.
      required:
        - name
      properties:
        name:
          type: string
          description: Contact name, as it appears in the list and in the ticket.
          example: Marina Alves
        number:
          type: string
          description: >-
            Phone number with country and area code. It can be formatted, like
            `+55 (11) 99999-9999`, and only the digits are saved. The contact's
            country (`numberCountry`) is inferred from the country code, and a
            number without a valid country code returns `422`. It identifies the
            contact in the `upsert` and sets the recipient when sending
            messages.
          example: '5511999999999'
        email:
          type: string
          description: >-
            Contact's email. It is not used for login, since a contact is not a
            user of the system.
          example: marina@exemplo.com.br
        code:
          type: string
          description: >-
            Identifier of the contact **in your system**. If you fill it in when
            creating the contact, you can find it again later with `GET
            /contacts?code=...`, without relying on the phone number, which can
            change.
          example: CLI-8842
        origin:
          type: string
          description: Where the contact came from. Free text, used in reports.
          example: Site
        cpfcnpj:
          type: string
          description: CPF or CNPJ. Saved exactly as sent, with no formatting applied.
          example: '12345678909'
        instagramUsername:
          type: string
          description: Instagram username, without the `@`.
          example: marina.alves
        customFields:
          type: array
          description: >-
            Custom fields to save. Identify each field by its `key`, which does
            not change, while the `name` can be renamed in the panel at any
            time.


            An empty value **removes** the field from the contact. Fields that
            do not appear in the body are left as they are.


            The save is all or nothing. If any value fails the type validation,
            the response is `400` and no field is saved.
          items:
            $ref: '#/components/schemas/CustomFieldInputValue'
        sourceUrl:
          type: string
          description: >-
            Page where the contact converted, such as the URL of the ad or the
            form.
          example: https://loja.exemplo.com.br/promo
        sourceId:
          type: string
          description: Id, at the provider, of the ad or post that brought in the contact.
          example: '23851234567890123'
        headline:
          type: string
          description: Title of the ad or post the contact came from.
          example: Coleção de inverno
        utmSource:
          type: string
          description: >-
            `utm_source` parameter of the source. It is used in the
            conversations report.
          example: instagram
        utmMedium:
          type: string
          description: '`utm_medium` parameter.'
          example: cpc
        utmCampaign:
          type: string
          description: '`utm_campaign` parameter.'
          example: inverno-2026
        utmId:
          type: string
          description: '`utm_id` parameter, when the ad platform sends it.'
          example: '6543210987'
    Contact:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Display name.
        number:
          type: string
        numberCountry:
          type: string
          nullable: true
          description: >-
            Country of the number, as an ISO 3166-1 alpha-2 code. Inferred from
            the country code when the number is saved through the 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: The contact is a group, not a person.
        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: Display name.
              color:
                type: string
                description: Color in hexadecimal, with `#`.
                example: '#6941C6'
        customFields:
          type: array
          description: >-
            Contact custom fields that are filled in. Always included in the
            response, as an empty list when the contact has none.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
        lastChannel:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
              description: Display name.
            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: Custom field to save.
      required:
        - id
      properties:
        id:
          description: >-
            Can be the field's `key` (recommended), its numeric id or its name.
            The `key` is the only one of the three that does not change when
            someone edits the field in the panel.
          oneOf:
            - type: string
            - type: integer
          example: plano
        value:
          type: string
          nullable: true
          description: Value to save. An empty value removes the field from the record.
          example: Ouro
      example:
        id: plano
        value: Ouro
    CustomFieldValue:
      type: object
      description: >-
        Value of a custom field, together with the field's definition. This way
        you do not need to call `GET /custom-fields` to find out what field 91
        is.
      properties:
        key:
          type: string
          nullable: true
          description: >-
            Fixed identifier of the field. Use it to point to the field when
            saving values, because the `name` can be renamed in the panel and
            the integration would stop working without warning.
        value:
          type: string
          description: Value filled in for the field, in the format defined by its type.
        customFieldId:
          type: integer
          description: Id of the custom field definition.
          example: 91
        name:
          type: string
          nullable: true
          description: Display name.
        type:
          type: string
          nullable: true
          description: Field type, which defines the format accepted for the value.
      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: Fixed error code, so your system can handle each case.
              example: ERR_API_FORBIDDEN_SCOPE
            message:
              type: string
            details: {}
  responses:
    BadRequest:
      description: Invalid request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_VALIDATION
              message: O campo `number` é obrigatório.
    Unauthorized:
      description: Token missing, invalid, revoked or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_UNAUTHORIZED
              message: Token de API ausente ou inválido.
    Forbidden:
      description: >-
        Inactive company, API not enabled on the plan, or insufficient
        permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_FORBIDDEN_SCOPE
              message: >-
                O token não tem permissão para este método neste módulo. A
                mensagem real nomeia os dois.
    Conflict:
      description: '`Idempotency-Key` conflict.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_IDEMPOTENCY_KEY_REUSED
              message: Idempotency-Key já usada com um corpo diferente.
    UnprocessableEntity:
      description: >-
        The body is well formed, but a required field is missing or a value is
        not accepted. For example, `application` other than `contact`/`card`, an
        empty `orderedIds` or a blank `name`.
      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: API token in the `sk_live_…` format.

````

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