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

# Create contact

> Add a contact to a Tapify Teams workspace.

Send at least the contact’s full name. All other fields are optional.

If you include an email address, Tapify uses it to prevent duplicates. When the email matches an existing contact, Tapify updates that contact with the fields you send and leaves their other details unchanged. Without an email address, each request creates a new contact.

To assign the contact to a team member, set `connectedWithProfileId` to that member’s `id`. The member must belong to the same workspace. Creating or assigning a contact through the API does not send email.

`message` and `captureMethod` are set by Tapify and cannot be changed through the API. Use `internalNote` for a private note that is visible only inside the workspace.


## OpenAPI

````yaml api-reference/openapi.json POST /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:
    post:
      tags:
        - Contacts
      summary: Create contact
      description: >-
        Creates a contact or updates the contact with the same email address.
        Creating or updating a contact through the API does not send email.
      operationId: createContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactRequest'
            examples:
              crmContact:
                summary: Contact from a CRM
                value:
                  fullName: Alex Morgan
                  jobTitle: Sales Director
                  company: Northstar
                  email: alex@northstar.example
                  internalNote: Added from our CRM.
                  tags:
                    - name: Lead
                      color: green
      responses:
        '200':
          description: Existing contact updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactWriteResponse'
        '201':
          description: Contact created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactWriteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/SubscriptionRequired'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateContactRequest:
      type: object
      description: >-
        Details for a new contact. When the email already exists, Tapify updates
        that contact with the fields in this request.
      additionalProperties: false
      required:
        - fullName
      properties:
        fullName:
          type: string
          description: Contact's full name.
          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
          description: Email address. Tapify uses it to prevent duplicate contacts.
          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
        internalNote:
          type: string
          nullable: true
          description: >-
            Private workspace note. Tapify does not show or send it to the
            contact.
          example: Added from our CRM.
        connectedWithProfileId:
          type: string
          format: uuid
          nullable: true
          description: >-
            Team member ID to assign to the contact. The member must be in the
            same workspace. This does not send email.
          example: 45fa16aa-2546-49b3-9d1e-7b7e1c9fb1e7
        tags:
          type: array
          description: Tags to add to the contact.
          items:
            $ref: '#/components/schemas/ContactTagInput'
    ContactWriteResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/ContactWriteResult'
    ContactTagInput:
      type: object
      description: A tag used to organize the contact.
      required:
        - name
      properties:
        name:
          type: string
          description: Tag name shown in Tapify.
          example: Follow up
        color:
          $ref: '#/components/schemas/ContactTagColor'
    ContactWriteResult:
      allOf:
        - $ref: '#/components/schemas/Contact'
        - type: object
          required:
            - created
          properties:
            created:
              type: boolean
              description: True when a new contact was created.
              example: true
    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
    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
    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.
    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
  responses:
    BadRequest:
      description: The request body or one of its fields is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
    PayloadTooLarge:
      description: The JSON request is larger than 256 KB.
      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.

````