Legal Entities

Overview

Legal Entities endpoints manage legal entities, related links, and contacts.

Endpoint Summary

Method	Route	Purpose
GET	/v1/data/legal-entities	List legal entities
POST	/v1/data/legal-entities	Create legal entity
GET	/v1/data/legal-entities/{legalEntityId}	Get legal entity by ID
PUT	/v1/data/legal-entities/{legalEntityId}	Update legal entity
DELETE	/v1/data/legal-entities/{legalEntityId}	Delete legal entity
GET	/v1/data/legal-entities/{legalEntityId}/links	List links
POST	/v1/data/legal-entities/{legalEntityId}/links	Create links
DELETE	/v1/data/legal-entities/{legalEntityId}/links	Delete links
GET	/v1/data/legal-entities/{legalEntityId}/contacts	List contacts
POST	/v1/data/legal-entities/{legalEntityId}/contacts	Create contact
PUT	/v1/data/legal-entities/{legalEntityId}/contacts/{contactId}	Update contact
DELETE	/v1/data/legal-entities/{legalEntityId}/contacts/{contactId}	Delete contact

GET /v1/data/legal-entities

Return legal entities for the authenticated context.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Accept	Yes	application/json

Query Parameters

Parameter	Type	Required	Description
search_text	string	No	Search by name/text.
owner_id	string	No	Owner UUID (resolved from auth context if omitted).

Example Request

curl -X GET "{{BASE_URL}}/v1/data/legal-entities" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Accept: application/json"

Success Response (200)

{
  "success": true,
  "result": [
    {
      "id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
      "owner_id": "8e6b6409-b03a-4f4d-a0b0-05481cc2cf28",
      "name": "XPath Germany GmbH",
      "country_code": "DE",
      "region": "Berlin",
      "city": "Berlin",
      "address": "Friedrichstrasse 100",
      "tax_number": "DE123456789",
      "zip_code": "10117",
      "segments": [
        {
          "id": "7f2d6e6d-a4ad-4b58-abfe-bd8b918ebec2",
          "name": "EMEA"
        }
      ]
    }
  ]
}

POST /v1/data/legal-entities

Create a legal entity.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Content-Type	Yes	application/json
Accept	Yes	application/json

Request Body Fields

Field	Type	Required	Description
name	string	Yes	Legal entity name.
country_code	string	Yes	Country ISO code (max 3 chars).
region	string	No	Region/state.
city	string	No	City.
address	string	No	Address line.
tax_number	string	No	Tax number.
zip_code	string	No	Postal code.
segments	array<object>	No	Linked segment IDs.
segments[].id	string	No	Segment UUID.

Example Request

curl -X POST "{{BASE_URL}}/v1/data/legal-entities" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "XPath Germany GmbH",
    "country_code": "DE",
    "region": "Berlin",
    "city": "Berlin",
    "address": "Friedrichstrasse 100",
    "tax_number": "DE123456789",
    "zip_code": "10117",
    "segments": [{"id": "7f2d6e6d-a4ad-4b58-abfe-bd8b918ebec2"}]
  }'

Success Response (201)

{
  "success": true,
  "result": {
    "id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
    "owner_id": "8e6b6409-b03a-4f4d-a0b0-05481cc2cf28",
    "name": "XPath Germany GmbH",
    "country_code": "DE",
    "region": "Berlin",
    "city": "Berlin",
    "address": "Friedrichstrasse 100",
    "tax_number": "DE123456789",
    "zip_code": "10117",
    "segments": [
      {
        "id": "7f2d6e6d-a4ad-4b58-abfe-bd8b918ebec2",
        "name": "EMEA"
      }
    ]
  },
  "message": "Legal entity created successfully."
}

GET /v1/data/legal-entities/{legalEntityId}

Return one legal entity by ID.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Accept	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
legalEntityId	string	Yes	Legal entity UUID.

Example Request

curl -X GET "{{BASE_URL}}/v1/data/legal-entities/{{LEGAL_ENTITY_ID}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Accept: application/json"

Success Response (200)

{
  "success": true,
  "result": {
    "id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
    "owner_id": "8e6b6409-b03a-4f4d-a0b0-05481cc2cf28",
    "name": "XPath Germany GmbH",
    "country_code": "DE",
    "region": "Berlin",
    "city": "Berlin",
    "address": "Friedrichstrasse 100",
    "tax_number": "DE123456789",
    "zip_code": "10117",
    "segments": [
      {
        "id": "7f2d6e6d-a4ad-4b58-abfe-bd8b918ebec2",
        "name": "EMEA"
      }
    ]
  }
}

PUT /v1/data/legal-entities/{legalEntityId}

