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

# Upsert Contact

> Please find the list of acceptable values for the `country` field  <a href="https://highlevel.stoplight.io/docs/integrations/ZG9jOjI4MzUzNDIy-country-list" target="_blank">here</a><br/><br/>The Upsert API will adhere to the configuration defined under the “Allow Duplicate Contact” setting at the Location level. If the setting is configured to check both Email and Phone, the API will attempt to identify an existing contact based on the priority sequence specified in the setting, and will create or update the contact accordingly.<br/><br/>If two separate contacts already exist—one with the same email and another with the same phone—and an upsert request includes both the email and phone, the API will update the contact that matches the first field in the configured sequence, and ignore the second field to prevent duplication.



## OpenAPI

````yaml /api-reference/contacts/openapi.json post /contacts/upsert
openapi: 3.0.0
info:
  title: Contacts API
  description: Documentation for Contacts API
  version: '1.0'
  contact: {}
servers:
  - url: https://services.leadconnectorhq.com
security: []
tags:
  - name: Contacts
    description: Documentation for Contacts API
  - name: Tasks
    description: Documentation for Contacts API
  - name: Appointments
    description: Documentation for Contacts API
  - name: Tags
    description: Documentation for Contacts API
  - name: Notes
    description: Documentation for Contacts API
  - name: Campaigns
    description: Documentation for Contacts API
  - name: Workflow
    description: Documentation for Contacts API
  - name: Bulk
    description: Documentation for Contacts API
  - name: Search
    description: Documentation for Contacts API
  - name: Followers
    description: Documentation for Contacts API
paths:
  /contacts/upsert:
    post:
      tags:
        - Contacts
      summary: Upsert Contact
      description: >-
        Please find the list of acceptable values for the `country` field  <a
        href="https://highlevel.stoplight.io/docs/integrations/ZG9jOjI4MzUzNDIy-country-list"
        target="_blank">here</a><br/><br/>The Upsert API will adhere to the
        configuration defined under the “Allow Duplicate Contact” setting at the
        Location level. If the setting is configured to check both Email and
        Phone, the API will attempt to identify an existing contact based on the
        priority sequence specified in the setting, and will create or update
        the contact accordingly.<br/><br/>If two separate contacts already
        exist—one with the same email and another with the same phone—and an
        upsert request includes both the email and phone, the API will update
        the contact that matches the first field in the configured sequence, and
        ignore the second field to prevent duplication.
      operationId: upsert-contact
      parameters:
        - name: Version
          in: header
          description: API Version
          required: true
          schema:
            type: string
            enum:
              - '2021-07-28'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertContactDto'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertContactsSuccessfulResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestDTO'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDTO'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableDTO'
      security:
        - bearer:
            - contacts.write
