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

# Get client contacts

> Returns a list of client contacts. Uses cursor pagination.



## OpenAPI

````yaml /openapi-private.json get /clients/contacts
openapi: 3.1.0
info:
  title: Spott API Reference
  version: '0.1'
servers:
  - url: https://api.gospott.com
security: []
tags: []
paths:
  /clients/contacts:
    get:
      tags:
        - Client Contacts
      summary: Get client contacts
      description: Returns a list of client contacts. Uses cursor pagination.
      operationId: getClientContacts
      parameters:
        - name: limit
          required: false
          in: query
          description: >-
            Number of client contacts to return per page (min: 1, max: 50,
            default: 25).
          schema:
            minimum: 1
            maximum: 50
            default: 25
            example: 25
            type: integer
        - name: cursor
          required: false
          in: query
          description: >-
            Opaque cursor string for pagination. Use the cursor value from a
            previous response to fetch the next page. Omit for the first page.
          schema:
            example: >-
              eyJtb2RpZmllZEF0IjoiMjAyNC0xMS0wNlQxMDozMDowMC4wMDBaIiwiaWQiOiJjbGllbnQtY29udGFjdC0xMjMifQ.signature
            type: string
        - name: modifiedSince
          required: false
          in: query
          description: >-
            Filter client contacts by sync watermark on or after this date.
            Useful for incremental synchronization. Defaults to beginning of
            time if not provided.
          schema:
            $ref: '#/components/schemas/DateISO'
            default: '1970-01-01T00:00:00.000Z'
            example: '2024-11-01T00:00:00.000Z'
        - name: modifiedUntil
          required: false
          in: query
          description: >-
            Filter client contacts by sync watermark on or before this date.
            Useful for bounded synchronization snapshots. If omitted, no upper
            bound is applied.
          schema:
            $ref: '#/components/schemas/DateISO'
            example: '2024-11-30T23:59:59.999Z'
        - name: listIds
          required: false
          in: query
          description: Filter client contacts by client contact list IDs.
          schema:
            minItems: 1
            maxItems: 25
            uniqueItems: true
            example:
              - client-contact-list-123
              - client-contact-list-456
            type: array
            items:
              type: string
        - name: client_ids
          required: false
          in: query
          description: Filter client contacts by client IDs.
          schema:
            minItems: 1
            maxItems: 25
            uniqueItems: true
            example:
              - client-123
              - client-456
            type: array
            items:
              type: string
      responses:
        '200':
          description: >-
            Successfully retrieved client contacts. Returns items with
            pagination metadata containing the cursor for the next page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetClientContactsResponseDto'
        '400':
          description: >-
            Bad request - invalid query parameters (e.g., limit out of range,
            invalid date format)
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ExceptionBaseDto'
                  - type: object
                    properties:
                      statusCode:
                        type: number
                        example: 400
                      message:
                        type: string
                        example: Limit must be between 1 and 50
                      error:
                        type: string
                        example: Bad Request
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseDto'
        '500':
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseDto'
      security:
        - x-api-key: []
