POST Relationships

Create a new relationship.

Endpoint

Endpoint

/api/relationships

Method

POST

Scope

riskassess.relationship.write

Headers

HeaderArgument

Authorization

Bearer token

Accept

application/json or application/xml

Content-Type

application/json or application/xml

X-Correlation-Id

(Optional) Request tracing ID

Parameters

Table 1. Request body parameters
ParameterRequiredDescription

name

Yes

Max 500 characters.

startEffectiveDate

Yes

Date/time. Sent as JSON date/time; server accepts ISO-style forms (for example yyyy-MM-dd).

organizations

Yes

Array of organization GUIDs. At least one; no duplicates; each non-empty.

internalManager

Yes

User entityId.

externalManager

Yes

User entityId.

supplier

Yes

Supplier entityId (GUID). Required; must exist.

classification

Yes

Must match active tenant setup data. Max 200 characters.

category

Yes

Standard category setup value. Max 200 characters.

subCategory

No

(Optional) If present, category must be set; must match setup data.

parentRelationship

No

(Optional) Relationship entityId (GUID).

internalAccess

Yes

ManagerOnly, Team, or All (case-insensitive).

externalAccess

Yes

Same allowed values as internalAccess.

status

Yes

Relationship_Active, Relationship_Inactive, Relationship_Draft, or Relationship_Expired.

thirdPartyLocations

No

(Optional) Array of supplier address entityIds for the relationship's supplier; no duplicates.

extensionFields

No

(Optional) Object map of field name to string value (UDFs on the Relationship object). For more information, see Extension Fields (User-Defined Fields).

Create relationship

Endpoint

POST /api/relationships

Example cURL request
curl --location --request POST 'https://<your-instance>.risk.com/api/relationships' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ••••••' \
--data '{
  "name": "Example relationship",
  "startEffectiveDate": "2026-04-17",
  "organizations": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "internalManager": "a218d8e5-8c7a-4f3e-9b12-111111111111",
  "externalManager": "b218d8e5-8c7a-4f3e-9b12-222222222222",
  "supplier": "c218d8e5-8c7a-4f3e-9b12-333333333333",
  "classification": "classification1",
  "category": "Cat1",
  "internalAccess": "ManagerOnly",
  "externalAccess": "ManagerOnly",
  "status": "Relationship_Active",
  "extensionFields": {
    "MyTextBox": "Single line text",
    "MyDate": "2026-04-17"
  }
}'
Example success response
{
    "success": true,
    "result": {
        "entityId": "d32a9192-353c-45fe-bbd4-b88702800467",
        "links": [
            {
                "rel": "self",
                "href": "https://your-instance.risk.com/api/relationships/d32a9192-353c-45fe-bbd4-b88702800467",
                "method": "GET"
            },
            {
                "rel": "update-relationship",
                "href": "https://your-instance.risk.com/api/relationships/d32a9192-353c-45fe-bbd4-b88702800467",
                "method": "PUT"
            }
        ]
    },
    "errors": []
}
Example error response
{
    "success": false,
    "result": null,
    "errors": [
        {
            "message": "Validation failed",
            "errorCode": "InvalidRequest"
        }
    ]
}