Update a legal entity.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Content-Type	Yes	application/json
Accept	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
legalEntityId	string	Yes	Legal entity UUID.

Request Body Fields

Field	Type	Required	Description
name	string	Yes	Legal entity name.
country_code	string	Yes	Country ISO code.
region	string	No	Region/state.
city	string	No	City.
address	string	No	Address line.
tax_number	string	No	Tax number.
zip_code	string	No	Postal code.
segments	array<object>	No	Linked segment IDs.
segments[].id	string	No	Segment UUID.

Example Request

curl -X PUT "{{BASE_URL}}/v1/data/legal-entities/{{LEGAL_ENTITY_ID}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "XPath Germany GmbH",
    "country_code": "DE",
    "city": "Munich",
    "address": "Leopoldstrasse 12"
  }'

Success Response (200)

{
  "success": true,
  "result": {
    "id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
    "owner_id": "8e6b6409-b03a-4f4d-a0b0-05481cc2cf28",
    "name": "XPath Germany GmbH",
    "country_code": "DE",
    "region": "Bavaria",
    "city": "Munich",
    "address": "Leopoldstrasse 12",
    "tax_number": "DE123456789",
    "zip_code": "80802",
    "segments": []
  },
  "message": "Legal entity updated successfully."
}

DELETE /v1/data/legal-entities/{legalEntityId}

Delete a legal entity.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Accept	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
legalEntityId	string	Yes	Legal entity UUID.

Example Request

curl -X DELETE "{{BASE_URL}}/v1/data/legal-entities/{{LEGAL_ENTITY_ID}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Accept: application/json"

Success Response (200)

{
  "success": true,
  "result": null,
  "message": "Legal entity deleted successfully."
}

GET /v1/data/legal-entities/{legalEntityId}/links

Return resource links for one legal entity.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Accept	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
legalEntityId	string	Yes	Legal entity UUID.

Query Parameters

Parameter	Type	Required	Description
resource_type	string	Yes	Linked resource type (for example user).

Example Request

curl -X GET "{{BASE_URL}}/v1/data/legal-entities/{{LEGAL_ENTITY_ID}}/links?resource_type=user" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Accept: application/json"

Success Response (200)

{
  "success": true,
  "result": [
    {
      "legal_entity_id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
      "resource_id": 501,
      "resource_type": "user",
      "resource": {
        "id": 501,
        "name": "Jane Doe",
        "email": "[email protected]"
      }
    }
  ]
}

POST /v1/data/legal-entities/{legalEntityId}/links

Create links from legal entity to resources.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Content-Type	Yes	application/json
Accept	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
legalEntityId	string	Yes	Legal entity UUID.

Request Body Fields

Field	Type	Required	Description
resource_type	string	Yes	Linked resource type.
resource_ids	array	Yes	Linked resource IDs.
resource_ids[]	string|number	Yes	One resource identifier.

Example Request

curl -X POST "{{BASE_URL}}/v1/data/legal-entities/{{LEGAL_ENTITY_ID}}/links" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "resource_type": "user",
    "resource_ids": [501, 502]
  }'

Success Response (201)

{
  "success": true,
  "result": [
    {
      "legal_entity_id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
      "resource_id": 501,
      "resource_type": "user",
      "resource": {
        "id": 501,
        "name": "Jane Doe",
        "email": "[email protected]"
      }
    },
    {
      "legal_entity_id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
      "resource_id": 502,
      "resource_type": "user",
      "resource": {
        "id": 502,
        "name": "John Doe",
        "email": "[email protected]"
      }
    }
  ]
}

DELETE /v1/data/legal-entities/{legalEntityId}/links

Delete links for one legal entity.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Content-Type	Yes	application/json
Accept	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
legalEntityId	string	Yes	Legal entity UUID.

Request Body Fields

Field	Type	Required	Description
resource_type	string	Yes	Linked resource type.
resource_ids	array	Yes	Linked resource IDs to remove.
resource_ids[]	string|number	Yes	One resource identifier.

Example Request

curl -X DELETE "{{BASE_URL}}/v1/data/legal-entities/{{LEGAL_ENTITY_ID}}/links" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "resource_type": "user",
    "resource_ids": [501]
  }'

Success Response (204)

{
  "success": true,
  "result": []
}

GET /v1/data/legal-entities/{legalEntityId}/contacts

Return paginated contacts for one legal entity.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Accept	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
legalEntityId	string	Yes	Legal entity UUID.

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number.
per_page	number	No	Items per page.

Example Request

curl -X GET "{{BASE_URL}}/v1/data/legal-entities/{{LEGAL_ENTITY_ID}}/contacts" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Accept: application/json"

Success Response (200)

