Create a relation (scope relations:write). Runs the advisory duplicate check; send confirmDuplicates=true to create anyway after reviewing matches (BLI-1408).

POST/api/v1/relations

Authorization

AuthorizationBearer token · headerrequired

Scoped API token (bnx_…). Required scopes are noted per operation.

Request body

application/json

kindstringrequired

Allowed:companycontactindividualemployeecourtprosecutor

departmentIdstringrequired

min length 1

companyRelationIdstring

companyNamestring

firstNamestring

lastNamestring

emailstring

phonestring

kvkNumberstring

confirmDuplicatesboolean

Responses

201

Created resource

idstringrequired

kindstringrequired

systemKindstring | nullrequired

systemCodestring | nullrequired

companyNamestring | nullrequired

firstNamestring | nullrequired

lastNamestring | nullrequired

emailstring | nullrequired

phonestring | nullrequired

departmentIdstring | nullrequired

accessLevelIdstring | nullrequired

activebooleanrequired

createdAtstringrequired

updatedAtstringrequired

400

Invalid request

errorstringrequired

codestringrequired

rulestring

401

Unauthenticated

errorstringrequired

codestringrequired

rulestring

403

Forbidden (missing scope or permission)

errorstringrequired

codestringrequired

rulestring

409

Duplicate relation matches found; resubmit with confirmDuplicates=true to create anyway

duplicatesobject[]required

min items 1

Show properties

Array of object

idstringrequired

labelstring

reasonstringrequired

Allowed:kvkemailname_birthdaycompany_name

scorenumberrequired

429

Rate limited

errorstringrequired

codestringrequired

rulestring

Request

curl -X POST '/api/v1/relations' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "company",
  "departmentId": "string",
  "companyRelationId": "string",
  "companyName": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phone": "string",
  "kvkNumber": "string",
  "confirmDuplicates": true
}'

const response = await fetch("/api/v1/relations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"kind\": \"company\",\n  \"departmentId\": \"string\",\n  \"companyRelationId\": \"string\",\n  \"companyName\": \"string\",\n  \"firstName\": \"string\",\n  \"lastName\": \"string\",\n  \"email\": \"string\",\n  \"phone\": \"string\",\n  \"kvkNumber\": \"string\",\n  \"confirmDuplicates\": true\n}"
});

import requests

response = requests.post(
    "/api/v1/relations",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"kind\": \"company\",\n  \"departmentId\": \"string\",\n  \"companyRelationId\": \"string\",\n  \"companyName\": \"string\",\n  \"firstName\": \"string\",\n  \"lastName\": \"string\",\n  \"email\": \"string\",\n  \"phone\": \"string\",\n  \"kvkNumber\": \"string\",\n  \"confirmDuplicates\": true\n}",
)

Response

{
  "id": "string",
  "kind": "string",
  "systemKind": "string",
  "systemCode": "string",
  "companyName": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phone": "string",
  "departmentId": "string",
  "accessLevelId": "string",
  "active": true,
  "createdAt": "string",
  "updatedAt": "string"
}

{
  "error": "string",
  "code": "string",
  "rule": "string"
}

{
  "error": "string",
  "code": "string",
  "rule": "string"
}

{
  "error": "string",
  "code": "string",
  "rule": "string"
}

{
  "duplicates": [
    {
      "id": "string",
      "label": "string",
      "reason": "kvk",
      "score": 0
    }
  ]
}

{
  "error": "string",
  "code": "string",
  "rule": "string"
}