Creates a new deal external reference with attributes, relationships or both

POST/jsonapi/deal-external-references

Requires integration and deal relationships. Each deal can have one reference per integration; external values are not a general idempotency guarantee. See the external integrations and references guide.

For client-credentials integrations, supply your assigned adviser identifier in the UserId header. See request headers and data access.

Access

Bearer authentication. Confirm your scopes, data access and required adviser context.

Request parameters

No parameters are defined for this operation in the source contract. Authentication and applicable request headers still apply.

Request body

application/vnd.api+json

Example request body

Illustrative request using reviewed sample values. Replace sample values, resource types and IDs with your own. Optional fields are shown for illustration; follow the field descriptions and business rules.

{
  "data": {
    "type": "deal-external-references",
    "attributes": {
      "externalReference": "OPP-2026-0042"
    },
    "relationships": {
      "integration": {
        "data": {
          "type": "integrations",
          "id": "42"
        }
      },
      "deal": {
        "data": {
          "type": "deals",
          "id": "3001"
        }
      }
    }
  }
}

Request documentobjectDealExternalReferenceDocument ↗

dataobjectrequiredDealExternalReference ↗

Example request

Use your supplied API base URL and replace path placeholders such as {id}. These examples run in your backend or terminal, where your credentials are kept.

curl --globoff --request POST "${API_BASE_URL}/jsonapi/deal-external-references" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "UserId: $ADVISER_CONTACT_ID" \
  --header 'Accept: application/vnd.api+json' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
  "data": {
    "type": "deal-external-references",
    "attributes": {
      "externalReference": "OPP-2026-0042"
    },
    "relationships": {
      "integration": {
        "data": {
          "type": "integrations",
          "id": "42"
        }
      },
      "deal": {
        "data": {
          "type": "deals",
          "id": "3001"
        }
      }
    }
  }
}'

Responses

201 response

Response headers

Location — Location of newly created resource

application/vnd.api+json

201 responseobjectDealExternalReferenceDocument ↗

metaobjectread only

jsonApiobjectread only

linksall ofread only

dataobjectrequiredDealExternalReference ↗

includedarray · nullableread only

For guidance beyond this operation's schema, see troubleshooting and JSON:API explained.