components:
  schemas:
    UpsertContactDto:
      type: object
      properties:
        firstName:
          type: string
          example: Rosan
          nullable: true
        lastName:
          type: string
          example: Deo
          nullable: true
        name:
          type: string
          example: Rosan Deo
          nullable: true
        email:
          type: string
          example: rosan@deos.com
          nullable: true
        locationId:
          type: string
          example: ve9EPM428h8vShlRW1KT
        gender:
          type: string
          example: male
        phone:
          type: string
          example: +1 888-888-8888
          nullable: true
        address1:
          type: string
          example: 3535 1st St N
          nullable: true
        city:
          type: string
          example: Dolomite
          nullable: true
        state:
          type: string
          example: AL
          nullable: true
        postalCode:
          type: string
          example: '35061'
        website:
          type: string
          example: https://www.tesla.com
          nullable: true
        timezone:
          type: string
          example: America/Chihuahua
          nullable: true
        dnd:
          type: boolean
          example: true
        dndSettings:
          $ref: '#/components/schemas/DndSettingsSchema'
        inboundDndSettings:
          $ref: '#/components/schemas/InboundDndSettingsSchema'
        tags:
          example:
            - nisi sint commodo amet
            - consequat
          description: >-
            This field will overwrite all current tags associated with the
            contact. To update a tags, it is recommended to use the Add Tag or
            Remove Tag API instead.
          type: array
          items:
            type: string
        customFields:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/TextField'
              - $ref: '#/components/schemas/LargeTextField'
              - $ref: '#/components/schemas/SingleSelectField'
              - $ref: '#/components/schemas/RadioField'
              - $ref: '#/components/schemas/NumericField'
              - $ref: '#/components/schemas/MonetoryField'
              - $ref: '#/components/schemas/CheckboxField'
              - $ref: '#/components/schemas/MultiSelectField'
              - $ref: '#/components/schemas/FileField'
        source:
          type: string
          example: public api
        dateOfBirth:
          type: object
          description: >-
            The birth date of the contact. Supported formats: YYYY/MM/DD,
            MM/DD/YYYY, YYYY-MM-DD, MM-DD-YYYY, YYYY.MM.DD, MM.DD.YYYY,
            YYYY_MM_DD, MM_DD_YYYY
          example: '1990-09-25'
          nullable: true
        country:
          type: string
          example: US
        companyName:
          type: string
          example: DGS VolMAX
          nullable: true
        assignedTo:
          type: string
          example: y0BeYjuRIlDwsDcOHOJo
          description: User's Id
        createNewIfDuplicateAllowed:
          type: boolean
          description: >-
            Controls whether to create a new contact or update an existing
            duplicate. **Scenario 1:** If this value is `true` and the location
            allows duplicate contacts, a new contact will be created immediately
            without checking for duplicates. **Scenario 2:** If this value is
            `true` but the location does not allow duplicate contacts, this
            field is ignored and the normal upsert behavior applies: the API
            will search for an existing duplicate contact, update it if found,
            or create a new contact if not found. **Scenario 3:** If this value
            is `false` or not provided, the normal upsert behavior applies
            regardless of the location's duplicate contact setting.
          example: false
          default: false
      required:
        - locationId
    UpsertContactsSuccessfulResponseDto:
      type: object
      properties:
        new:
          type: boolean
          example: true
        contact:
          $ref: '#/components/schemas/GetContectByIdSchema'
        traceId:
          type: string
    BadRequestDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 400
        message:
          type: string
          example: Bad Request
      required:
        - statusCode
        - message
    UnauthorizedDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 401
        message:
          type: string
          example: 'Invalid token: access token is invalid'
        error:
          type: string
          example: Unauthorized
      required:
        - statusCode
        - message
        - error
    UnprocessableDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 422
        message:
          type: array
          items:
            type: string
          example:
            - Unprocessable Entity
        error:
          type: string
          example: Unprocessable Entity
      required:
        - statusCode
        - message
        - error
    DndSettingsSchema:
      type: object
      properties:
        Call:
          $ref: '#/components/schemas/DndSettingSchema'
        Email:
          $ref: '#/components/schemas/DndSettingSchema'
        SMS:
          $ref: '#/components/schemas/DndSettingSchema'
        WhatsApp:
          $ref: '#/components/schemas/DndSettingSchema'
        GMB:
          $ref: '#/components/schemas/DndSettingSchema'
        FB:
          $ref: '#/components/schemas/DndSettingSchema'
    InboundDndSettingsSchema:
      type: object
      properties:
        all:
          $ref: '#/components/schemas/InboundDndSettingSchema'
    TextField:
      type: object
      properties:
        id:
          type: string
          example: 6dvNaf7VhkQ9snc5vnjJ
        key:
          type: string
          example: my_custom_field
        field_value:
          type: string
          example: My Text
      required:
        - id
    LargeTextField:
      type: object
      properties:
        id:
          type: string
          example: 6dvNaf7VhkQ9snc5vnjJ
        key:
          type: string
          example: my_custom_field
        field_value:
          type: string
          example: My Text
      required:
        - id
    SingleSelectField:
      type: object
      properties:
        id:
          type: string
          example: 6dvNaf7VhkQ9snc5vnjJ
        key:
          type: string
          example: my_custom_field
        field_value:
          type: string
          example: My Selected Option
      required:
        - id
    RadioField:
      type: object
      properties:
        id:
          type: string
          example: 6dvNaf7VhkQ9snc5vnjJ
        key:
          type: string
          example: my_custom_field
        field_value:
          type: string
          example: My Selected Option
      required:
        - id
    NumericField:
      type: object
      properties:
        id:
          type: string
          example: 6dvNaf7VhkQ9snc5vnjJ
        key:
          type: string
          example: my_custom_field
        field_value:
          type: object
          example: 100
      required:
        - id
    MonetoryField:
      type: object
      properties:
        id:
          type: string
          example: 6dvNaf7VhkQ9snc5vnjJ
        key:
          type: string
          example: my_custom_field
        field_value:
          type: object
          example: 100.5
      required:
        - id
    CheckboxField:
      type: object
      properties:
        id:
          type: string
          example: 6dvNaf7VhkQ9snc5vnjJ
        key:
          type: string
          example: my_custom_field
        field_value:
          example:
            - test
            - test2
          type: array
          items:
            type: string
      required:
        - id
    MultiSelectField:
      type: object
      properties:
        id:
          type: string
          example: 6dvNaf7VhkQ9snc5vnjJ
        key:
          type: string
          example: my_custom_field
        field_value:
          example:
            - test
            - test2
          type: array
          items:
            type: string
      required:
        - id
    FileField:
      type: object
      properties:
        id:
          type: string
          example: 6dvNaf7VhkQ9snc5vnjJ
        key:
          type: string
          example: my_custom_field
        field_value:
          type: object
          example:
            f31175d4-2b06-4fc6-b7bc-74cd814c68cb:
              meta:
                fieldname: 1HeGizb13P0odwgOgKSs
                originalname: IMG_20231215_164412935.jpg
                encoding: 7bit
                mimetype: image/jpeg
                size: 1786611
                uuid: f31175d4-2b06-4fc6-b7bc-74cd814c68cb
              url: >-
                https://services.leadconnectorhq.com/documents/download/w2M9qTZ0ZJz8rGt02jdJ
              documentId: w2M9qTZ0ZJz8rGt02jdJ
      required:
        - id
    GetContectByIdSchema:
      type: object
      properties:
        id:
          type: string
          example: seD4PfOuKoVMLkEZqohJ
        name:
          type: string
          example: rubika deo
        locationId:
          type: string
          example: ve9EPM428h8vShlRW1KT
        firstName:
          type: string
          example: rubika
        lastName:
          type: string
          example: Deo
        email:
          type: string
          example: rubika@deos.com
        emailLowerCase:
          type: string
          example: rubika@deos.com
        timezone:
          type: string
          example: Asia/Calcutta
        companyName:
          type: string
          example: DGS VolMAX
        phone:
          type: string
          example: '+18832327657'
        dnd:
          type: boolean
          example: true
        dndSettings:
          $ref: '#/components/schemas/DndSettingsSchema'
        type:
          type: string
          example: read
        source:
          type: string
          example: public api
        assignedTo:
          type: string
          example: ve9EPM428h8vShlRW1KT
        address1:
          type: string
          example: 3535 1st St N
        city:
          type: string
          example: ruDolomitebika
        state:
          type: string
          example: AL
        country:
          type: string
          example: US
        postalCode:
          type: string
          example: '35061'
        website:
          type: string
          example: https://www.tesla.com
        tags:
          example:
            - nisi sint commodo amet
            - consequat
          type: array
          items:
            type: string
        dateOfBirth:
          type: string
          example: Date format YYYY-MM-DD
        dateAdded:
          type: string
          example: '2021-07-02T05:18:26.704Z'
        dateUpdated:
          type: string
          example: '2021-07-02T05:18:26.704Z'
        attachments:
          type: string
        ssn:
          type: string
        keyword:
          type: string
          example: test
        firstNameLowerCase:
          type: string
          example: rubika
        fullNameLowerCase:
          type: string
          example: rubika deo
        lastNameLowerCase:
          type: string
          example: deo
        lastActivity:
          type: string
          example: '2021-07-16T11:39:30.564Z'
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldSchema'
        businessId:
          type: string
          example: 641c094001436dbc2081e642
        attributionSource:
          $ref: '#/components/schemas/AttributionSource'
        lastAttributionSource:
          $ref: '#/components/schemas/AttributionSource'
        visitorId:
          type: string
          description: visitorId is the Unique ID assigned to each Live chat visitor.
          example: ve9EPM428h8vShlRW1KT
    DndSettingSchema:
      type: object
      properties:
        status:
          type: string
          enum:
            - active
            - inactive
            - permanent
        message:
          type: string
        code:
          type: string
      required:
        - status
    InboundDndSettingSchema:
      type: object
      properties:
        status:
          type: string
          enum:
            - active
            - inactive
        message:
          type: string
      required:
        - status
    CustomFieldSchema:
      type: object
      properties:
        id:
          type: string
          example: MgobCB14YMVKuE4Ka8p1
        value:
          type: string
          example: name
    AttributionSource:
      type: object
      properties:
        url:
          type: string
          example: Trigger Link
        campaign:
          type: string
          nullable: true
        utmSource:
          type: string
          nullable: true
        utmMedium:
          type: string
          nullable: true
        utmContent:
          type: string
          nullable: true
        referrer:
          type: string
          example: 'https: //www.google.com'
          nullable: true
        campaignId:
          type: string
          nullable: true
        fbclid:
          type: string
          nullable: true
        gclid:
          type: string
          example: >-
            CjOKCQjwnNyUBhCZARISAI9AYIFtNnIcWcYGIOQINz_ZoFI5SSLRRugSoPZoiEu27IZBY£1-MAIWmEaAo2VEALW_WCB
          nullable: true
        msclikid:
          type: string
          nullable: true
        dclid:
          type: string
          nullable: true
        fbc:
          type: string
          nullable: true
        fbp:
          type: string
          example: fb. 1.1674748390986.1171287961
          nullable: true
        fbEventId:
          type: string
          example: Mozilla/5.0
          nullable: true
        userAgent:
          type: string
          example: Mozilla/5.0
          nullable: true
        ip:
          type: string
          example: 58.111.106.198
          nullable: true
        medium:
          type: string
          example: survey
          nullable: true
        mediumId:
          type: string
          example: FglfHAn30PRwsZVyQlKp
          nullable: true
      required:
        - url
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Use the Access Token generated with user type as Sub-Account (OR)
        Private Integration Token of Sub-Account.
      type: http

````