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

# List contacts

> Get saved contacts from across a Tapify Teams workspace.

Tapify returns saved contacts from newest to oldest. Scan drafts are included only after someone saves them.

The response can contain contacts from the entire workspace, including messages and private notes. Keep the API key and any exported contact data secure.

Each request returns up to 100 contacts. Use `limit` and `offset` to move through a longer list. See [Pagination](/api-reference/requests#pagination) for an example.


## OpenAPI

````yaml api-reference/openapi.json GET /contacts
openapi: 3.0.3
info:
  title: Tapify API
  version: 1.0.0
  description: Manage team members and contacts in a Tapify Teams workspace.
servers:
  - url: https://tapify.app/api/v1
    description: Tapify API
security:
  - bearerAuth: []
tags:
  - name: Workspace
    description: Check the workspace connected to an API key.
  - name: Team members
    description: Manage members and their digital business cards.
  - name: Contacts
    description: Manage contacts collected across the workspace.
paths:
  /contacts:
    get:
      tags:
        - Contacts
      summary: List contacts
      description: Returns saved workspace contacts from newest to oldest.
      operationId: listContacts
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A paginated list of contacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/SubscriptionRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    Limit:
      name: limit
      in: query
      description: Number of results to return.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 100
    Offset:
      name: offset
      in: query
      description: Number of results to skip.
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
  schemas:
    ContactListResponse:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Contact:
      type: object
      description: A contact saved in the Tapify Teams workspace.
      required:
        - id
        - workspaceId
        - fullName
        - jobTitle
        - company
        - email
        - mobile
        - phone
        - website
        - linkedin
        - address
        - message
        - internalNote
        - captureMethod
        - connectedWith
        - tags
        - details
        - createdAt
        - enrichedAt
      properties:
        id:
          type: string
          format: uuid
          description: Contact ID. Use this value in other contact endpoints.
          example: f08f7c49-8f1e-42ac-b5ac-e0d6bd37d938
        workspaceId:
          type: string
          format: uuid
          description: ID of the workspace that contains the contact.
          example: 9df81bd4-3d76-42cc-9518-a019ea75a221
        fullName:
          type: string
          example: Alex Morgan
        jobTitle:
          type: string
          nullable: true
          example: Sales Director
        company:
          type: string
          nullable: true
          example: Northstar
        email:
          type: string
          format: email
          nullable: true
          example: alex@northstar.example
        mobile:
          type: string
          nullable: true
          description: Mobile phone number.
          example: '+31612345678'
        phone:
          type: string
          nullable: true
          description: Other phone number, such as an office number.
        website:
          type: string
          nullable: true
          example: https://northstar.example
        linkedin:
          type: string
          nullable: true
          example: https://linkedin.com/in/alex-morgan
        address:
          type: string
          nullable: true
          example: Amsterdam, Netherlands
        message:
          type: string
          nullable: true
          readOnly: true
          description: >-
            Message the contact submitted through a digital business card.
            Read-only.
          example: Interested in a demo.
        internalNote:
          type: string
          nullable: true
          description: >-
            Private workspace note. Tapify does not show or send it to the
            contact.
          example: Met at Tech Expo.
        captureMethod:
          allOf:
            - $ref: '#/components/schemas/ContactCaptureMethod'
          readOnly: true
          description: How the contact was added to Tapify. Read-only.
        connectedWith:
          allOf:
            - $ref: '#/components/schemas/ConnectedTeamMember'
          description: Team member assigned to the contact, or null when unassigned.
          nullable: true
        tags:
          type: array
          description: Tags used to organize the contact.
          items:
            $ref: '#/components/schemas/ContactTag'
        details:
          type: array
          readOnly: true
          description: >-
            Read-only list built from the contact's email, phone, website,
            LinkedIn, and address fields.
          items:
            $ref: '#/components/schemas/ContactDetail'
        createdAt:
          type: string
          format: date-time
          description: Date and time the contact was added.
          example: '2026-07-28T09:30:00.000Z'
        enrichedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Date and time enrichment was last applied, or null when it has not
            been applied.
    Pagination:
      type: object
      description: Information for moving through a list of results.
      required:
        - limit
        - offset
        - total
        - hasMore
      properties:
        limit:
          type: integer
          description: Maximum number of items requested.
          example: 100
        offset:
          type: integer
          description: Number of items skipped before this page starts.
          example: 0
        total:
          type: integer
          description: Total number of matching items.
          example: 1
        hasMore:
          type: boolean
          description: True when another page is available.
          example: false
    ErrorResponse:
      type: object
      description: Information about a request that Tapify could not complete.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Short code that identifies the error.
              example: bad_request
            message:
              type: string
              description: Readable explanation of what went wrong.
              example: Request body is invalid.
            details:
              type: object
              description: Extra information that can help fix the request.
              additionalProperties: true
              nullable: true
    ContactCaptureMethod:
      type: string
      description: >-
        How the contact was added, such as manually, through a profile form, or
        by scanning a card or QR code. API-created contacts use manual. Tapify
        sets this value and the API cannot change it.
      enum:
        - manual
        - profile_form
        - ai_scan
        - paper_card
        - digital_card
        - linkedin_qr
        - vcard
    ConnectedTeamMember:
      type: object
      description: Team member assigned to the contact.
      required:
        - id
        - name
        - avatarUrl
      properties:
        id:
          type: string
          format: uuid
          description: ID of the team member assigned to the contact.
          example: 45fa16aa-2546-49b3-9d1e-7b7e1c9fb1e7
        name:
          type: string
          example: Mina Park
        avatarUrl:
          type: string
          format: uri
          nullable: true
          example: https://example.com/mina.jpg
    ContactTag:
      type: object
      description: A tag saved on the contact.
      required:
        - name
        - color
      properties:
        name:
          type: string
          example: Follow up
        color:
          $ref: '#/components/schemas/ContactTagColor'
    ContactDetail:
      type: object
      description: One saved way to contact the person.
      required:
        - type
        - value
      properties:
        type:
          type: string
          description: Type of contact information.
          enum:
            - email
            - mobile
            - phone
            - website
            - linkedin
            - address
          example: email
        value:
          type: string
          example: alex@northstar.example
        isPrimary:
          type: boolean
          description: True when this is the contact's main detail of this kind.
          example: true
    ContactTagColor:
      type: string
      description: Badge color used for the tag. Omit this field to use neutral.
      enum:
        - red
        - green
        - blue
        - purple
        - pink
        - yellow
        - indigo
        - neutral
      default: neutral
  responses:
    Unauthorized:
      description: The API key is missing, incorrect, or deleted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    SubscriptionRequired:
      description: The workspace needs an active Teams subscription.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Too many requests were sent in a short period.
      headers:
        Retry-After:
          description: Seconds to wait before trying again.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Tapify could not complete the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Tapify API key
      description: API key created under Settings → API keys.

````