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

# Create a new contact

> Create a new contact in the specified workspace.



## OpenAPI

````yaml /api-reference/openapi.yaml post /bridge/api/v1/workspaces/{workspaceId}/contacts
openapi: 3.1.0
info:
  title: Bridge API
  summary: Bridge API specification for chat system management.
  description: >-
    Bridge API specification including webhook receiver endpoints, Contact CRUD
    operations, and comprehensive chat system.

                        This API includes:
                        1. Webhook Receiver API - for CRM clients to receive event notifications from Bridge
                        2. Contact CRUD API - for clients to manage contacts in Bridge
                        3. Conversations API - for managing conversations with flexible user identification and participant management
                        4. Messages API - for sending messages and files to a conversation
                        5. Files API - for managing files in a message
                        6. Custom attributes API - for consult custom attributes of an specific workspace
                    
                        **Multi-Tenant Architecture**: All operations are scoped to a specific workspace using workspaceId.
  termsOfService: https://www.sainapsis.com/legal/terms-of-service
  contact:
    name: Bridge Support
    url: https://app.bridge.new/
    email: support@sainapsis.com
  license:
    name: MIT License
    url: https://spdx.org/licenses/MIT.html
  version: 1.0.0
servers:
  - url: https://api-connect-us.bridge.new
    description: Production server
