---
title: "Create Relationship Fields"
method: POST
path: "/v2/fields/relationships"
---

# Create Relationship Fields

`POST /v2/fields/relationships`

## Request

- Base URL: `https://pub-api.conversion.ai/api`
- URL: `https://pub-api.conversion.ai/api/v2/fields/relationships`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in query parameter `api_key`

Create a field on `source` that links each record to one `target` record, plus a read-only reverse field on `target` that lists those records. This doesn't link any records.

## Request body

- object
  - `source` RelationshipFieldSide, required
    - `objectType` 'CONTACT' | 'COMPANY' | 'OPPORTUNITY' | 'CAMPAIGN' | 'CAMPAIGN_MEMBER' | 'CUSTOM_OBJECT', required
    - `customObjectId` string, uuid: Required when objectType is CUSTOM_OBJECT; omit for standard objects.
    - `key` string, required: Required field key. Leading and trailing whitespace is trimmed. Use letters, numbers, or underscores, including Unicode letters.
    - `label` string, required: Display name; leading and trailing whitespace is trimmed.
  - `target` RelationshipFieldSide, required
    - `objectType` 'CONTACT' | 'COMPANY' | 'OPPORTUNITY' | 'CAMPAIGN' | 'CAMPAIGN_MEMBER' | 'CUSTOM_OBJECT', required
    - `customObjectId` string, uuid: Required when objectType is CUSTOM_OBJECT; omit for standard objects.
    - `key` string, required: Required field key. Leading and trailing whitespace is trimmed. Use letters, numbers, or underscores, including Unicode letters.
    - `label` string, required: Display name; leading and trailing whitespace is trimmed.

## Response `200`

Relationship fields created.

- object
  - `data` object
    - `sourceField` RelationshipFieldReference, required
      - `key` string, required
      - `objectType` 'CONTACT' | 'COMPANY' | 'OPPORTUNITY' | 'CAMPAIGN' | 'CAMPAIGN_MEMBER' | 'CUSTOM_OBJECT', required
      - `customObjectId` string, uuid
    - `relatedFields` RelationshipFieldReference[], required
      - `key` string, required
      - `objectType` 'CONTACT' | 'COMPANY' | 'OPPORTUNITY' | 'CAMPAIGN' | 'CAMPAIGN_MEMBER' | 'CUSTOM_OBJECT', required
      - `customObjectId` string, uuid

## Other responses

- `400`: Invalid request.
- `401`: Missing or invalid API key.
- `403`: The API key lacks permission, or custom objects are not enabled.
- `404`: Resource not found in this workspace.
- `500`: Unexpected service failure.

---

[API](https://skmtc.dev/conversion/apis/conversion-api.md) - [All operations](https://skmtc.dev/conversion/apis/conversion-api/llms.txt) - [OpenAPI document](https://skmtc.dev/conversion/apis/conversion-api/revisions/8422f815402a?raw)