{
  "success": true,
  "result": {
    "currentPage": 1,
    "perPage": 20,
    "lastPage": 1,
    "total": 1,
    "items": [
      {
        "id": 991,
        "label": "Primary",
        "name": "John Manager",
        "email": "[email protected]",
        "phone_prefix": "+49",
        "phone_number": "155001122",
        "is_primary": true,
        "is_emergency": false,
        "address": {
          "usage": "office",
          "country_code": "DE",
          "state": "Berlin",
          "city": "Berlin",
          "address": "Friedrichstrasse 100",
          "post_code": "10117"
        },
        "company_position": "HR Lead",
        "legal_entity_id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
        "legal_entity": {
          "id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
          "label": "XPath Germany GmbH"
        }
      }
    ],
    "filters": []
  }
}

POST /v1/data/legal-entities/{legalEntityId}/contacts

Create a contact for one legal entity.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Content-Type	Yes	application/json
Accept	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
legalEntityId	string	Yes	Legal entity UUID.

Request Body Fields

Field	Type	Required	Description
name	string	Yes	Contact name.
email	string	Conditional	Required if phone_number is missing.
phone_number	string	Conditional	Required if email is missing.
phone_prefix	string	No	Phone prefix.
is_primary	boolean	Yes	Primary contact flag.
is_emergency	boolean	Yes	Emergency contact flag.
label	string	No	Label value.
company_position	string	No	Company position.
user_id	number	No	Linked user ID.
address	object	No	Address object.
address.usage	string	No	Address usage.
address.country_code	string	Conditional	Required when address is sent.
address.state	string	Conditional	Required when address is sent.
address.city	string	Conditional	Required when address is sent.
address.address	string	Conditional	Required when address is sent.
address.post_code	string	Conditional	Required when address is sent.

Example Request

curl -X POST "{{BASE_URL}}/v1/data/legal-entities/{{LEGAL_ENTITY_ID}}/contacts" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "John Manager",
    "email": "[email protected]",
    "phone_prefix": "+49",
    "phone_number": "155001122",
    "is_primary": true,
    "is_emergency": false,
    "company_position": "HR Lead",
    "address": {
      "usage": "office",
      "country_code": "DE",
      "state": "Berlin",
      "city": "Berlin",
      "address": "Friedrichstrasse 100",
      "post_code": "10117"
    }
  }'

Success Response (200)

{
  "success": true,
  "result": {
    "contact": {
      "id": 991,
      "label": "Primary",
      "name": "John Manager",
      "email": "[email protected]",
      "phone_prefix": "+49",
      "phone_number": "155001122",
      "is_primary": true,
      "is_emergency": false,
      "address": {
        "usage": "office",
        "country_code": "DE",
        "state": "Berlin",
        "city": "Berlin",
        "address": "Friedrichstrasse 100",
        "post_code": "10117"
      },
      "company_position": "HR Lead",
      "legal_entity_id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
      "legal_entity": {
        "id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
        "label": "XPath Germany GmbH"
      }
    }
  }
}

PUT /v1/data/legal-entities/{legalEntityId}/contacts/{contactId}

Update a legal entity contact.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Content-Type	Yes	application/json
Accept	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
legalEntityId	string	Yes	Legal entity UUID.
contactId	number	Yes	Contact identifier.

Request Body Fields

Same fields as POST /contacts.

Example Request

curl -X PUT "{{BASE_URL}}/v1/data/legal-entities/{{LEGAL_ENTITY_ID}}/contacts/{{CONTACT_ID}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "John Manager",
    "email": "[email protected]",
    "phone_prefix": "+49",
    "phone_number": "155001122",
    "is_primary": true,
    "is_emergency": true
  }'

Success Response (200)

{
  "success": true,
  "result": {
    "contact": {
      "id": 991,
      "label": "Primary",
      "name": "John Manager",
      "email": "[email protected]",
      "phone_prefix": "+49",
      "phone_number": "155001122",
      "is_primary": true,
      "is_emergency": true,
      "address": null,
      "company_position": "HR Lead",
      "legal_entity_id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
      "legal_entity": {
        "id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
        "label": "XPath Germany GmbH"
      }
    }
  }
}

DELETE /v1/data/legal-entities/{legalEntityId}/contacts/{contactId}

Delete a contact.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Accept	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
legalEntityId	string	Yes	Legal entity UUID.
contactId	number	Yes	Contact identifier.

Example Request

curl -X DELETE "{{BASE_URL}}/v1/data/legal-entities/{{LEGAL_ENTITY_ID}}/contacts/{{CONTACT_ID}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Accept: application/json"

Success Response (200)

{
  "success": true,
  "result": {
    "contact": 991
  }
}