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

# Create Relationship Fields

> Create a writable source field and its automatically maintained reverse field. For example, a dashboard user has one organization, and the organization lists its dashboard users. Updating the source field on a record maintains the reverse side. Requires field creation permission and edit access to each custom object. This creates the field definitions; it does not link any records.



## OpenAPI

````yaml /openapi.json post /v2/fields/relationships
openapi: 3.1.0
info:
  title: Conversion API
  version: 2.0.0
  description: >-
    The Conversion API lets you programmatically manage contacts, track custom
    events, and manage their associated data.
servers:
  - url: https://pub-api.conversion.ai/api
security:
  - apiKey: []
paths:
  /v2/fields/relationships:
    post:
      summary: Create Relationship Fields
      description: >-
        Create a writable source field and its automatically maintained reverse
        field. For example, a dashboard user has one organization, and the
        organization lists its dashboard users. Updating the source field on a
        record maintains the reverse side. Requires field creation permission
        and edit access to each custom object. This creates the field
        definitions; it does not link any records.
      operationId: createRelationshipField
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source:
                  $ref: '#/components/schemas/RelationshipFieldSide'
                target:
                  $ref: '#/components/schemas/RelationshipFieldSide'
              required:
                - source
                - target
            example:
              source:
                objectType: CUSTOM_OBJECT
                customObjectId: 528f0cc5-431c-4f3b-9d3c-7204740a3f76
                key: organization
                label: Organization
              target:
                objectType: CUSTOM_OBJECT
                customObjectId: f4f9ae15-12e8-4b3f-9822-22166d455f40
                key: dashboard_users
                label: Dashboard Users
      responses:
        '200':
          description: Relationship fields created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sourceField:
                        $ref: '#/components/schemas/RelationshipFieldReference'
                      relatedFields:
                        type: array
                        items:
                          $ref: '#/components/schemas/RelationshipFieldReference'
                    required:
                      - sourceField
                      - relatedFields
              example:
                data:
                  sourceField:
                    key: organization
                    objectType: CUSTOM_OBJECT
                    customObjectId: 528f0cc5-431c-4f3b-9d3c-7204740a3f76
                  relatedFields:
                    - key: dashboard_users
                      objectType: CUSTOM_OBJECT
                      customObjectId: f4f9ae15-12e8-4b3f-9822-22166d455f40
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The API key lacks permission, or custom objects are not enabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Unexpected service failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RelationshipFieldSide:
      type: object
      properties:
        objectType:
          type: string
          enum:
            - CONTACT
            - COMPANY
            - OPPORTUNITY
            - CAMPAIGN
            - CAMPAIGN_MEMBER
            - CUSTOM_OBJECT
        customObjectId:
          type: string
          format: uuid
          description: >-
            Required when objectType is CUSTOM_OBJECT; omit for standard
            objects.
        key:
          type: string
          description: >-
            Required field key. Leading and trailing whitespace is trimmed. Use
            letters, numbers, or underscores, including Unicode letters.
        label:
          type: string
          description: Display name; leading and trailing whitespace is trimmed.
      required:
        - objectType
        - key
        - label
    RelationshipFieldReference:
      type: object
      properties:
        key:
          type: string
        objectType:
          type: string
          enum:
            - CONTACT
            - COMPANY
            - OPPORTUNITY
            - CAMPAIGN
            - CAMPAIGN_MEMBER
            - CUSTOM_OBJECT
        customObjectId:
          type: string
          format: uuid
      required:
        - key
        - objectType
    Error:
      type: object
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: A machine-readable error code.
              examples:
                - invalid_email
            message:
              type: string
              description: A human-readable error description.
              examples:
                - 'invalid email format: not-an-email'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your Conversion API key. Found in **Settings > Integrations** in the
        dashboard. Format: `sk_live_<key_id>_<secret>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.