security: []
paths:
  /bridge/api/v1/workspaces/{workspaceId}/contacts:
    post:
      tags:
        - Contacts API
      summary: Create a new contact
      description: Create a new contact in the specified workspace.
      operationId: create_contact_bridge_api_v1_workspaces__workspaceId__contacts_post
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Unique identifier of the workspace (UUID v4).
            examples:
              - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234
            title: Workspaceid
          description: Unique identifier of the workspace (UUID v4).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactBody'
              description: Request body for creating a new contact.
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              examples:
                FORBIDDEN:
                  value:
                    title: Forbidden
                    status: 403
                    code: BRIDGE_CORE_0301
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                WORKSPACE_NOT_FOUND:
                  value:
                    title: Workspace Not Found
                    status: 404
                    code: BRIDGE_WORKSPACE_0001
                INTERNAL_USER_NOT_FOUND:
                  value:
                    title: Internal User Not Found
                    status: 404
                    code: BRIDGE_INTERNAL_0001
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Conflict
          content:
            application/json:
              examples:
                EXTERNAL_USER_ALREADY_EXISTS:
                  value:
                    title: External User Already Exists
                    status: 409
                    code: BRIDGE_EXTERNAL_0002
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - x-api-key: []
components:
  schemas:
    CreateContactBody:
      properties:
        firstName:
          type: string
          title: First Name
          description: Contact's first name.
          examples:
            - John
            - Alice
        lastName:
          type: string
          title: Last Name
          description: Contact's last name.
          examples:
            - Doe
        email:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          title: Email
          description: Contact's email address.
          examples:
            - john.doe@example.com
            - null
        languageCode:
          $ref: '#/components/schemas/LanguageCode'
          title: Language Code
          description: Contact's language code.
          examples:
            - EN
        cellphone:
          type: string
          format: phone
          title: Cellphone
          description: Contact's cellphone number.
          examples:
            - '+14084029292'
        ownerIdentifier:
          anyOf:
            - $ref: '#/components/schemas/InternalUserIdentifierRequest'
            - type: 'null'
          title: Owner Identifier
          description: Identifier of the salesperson or user who owns this contact.
        customAttributes:
          $ref: '#/components/schemas/CustomAttributesBody'
          title: Custom Attributes
          description: Object with open and closed custom attributes.
      additionalProperties: false
      type: object
      required:
        - firstName
        - lastName
        - languageCode
        - cellphone
      title: CreateContactBody
      description: Request body for creating a new contact.
    ContactResponse:
      properties:
        id:
          type: string
          title: Identifier
          description: Unique identifier for the contact (UUID v4).
          examples:
            - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234
        workspaceId:
          type: string
          title: Workspace Identifier
          description: Unique identifier of the workspace this contact belongs to
          examples:
            - 92b2d4f3-81e1-4b61-a7ec-6f4ff3b58be5
        type:
          $ref: '#/components/schemas/ExternalUserType'
          title: Contact Type
          description: >-
            NORMAL when all required identity and custom attribute fields are
            present, PARTIAL otherwise.
          examples:
            - NORMAL
            - PARTIAL
        firstName:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
          description: Contact's first name.
          examples:
            - John
            - null
        lastName:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
          description: Contact's last name.
          examples:
            - Doe
            - null
        email:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          title: Email
          description: Contact's email address.
          examples:
            - john.doe@example.com
            - null
        cellphone:
          anyOf:
            - type: string
              format: phone
            - type: 'null'
          title: Cellphone
          description: Contact's cellphone address.
          examples:
            - '+14084029292'
            - null
        customAttributes:
          items:
            $ref: '#/components/schemas/CustomAttributeResponse'
          type: array
          title: Custom Attributes
          description: Array of custom key-value attributes.
        languageCode:
          anyOf:
            - $ref: '#/components/schemas/LanguageCode'
            - type: 'null'
          title: Language Code
          description: Language code from external user.
          examples:
            - EN
            - null
        ownerId:
          anyOf:
            - type: string
            - type: 'null'
          title: Owner Identifier
          description: Email address of the salesperson or user who owns this contact.
          examples:
            - 37673840-6259-40f9-bbe5-a7db40f8e3cf
            - null
        createdAt:
          type: string
          title: Created At
          description: Timestamp when the contact was created.
          examples:
            - '2003-04-10T08:00:00.000Z'
        updatedAt:
          type: string
          title: Updated At
          description: Timestamp when the contact was last updated.
          examples:
            - '2003-04-10T08:00:00.000Z'
      type: object
      required:
        - id
        - workspaceId
        - type
        - createdAt
        - updatedAt
      title: ContactResponse
      description: Response body for contact-related operations.
    Problem:
      properties:
        title:
          type: string
          title: Title
          description: Short, summary of the problem type.
        status:
          type: integer
          title: Status
          description: >-
            HTTP status code generated by the origin server for this occurrence
            of the problem.
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
          description: Explanation specific to this occurrence of the problem.
        instance:
          anyOf:
            - type: string
            - type: 'null'
          title: Instance
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
        traceId:
          anyOf:
            - type: string
            - type: 'null'
          title: Traceid
          description: Trace ID for debugging purposes.
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
          description: >-
            Error code for identification, view the error codes page for more
            details.
        errors:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Errors
          description: List of error details.
        extra:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Extra
          description: Extra information about the problem.
      type: object
      required:
        - title
        - status
      title: Problem
      description: Object representing a Problem response body.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LanguageCode:
      type: string
      enum:
        - ES
        - EN
      title: LanguageCode
    InternalUserIdentifierRequest:
      properties:
        identifier:
          type: string
          title: Identifier
          description: User identifier value.
          examples:
            - john.doe@example.com
            - '+13802098869'
            - 37673840-6259-40f9-bbe5-a7db40f8e3cf
        identifierType:
          $ref: '#/components/schemas/InternalParticipantIdentifierType'
          title: Identifier Type
          description: Type of identifier for internal users (ID or EMAIL).
          examples:
            - EMAIL
            - ID
      type: object
      required:
        - identifier
        - identifierType
      title: InternalUserIdentifierRequest
      description: Body to identify an internal user in Bridge System.
    CustomAttributesBody:
      properties:
        openAttributes:
          anyOf:
            - items:
                $ref: '#/components/schemas/OpenAttributeRequest'
              type: array
            - type: 'null'
          title: Open Attributes
          description: Array of open attributes.
        closedAttributes:
          anyOf:
            - items:
                $ref: '#/components/schemas/ClosedAttributeRequest'
              type: array
            - type: 'null'
          title: Closed Attributes
          description: Array of closed attributes.
      type: object
      title: CustomAttributesBody
      description: Request body for custom attributes operations.
    ExternalUserType:
      type: string
      enum:
        - PARTIAL
        - NORMAL
      title: ExternalUserType
    CustomAttributeResponse:
      properties:
        key:
          type: string
          title: Key
          description: Attribute key/name
        values:
          items:
            type: string
          type: array
          title: Values
          description: Attribute value
      type: object
      required:
        - key
      title: CustomAttributeResponse
      description: Response body for custom attributes in contact-related operations.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    InternalParticipantIdentifierType:
      type: string
      enum:
        - ID
        - EMAIL
      title: InternalParticipantIdentifierType
    OpenAttributeRequest:
      properties:
        customAttributeId:
          type: string
          title: Custom Attribute Identifier
          description: Unique open custom attribute identifier.
          examples:
            - 651c97c1-b31d-466f-825c-fe77b39e7ae6
        content:
          type: string
          title: Content
          description: Value of open attribute.
      type: object
      required:
        - customAttributeId
        - content
      title: OpenAttributeRequest
      description: Request body for open custom attributes operations.
    ClosedAttributeRequest:
      properties:
        customAttributeId:
          type: string
          title: Custom Attribute Identifier
          description: Unique closed custom attribute identifier.
          examples:
            - 651c97c1-b31d-466f-825c-fe77b39e7ae6
        closedCustomAttributeIds:
          items:
            type: string
          type: array
          title: Closed Custom Attribute Identifiers
          description: List of unique closed attribute value identifiers.
          examples:
            - - 62de01f0-fd48-467c-9c35-18647c51532a
              - 6faf42bb-7d7b-44bd-9e79-5de6fd491134
      type: object
      required:
        - customAttributeId
        - closedCustomAttributeIds
      title: ClosedAttributeRequest
      description: Request body for closed custom attributes operations.
  securitySchemes:
    x-api-key:
      type: apiKey
      description: Copy the API key as provided by the Bridge Console.
      in: header
      name: x-api-key

````