components:
  schemas:
    DateISO:
      id: DateISO
      format: date-time
      anyOf:
        - type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        - type: string
          format: date
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
    GetClientContactsResponseDto:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ClientContactBaseDto'
        pagination:
          $ref: '#/components/schemas/ClientContactCursorPaginationDto'
      required:
        - items
        - pagination
      id: PrivateGetClientContactsResponseDto
    ExceptionBaseDto:
      type: object
      properties:
        status:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        message:
          type: string
        requestId:
          type: string
      required:
        - status
        - message
        - requestId
      id: ExceptionBaseDto
    ClientContactBaseDto:
      type: object
      properties:
        id:
          type: string
          minLength: 1
        candidateId:
          type: string
          minLength: 1
        firstName:
          type: string
        lastName:
          type: string
        avatarUrl:
          anyOf:
            - type: string
            - type: 'null'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/LocationDto'
        client:
          $ref: '#/components/schemas/ClientContactClientDto'
        role:
          anyOf:
            - type: string
            - type: 'null'
        department:
          anyOf:
            - type: string
            - type: 'null'
        startDate:
          $ref: '#/components/schemas/DateISO'
        endDate:
          anyOf:
            - $ref: '#/components/schemas/DateISO'
            - type: 'null'
        active:
          type: boolean
        stage:
          $ref: '#/components/schemas/ClientStageDto'
        mainContact:
          anyOf:
            - $ref: '#/components/schemas/UserBadgeDto'
            - type: 'null'
        createdAt:
          $ref: '#/components/schemas/DateISO'
        customAttributes:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttributeItemDto'
        modifiedAt:
          $ref: '#/components/schemas/DateISO'
      required:
        - id
        - candidateId
        - firstName
        - lastName
        - avatarUrl
        - locations
        - client
        - role
        - department
        - startDate
        - endDate
        - active
        - stage
        - mainContact
        - createdAt
        - customAttributes
        - modifiedAt
      id: PrivateClientContactBaseDto
    ClientContactCursorPaginationDto:
      type: object
      properties:
        cursor:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - cursor
      id: PrivateClientContactCursorPaginationDto
    LocationDto:
      type: object
      properties:
        street1:
          anyOf:
            - type: string
            - type: 'null'
        street2:
          anyOf:
            - type: string
            - type: 'null'
        postalCode:
          anyOf:
            - type: string
            - type: 'null'
        city:
          anyOf:
            - type: string
            - type: 'null'
        region:
          anyOf:
            - type: string
            - type: 'null'
        state:
          anyOf:
            - type: string
            - type: 'null'
        country:
          anyOf:
            - type: string
            - type: 'null'
        rawCityCountry:
          anyOf:
            - type: string
            - type: 'null'
        latitude:
          anyOf:
            - type: number
            - type: 'null'
        longitude:
          anyOf:
            - type: number
            - type: 'null'
        formattedAddress:
          anyOf:
            - type: string
            - type: 'null'
        type:
          anyOf:
            - $ref: '#/components/schemas/LocationType'
            - type: 'null'
      required:
        - street1
        - street2
        - postalCode
        - city
        - region
        - state
        - country
        - rawCityCountry
        - latitude
        - longitude
        - formattedAddress
        - type
      id: PrivateLocationDto
    ClientContactClientDto:
      type: object
      properties:
        company:
          $ref: '#/components/schemas/ClientContactCompanyDto'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/LocationDto'
      required:
        - company
        - locations
      id: PrivateClientContactClientDto
    ClientStageDto:
      type: object
      properties:
        id:
          type: string
          minLength: 1
        order:
          type: number
        name:
          type: string
        colorHex:
          type: string
      required:
        - id
        - order
        - name
        - colorHex
      id: PrivateClientStageDto
    UserBadgeDto:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        avatarUrl:
          anyOf:
            - type: string
            - type: 'null'
        deactivatedAt:
          anyOf:
            - $ref: '#/components/schemas/DateISO'
            - type: 'null'
      required:
        - id
        - name
        - avatarUrl
        - deactivatedAt
      id: PrivateUserBadgeDto
    CustomAttributeItemDto:
      type: object
      properties:
        attributeDefinitionId:
          type: string
          minLength: 1
        label:
          type: string
        aiFillOngoing:
          type: boolean
        aiOverridden:
          type: boolean
        isFilledByAI:
          type: boolean
        value:
          $ref: '#/components/schemas/SharedCustomAttributeTypeDto'
      required:
        - attributeDefinitionId
        - label
        - aiFillOngoing
        - aiOverridden
        - isFilledByAI
        - value
      id: PrivateCustomAttributeItemDto
    LocationType:
      type: string
      enum:
        - primary_home
        - secondary_home
        - primary_work
        - headquarters
        - regional_office
      id: LocationType
    ClientContactCompanyDto:
      type: object
      properties:
        id:
          type: string
          minLength: 1
        name:
          type: string
        logoUrl:
          anyOf:
            - type: string
            - type: 'null'
        linkedinUrl:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - id
        - name
        - logoUrl
        - linkedinUrl
      id: PrivateClientContactCompanyDto
    SharedCustomAttributeTypeDto:
      oneOf:
        - $ref: '#/components/schemas/CustomTextTypeDto'
        - $ref: '#/components/schemas/CustomNumberTypeDto'
        - $ref: '#/components/schemas/CustomCheckboxTypeDto'
        - $ref: '#/components/schemas/CustomDateTypeDto'
        - $ref: '#/components/schemas/CustomTimestampTypeDto'
        - $ref: '#/components/schemas/CustomRatingTypeDto'
        - $ref: '#/components/schemas/CustomSelectTypeDto'
        - $ref: '#/components/schemas/CustomMultiSelectTypeDto'
        - $ref: '#/components/schemas/CustomCurrencyTypeDto'
        - $ref: '#/components/schemas/CustomDateRangeTypeDto'
        - $ref: '#/components/schemas/CustomDurationTypeDto'
        - $ref: '#/components/schemas/CustomUrlTypeDto'
        - $ref: '#/components/schemas/CustomEntityTypeDto'
        - $ref: '#/components/schemas/CustomMultiEntityTypeDto'
      id: SharedPrivateCustomAttributeTypeDto
    CustomTextTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customText
        text:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - viewType
        - text
      id: PrivateCustomTextTypeDto
    CustomNumberTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customNumber
        number:
          anyOf:
            - type: number
            - type: 'null'
      required:
        - viewType
        - number
      id: PrivateCustomNumberTypeDto
    CustomCheckboxTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customCheckbox
        checked:
          anyOf:
            - type: boolean
            - type: 'null'
      required:
        - viewType
        - checked
      id: PrivateCustomCheckboxTypeDto
    CustomDateTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customDate
        date:
          anyOf:
            - $ref: '#/components/schemas/DateISO'
            - type: 'null'
      required:
        - viewType
        - date
      id: PrivateCustomDateTypeDto
    CustomTimestampTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customTimestamp
        timestamp:
          anyOf:
            - $ref: '#/components/schemas/DateISO'
            - type: 'null'
      required:
        - viewType
        - timestamp
      id: PrivateCustomTimestampTypeDto
    CustomRatingTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customRating
        rating:
          anyOf:
            - type: number
            - type: 'null'
      required:
        - viewType
        - rating
      id: PrivateCustomRatingTypeDto
    CustomSelectTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customSelect
        select:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - viewType
        - select
      id: PrivateCustomSelectTypeDto
    CustomMultiSelectTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customMultiSelect
        multiSelect:
          type: array
          items:
            type: string
      required:
        - viewType
        - multiSelect
      id: PrivateCustomMultiSelectTypeDto
    CustomCurrencyTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customCurrency
        monetaryAmount:
          anyOf:
            - $ref: '#/components/schemas/MonetaryAmountDto'
            - type: 'null'
      required:
        - viewType
        - monetaryAmount
      id: PrivateCustomCurrencyTypeDto
    CustomDateRangeTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customDateRange
        dateRange:
          anyOf:
            - $ref: '#/components/schemas/DateRangeDto'
            - type: 'null'
      required:
        - viewType
        - dateRange
      id: PrivateCustomDateRangeTypeDto
    CustomDurationTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customDuration
        duration:
          anyOf:
            - type: number
            - type: 'null'
      required:
        - viewType
        - duration
      id: PrivateCustomDurationTypeDto
    CustomUrlTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customUrl
        url:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - viewType
        - url
      id: PrivateCustomUrlTypeDto
    CustomEntityTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customEntity
        type:
          type: string
          enum:
            - user
        id:
          anyOf:
            - type: string
            - type: 'null'
        entity:
          anyOf:
            - $ref: '#/components/schemas/UserBadgeDto'
            - type: 'null'
      required:
        - viewType
        - type
        - id
      id: PrivateCustomEntityTypeDto
    CustomMultiEntityTypeDto:
      type: object
      properties:
        viewType:
          type: string
          enum:
            - customMultiEntity
        type:
          type: string
          enum:
            - user
        ids:
          type: array
          items:
            type: string
        entities:
          type: array
          items:
            $ref: '#/components/schemas/UserBadgeDto'
      required:
        - viewType
        - type
        - ids
      id: PrivateCustomMultiEntityTypeDto
    MonetaryAmountDto:
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/DmCurrency'
        amount:
          type: number
      required:
        - currency
        - amount
      id: PrivateMonetaryAmountDto
    DateRangeDto:
      type: object
      properties:
        startDate:
          $ref: '#/components/schemas/DateISO'
        endDate:
          anyOf:
            - $ref: '#/components/schemas/DateISO'
            - type: 'null'
      required:
        - startDate
        - endDate
      id: PrivateDateRangeDto
    DmCurrency:
      type: string
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BRL
        - BSD
        - BTC
        - BTN
        - BWP
        - BYN
        - BZD
        - CAD
        - CDF
        - CHF
        - CLF
        - CLP
        - CNH
        - CNY
        - COP
        - CRC
        - CUC
        - CUP
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ERN
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GGP
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - IMP
        - INR
        - IQD
        - IRR
        - ISK
        - JEP
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KPW
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LYD
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRU
        - MUR
        - MVR
        - MWK
        - MXN
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SDG
        - SEK
        - SGD
        - SHP
        - SLE
        - SLL
        - SOS
        - SRD
        - SSP
        - STD
        - STN
        - SVC
        - SYP
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - UYU
        - UZS
        - VEF
        - VES
        - VND
        - VUV
        - WST
        - XAF
        - XAG
        - XAU
        - XCD
        - XCG
        - XDR
        - XOF
        - XPD
        - XPF
        - XPT
        - YER
        - ZAR
        - ZMW
        - ZWG
        - ZWL
      id: DmCurrency
  securitySchemes:
    x-api-key:
      type: apiKey
      name: x-api-key
      in: header
      description: >-
        API key for authentication. Get your API key from Settings → API Keys in
        your Spott dashboard.

````