# Legal Entities ## Retrieving all legal entities > Retrieves all legal entities. You can filter, sort and paginate the results with query parameters.\ > \ > \* If the \`customermanagement.legalentity\_read\` scope is used, then all legal entities assigned to the tenant are returned. \ > \* If the \`customermanagement.legalentity\_read\_own\` scope is used, then all legal entities assigned to the customer are returned. ```json {"openapi":"3.0.0","info":{"title":"Customer Management Service","version":"0.0.1"},"tags":[{"name":"Legal Entities"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["customermanagement.legalentity_read","customermanagement.legalentity_read_own"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"customermanagement.legalentity_read":"Needed to read legal entities.","customermanagement.legalentity_read_own":"Needed to read legal entities by customer.","customermanagement.legalentity_manage":"Needed to manage legal entities.","customermanagement.contactassignment_read":"Needed to read contact assignments.","customermanagement.contactassignment_manage":"Needed to manage contact assignments.","customermanagement.location_read":"Needed to read locations.","customermanagement.location_manage":"Needed to manage locations."}}}}},"parameters":{"trait_paged_pageNumber":{"name":"pageNumber","in":"query","description":"The page number to be retrieved where the size of the pages must be specified by the pageSize parameter.\nThe number of the first page is 1.\n","schema":{"default":1,"minimum":1,"type":"integer"}},"trait_paged_pageSize":{"name":"pageSize","in":"query","description":"The number of documents being retrieved on the page.\n","schema":{"default":16,"minimum":1,"type":"integer"}},"trait_XTotalCount_header":{"in":"header","name":"X-Total-Count","required":false,"description":"In order to get information how many entities meet a filter requirements, X-Total-Count header has been introduced. The header is optional and its default value is false. It the header is provided and it is true then total count is returned in the X-Total-Count response header. In both cases (X-Total-Count true, false or not provided), the response body has the same format (array of entities). In other words, the information about total count is returned on demand, depending of an existence of X-Total-Count header in a request. Therefore, the X-Total-Count header is not returned if an API consumer didn't ask for it.","schema":{"default":false,"type":"boolean"}},"trait_sort":{"in":"query","name":"sort","required":false,"description":"Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case.","schema":{"type":"string"}},"trait_q_param":{"in":"query","name":"q","required":false,"description":"Query param for filtering entities by specified type. Examples of query params which are supported:\n\n| Q Param | Description |\n|------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|\n| `name:\"Exact match\"` | find an entity with `name` field with `Exact match` value |\n| `name:~John` | find an entity with `name` field containing `John` value |\n| `locDescription.fr:\"Description traduction française 02\"` | find an entity with localized `locDescription` field with `Description traduction française 02` value in french language | \n| `primary:true` | find an entity with `primary` field with `true` value |\n| `metadata.createdAt:(>\"2019-01-06T10:29:30.602Z\" AND <\"2020-01-07T10:29:30.602Z\")` | find an entity with `metadata.createdAt` field with value between `2019-01-06T10:29:30.602Z` and `2020-01-07T10:29:30.602Z` |\n| `name:exists` | find an entity with existing `name` field |\n| `name:null` | find an entity with non-existing `name` field |\n| `name:missing` | find an entity with non-existing `name` field |\n| `name:\"John\" surname:~Smith` | find an entity with `name` exactly equals to `John` and surname containing `Smith` value |\n| `name:(\"John\",\"Jack\",\"James\")` | find an entity with `name` field with one of the following value: `John` or `Jack` or `James` |\n","schema":{"type":"string"}},"trait_fields":{"in":"query","name":"fields","required":false,"description":"Comma-separated list of fields to return in the response. If not specified, all fields are returned.","schema":{"type":"string"}},"trait_legalEntity_id_query_param":{"name":"id","in":"query","required":false,"schema":{"type":"string"},"description":"Legal entity id. When specified, only legal entity with the specified id will be returned.\n\n**Note**: When filtering the results with this field, the `equals` operator is used. The operator is case-insensitive.\n"},"trait_legalEntity_name_query_param":{"name":"name","in":"query","required":false,"schema":{"type":"string"},"description":"Legal entity name. When specified, only legal entities containing the specified name will be returned.\n\n**Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-insensitive.\n"},"trait_legalEntity_type_query_param":{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["COMPANY","SUBSIDIARY"]},"description":"Legal entity type. When specified, only legal entities with the specified type will be returned.\n\n**Note**: When filtering the results with this field, the `equals` operator is used.\n"},"trait_legalEntity_parentId_query_param":{"name":"parentId","in":"query","required":false,"schema":{"type":"string"},"description":"The id of the parent legal entity. When specified, only legal entities with the specified parent will be returned.\n\n**Note**: When filtering the results with this field, the `equals` operator is used.\n"},"trait_legalEntity_legalName_query_param":{"name":"legalInfo.legalName","in":"query","required":false,"schema":{"type":"string"},"description":"The legal name of the entity. When specified, only legal entities containing the specified name will be returned.\n\n**Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-insensitive.\n"},"trait_legalEntity_registrationDate_query_param":{"name":"legalInfo.registrationDate","in":"query","required":false,"schema":{"type":"string"},"description":"Legal entity registration date. When specified, only legal entities registered in the specified date will be returned.\n\n**Note**: When filtering the results with this field, the `equals` operator is used.\n"},"trait_legalEntity_taxRegistrationNumber_query_param":{"name":"legalInfo.taxRegistrationNumber","in":"query","required":false,"schema":{"type":"string"},"description":"Legal entity tax registration number. When specified, only legal entities with the specified tax registration number will be returned.\n\n**Note**: When filtering the results with this field, the `equals` operator is used.\n"},"trait_legalEntity_registrationAgency_query_param":{"name":"legalInfo.registrationAgency","in":"query","required":false,"schema":{"type":"string"},"description":"Legal entity registration agency. When specified, only legal entities containing the specified registration agency will be returned.\n\n**Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-insensitive.\n"},"trait_legalEntity_countryOfRegistration_query_param":{"name":"legalInfo.countryOfRegistration","in":"query","required":false,"schema":{"type":"string"},"description":"Legal entity registration country. When specified, only legal entities containing the specified registration country will be returned.\n\n**Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-insensitive.\n"},"trait_legalEntity_registrationId_query_param":{"name":"legalInfo.registrationId","in":"query","required":false,"schema":{"type":"string"},"description":"The id of the legal entity registration. When specified, only legal entities with the specified registration ID will be returned.\n\n**Note**: When filtering the results with this field, the `equals` operator is used.\n"}},"responses":{"GetLegalEntities":{"description":"The request was successful. A list of legal entities is returned.","headers":{"X-Total-Count":{"description":"'The total number of entities in the database matching the specified query criteria.\nReturned if request X-Total-Count header has been set to true.'","schema":{"type":"number"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/legalEntity"}}}}},"BadRequest_400":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"schemas":{"legalEntity":{"title":"Legal Entity","type":"object","properties":{"id":{"type":"string","description":"The legal entity unique identifier."},"name":{"type":"string","description":"The name of the legal entity."},"type":{"type":"string","enum":["COMPANY","SUBSIDIARY"],"description":"The type of the legal entity."},"parentId":{"type":"string","description":"The id of the parent legal entity."},"accountLimit":{"$ref":"#/components/schemas/accountLimit"},"legalInfo":{"$ref":"#/components/schemas/legalInfo"},"customerGroups":{"type":"array","description":"The list of customer groups assigned to the legal entity.","items":{"$ref":"#/components/schemas/customerGroup"}},"entitiesAddresses":{"type":"array","description":"The list of locations assigned to the legal entity.","items":{"$ref":"#/components/schemas/location"}},"approvalGroup":{"type":"array","description":"The list of customer assignment of the approval group of the legal entity.","items":{"$ref":"#/components/schemas/contactAssignmentWithoutExpandedLegalEntity"}},"restrictions":{"$ref":"#/components/schemas/restrictions"},"metadata":{"$ref":"#/components/schemas/metadata"},"mixins":{"type":"object","description":"Mixins request. A map where a key represent mixins set name and a value represent a map with key-value pairs.","additionalProperties":true}}},"accountLimit":{"title":"Account Limit additional information","type":"object","properties":{"currency":{"type":"string","description":"The account limit currency."},"value":{"type":"number","description":"The purchasing limit for account in the legal entity.","minimum":0}}},"legalInfo":{"title":"Legal Entity additional information","type":"object","properties":{"legalName":{"type":"string","description":"The legal name of the entity."},"registrationDate":{"type":"string","description":"The registration date of the legal entity in the ISO 8601 format, e.g. 2020-04-30T04:00:00.000Z."},"taxRegistrationNumber":{"type":"string","description":"The tax registration number of the legal entity."},"registrationAgency":{"type":"string","description":"The registration agency of the legal entity."},"countryOfRegistration":{"type":"string","description":"The country in which the legal entity has been registered. The country needs to be defined and active in the Country Service."},"registrationId":{"type":"string","description":"The unique identifier of the legal entity registration."}}},"customerGroup":{"title":"Customer group","type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the customer group."},"name":{"additionalProperties":{"type":"string"},"description":"Localized name of a customer group."},"role":{"type":"string","description":"The customer group role."}},"required":["id"]},"location":{"title":"Location","type":"object","properties":{"id":{"type":"string","description":"The location unique identifier."},"name":{"type":"string","description":"The name of the location"},"type":{"type":"string","enum":["HEADQUARTER","WAREHOUSE","OFFICE"],"description":"The type of the location."},"contactDetails":{"$ref":"#/components/schemas/contactDetails"},"metadata":{"$ref":"#/components/schemas/metadata"},"mixins":{"type":"object","description":"Mixins request. A map where a key represent mixins set name and a value represent a map with key-value pairs.","additionalProperties":true}}},"contactDetails":{"title":"Contact Details","type":"object","properties":{"emails":{"type":"array","items":{"type":"string"},"description":"The list of contact emails."},"phones":{"type":"array","items":{"type":"string"},"description":"The list of contact phone numbers."},"addressLine1":{"type":"string","description":"The first address line of the contact."},"addressLine2":{"type":"string","description":"The second address line of the contact."},"city":{"type":"string","description":"The city of the contact."},"state":{"type":"string","description":"The state of the contact."},"postcode":{"type":"string","description":"The post code of the contact."},"countryCode":{"type":"string","description":"The country code of the contact."},"tags":{"type":"array","items":{"type":"string"},"description":"Allows to tag the location."}}},"metadata":{"type":"object","allOf":[{"$ref":"#/components/schemas/metadataUpdate"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the document was created.","type":"string"},"modifiedAt":{"description":"Date and time when the document was last modified.","type":"string"}}}]},"metadataUpdate":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the document."},"mixins":{"type":"object","description":"Links to the mixin schemas. A map where the keys represent mixins set attributes and the values represent url to a schema for a particular set.","additionalProperties":true}}},"contactAssignmentWithoutExpandedLegalEntity":{"title":"Contact Assignment","type":"object","properties":{"id":{"type":"string","description":"The customer assignment unique identifier."},"legalEntity":{"type":"object","description":"Assigned legal entity.","properties":{"id":{"type":"string","description":"The legal entity unique identifier."}}},"customer":{"$ref":"#/components/schemas/customer"},"type":{"type":"string","enum":["PRIMARY","BILLING","LOGISTICS","CONTACT"],"description":"The type of the customer assignment."},"primary":{"type":"boolean","description":"Indicates whether the customer is primary."},"metadata":{"$ref":"#/components/schemas/metadata"}}},"customer":{"title":"Customer","properties":{"id":{"type":"string","description":"The customer unique identifier."},"name":{"type":"string","description":"The name of the customer."},"surname":{"type":"string","description":"The surname of the customer."},"email":{"type":"string","description":"The email of the customer."},"phone":{"type":"string","description":"The phone number of the customer."}}},"restrictions":{"title":"Restriction","type":"array","maximum":1,"nullable":true,"description":"List of restrictions which determine who can view or manage the Legal Entity.","items":{"type":"string","description":"Access control identifier that determines who can view or manage the Legal Entity.\n\n**Purpose**: Restricts Legal Entity visibility based on scope permissions. Only users/applications \nwith matching restrictions scopes can access Legal Entities with a specific restrictions value.\n\n**Access Control**:\n- *Reading*: Users can only query and view Legal Entities whose `restrictions` value matches one of their authorized restrictions.\n\n**Validation**: The value must exist in the tenant's configured list of valid restrictions.\n"}},"errorMessage":{"title":"Error","description":"Schema for API specified errors.","type":"object","properties":{"code":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"status":{"description":"Original HTTP error name.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"type":"string","description":"Id of the resource."},"details":{"description":"List of problems causing this error.","type":"array","items":{"description":"Details for specific error cause.","type":"string"}}},"required":["status","code"]}}},"paths":{"/customer-management/{tenant}/legal-entities":{"get":{"summary":"Retrieving all legal entities","description":"Retrieves all legal entities. You can filter, sort and paginate the results with query parameters.\n\n* If the `customermanagement.legalentity_read` scope is used, then all legal entities assigned to the tenant are returned. \n* If the `customermanagement.legalentity_read_own` scope is used, then all legal entities assigned to the customer are returned. ","parameters":[{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/trait_XTotalCount_header"},{"$ref":"#/components/parameters/trait_sort"},{"$ref":"#/components/parameters/trait_q_param"},{"$ref":"#/components/parameters/trait_fields"},{"$ref":"#/components/parameters/trait_legalEntity_id_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_name_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_type_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_parentId_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_legalName_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_registrationDate_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_taxRegistrationNumber_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_registrationAgency_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_countryOfRegistration_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_registrationId_query_param"}],"responses":{"200":{"$ref":"#/components/responses/GetLegalEntities"},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"GET-customer-mgmt-list-legal-entities","tags":["Legal Entities"]}}}} ``` ## Creating legal entity > Creates a new legal entity for the tenant. A legal entity represents a company or it's subsidiary in the system. ```json {"openapi":"3.0.0","info":{"title":"Customer Management Service","version":"0.0.1"},"tags":[{"name":"Legal Entities"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["customermanagement.legalentity_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"customermanagement.legalentity_read":"Needed to read legal entities.","customermanagement.legalentity_read_own":"Needed to read legal entities by customer.","customermanagement.legalentity_manage":"Needed to manage legal entities.","customermanagement.contactassignment_read":"Needed to read contact assignments.","customermanagement.contactassignment_manage":"Needed to manage contact assignments.","customermanagement.location_read":"Needed to read locations.","customermanagement.location_manage":"Needed to manage locations."}}}}},"schemas":{"legalEntityCreate":{"title":"Legal Entity create payload","type":"object","properties":{"id":{"type":"string","description":"Custom legal entity identifier. If not provided, it is automatically generated.","minLength":1,"maxLength":66,"pattern":"^[a-zA-Z0-9_-]$"},"name":{"type":"string","description":"The name of the legal entity."},"type":{"type":"string","enum":["COMPANY","SUBSIDIARY"],"description":"The type of the legal entity. Default value if not provided is: `COMPANY`"},"parentId":{"type":"string","description":"The id of the parent legal entity."},"accountLimit":{"$ref":"#/components/schemas/accountLimit"},"legalInfo":{"$ref":"#/components/schemas/legalInfo"},"customerGroups":{"type":"array","description":"The list of customer group IDs assigned to the legal entity.","items":{"$ref":"#/components/schemas/customerGroup"}},"entitiesAddresses":{"type":"array","description":"The list of location IDs assigned to the legal entity.","items":{"$ref":"#/components/schemas/resourceId"}},"approvalGroup":{"type":"array","description":"The list of customer assignment IDs of an approval group of the legal entity.","items":{"$ref":"#/components/schemas/resourceId"}},"restrictions":{"$ref":"#/components/schemas/restrictions"},"metadata":{"$ref":"#/components/schemas/metadata_create"},"mixins":{"type":"object","description":"Mixins request. A map where a key represent mixins set name and a value represent a map with key-value pairs.","additionalProperties":true}},"required":["name"]},"accountLimit":{"title":"Account Limit additional information","type":"object","properties":{"currency":{"type":"string","description":"The account limit currency."},"value":{"type":"number","description":"The purchasing limit for account in the legal entity.","minimum":0}}},"legalInfo":{"title":"Legal Entity additional information","type":"object","properties":{"legalName":{"type":"string","description":"The legal name of the entity."},"registrationDate":{"type":"string","description":"The registration date of the legal entity in the ISO 8601 format, e.g. 2020-04-30T04:00:00.000Z."},"taxRegistrationNumber":{"type":"string","description":"The tax registration number of the legal entity."},"registrationAgency":{"type":"string","description":"The registration agency of the legal entity."},"countryOfRegistration":{"type":"string","description":"The country in which the legal entity has been registered. The country needs to be defined and active in the Country Service."},"registrationId":{"type":"string","description":"The unique identifier of the legal entity registration."}}},"customerGroup":{"title":"Customer group","type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the customer group."},"name":{"additionalProperties":{"type":"string"},"description":"Localized name of a customer group."},"role":{"type":"string","description":"The customer group role."}},"required":["id"]},"resourceId":{"title":"Resource","type":"object","properties":{"id":{"type":"string","description":"Id of a resource."}}},"restrictions":{"title":"Restriction","type":"array","maximum":1,"nullable":true,"description":"List of restrictions which determine who can view or manage the Legal Entity.","items":{"type":"string","description":"Access control identifier that determines who can view or manage the Legal Entity.\n\n**Purpose**: Restricts Legal Entity visibility based on scope permissions. Only users/applications \nwith matching restrictions scopes can access Legal Entities with a specific restrictions value.\n\n**Access Control**:\n- *Reading*: Users can only query and view Legal Entities whose `restrictions` value matches one of their authorized restrictions.\n\n**Validation**: The value must exist in the tenant's configured list of valid restrictions.\n"}},"metadata_create":{"title":"metadata_create","type":"object","description":"Metadata request.","properties":{"mixins":{"type":"object","description":"Links to the mixin schemas. A map where the keys represent mixins set attributes and the values represent url to a schema for a particular set.","additionalProperties":true}}},"errorMessage":{"title":"Error","description":"Schema for API specified errors.","type":"object","properties":{"code":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"status":{"description":"Original HTTP error name.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"type":"string","description":"Id of the resource."},"details":{"description":"List of problems causing this error.","type":"array","items":{"description":"Details for specific error cause.","type":"string"}}},"required":["status","code"]}},"responses":{"BadRequest_400":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Conflict_409":{"description":"Given resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/customer-management/{tenant}/legal-entities":{"post":{"summary":"Creating legal entity","description":"Creates a new legal entity for the tenant. A legal entity represents a company or it's subsidiary in the system.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/legalEntityCreate"}}}},"responses":{"201":{"description":"The request was successful. The legal entity has been created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"409":{"$ref":"#/components/responses/Conflict_409"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"POST-customer-mgmt-create-legal-entity","tags":["Legal Entities"]}}}} ``` ## Searching with parameters for legal entities > Retrieves all legal entities that match provided criteria.\ > \ > If the \`customermanagement.legalentity\_read\` scope is used, then all legal entities assigned to the tenant are returned. \ > If the \`customermanagement.legalentity\_read\_own\` scope is used, then all legal entities assigned to the customer are returned. ```json {"openapi":"3.0.0","info":{"title":"Customer Management Service","version":"0.0.1"},"tags":[{"name":"Legal Entities"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["customermanagement.legalentity_read","customermanagement.legalentity_read_own"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"customermanagement.legalentity_read":"Needed to read legal entities.","customermanagement.legalentity_read_own":"Needed to read legal entities by customer.","customermanagement.legalentity_manage":"Needed to manage legal entities.","customermanagement.contactassignment_read":"Needed to read contact assignments.","customermanagement.contactassignment_manage":"Needed to manage contact assignments.","customermanagement.location_read":"Needed to read locations.","customermanagement.location_manage":"Needed to manage locations."}}}}},"parameters":{"trait_paged_pageNumber":{"name":"pageNumber","in":"query","description":"The page number to be retrieved where the size of the pages must be specified by the pageSize parameter.\nThe number of the first page is 1.\n","schema":{"default":1,"minimum":1,"type":"integer"}},"trait_paged_pageSize":{"name":"pageSize","in":"query","description":"The number of documents being retrieved on the page.\n","schema":{"default":16,"minimum":1,"type":"integer"}},"trait_XTotalCount_header":{"in":"header","name":"X-Total-Count","required":false,"description":"In order to get information how many entities meet a filter requirements, X-Total-Count header has been introduced. The header is optional and its default value is false. It the header is provided and it is true then total count is returned in the X-Total-Count response header. In both cases (X-Total-Count true, false or not provided), the response body has the same format (array of entities). In other words, the information about total count is returned on demand, depending of an existence of X-Total-Count header in a request. Therefore, the X-Total-Count header is not returned if an API consumer didn't ask for it.","schema":{"default":false,"type":"boolean"}},"trait_sort":{"in":"query","name":"sort","required":false,"description":"Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case.","schema":{"type":"string"}},"trait_fields":{"in":"query","name":"fields","required":false,"description":"Comma-separated list of fields to return in the response. If not specified, all fields are returned.","schema":{"type":"string"}},"trait_legalEntity_id_query_param":{"name":"id","in":"query","required":false,"schema":{"type":"string"},"description":"Legal entity id. When specified, only legal entity with the specified id will be returned.\n\n**Note**: When filtering the results with this field, the `equals` operator is used. The operator is case-insensitive.\n"},"trait_legalEntity_name_query_param":{"name":"name","in":"query","required":false,"schema":{"type":"string"},"description":"Legal entity name. When specified, only legal entities containing the specified name will be returned.\n\n**Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-insensitive.\n"},"trait_legalEntity_type_query_param":{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["COMPANY","SUBSIDIARY"]},"description":"Legal entity type. When specified, only legal entities with the specified type will be returned.\n\n**Note**: When filtering the results with this field, the `equals` operator is used.\n"},"trait_legalEntity_parentId_query_param":{"name":"parentId","in":"query","required":false,"schema":{"type":"string"},"description":"The id of the parent legal entity. When specified, only legal entities with the specified parent will be returned.\n\n**Note**: When filtering the results with this field, the `equals` operator is used.\n"},"trait_legalEntity_legalName_query_param":{"name":"legalInfo.legalName","in":"query","required":false,"schema":{"type":"string"},"description":"The legal name of the entity. When specified, only legal entities containing the specified name will be returned.\n\n**Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-insensitive.\n"},"trait_legalEntity_registrationDate_query_param":{"name":"legalInfo.registrationDate","in":"query","required":false,"schema":{"type":"string"},"description":"Legal entity registration date. When specified, only legal entities registered in the specified date will be returned.\n\n**Note**: When filtering the results with this field, the `equals` operator is used.\n"},"trait_legalEntity_taxRegistrationNumber_query_param":{"name":"legalInfo.taxRegistrationNumber","in":"query","required":false,"schema":{"type":"string"},"description":"Legal entity tax registration number. When specified, only legal entities with the specified tax registration number will be returned.\n\n**Note**: When filtering the results with this field, the `equals` operator is used.\n"},"trait_legalEntity_registrationAgency_query_param":{"name":"legalInfo.registrationAgency","in":"query","required":false,"schema":{"type":"string"},"description":"Legal entity registration agency. When specified, only legal entities containing the specified registration agency will be returned.\n\n**Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-insensitive.\n"},"trait_legalEntity_countryOfRegistration_query_param":{"name":"legalInfo.countryOfRegistration","in":"query","required":false,"schema":{"type":"string"},"description":"Legal entity registration country. When specified, only legal entities containing the specified registration country will be returned.\n\n**Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-insensitive.\n"},"trait_legalEntity_registrationId_query_param":{"name":"legalInfo.registrationId","in":"query","required":false,"schema":{"type":"string"},"description":"The id of the legal entity registration. When specified, only legal entities with the specified registration ID will be returned.\n\n**Note**: When filtering the results with this field, the `equals` operator is used.\n"}},"responses":{"GetLegalEntities":{"description":"The request was successful. A list of legal entities is returned.","headers":{"X-Total-Count":{"description":"'The total number of entities in the database matching the specified query criteria.\nReturned if request X-Total-Count header has been set to true.'","schema":{"type":"number"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/legalEntity"}}}}},"BadRequest_400":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"schemas":{"legalEntity":{"title":"Legal Entity","type":"object","properties":{"id":{"type":"string","description":"The legal entity unique identifier."},"name":{"type":"string","description":"The name of the legal entity."},"type":{"type":"string","enum":["COMPANY","SUBSIDIARY"],"description":"The type of the legal entity."},"parentId":{"type":"string","description":"The id of the parent legal entity."},"accountLimit":{"$ref":"#/components/schemas/accountLimit"},"legalInfo":{"$ref":"#/components/schemas/legalInfo"},"customerGroups":{"type":"array","description":"The list of customer groups assigned to the legal entity.","items":{"$ref":"#/components/schemas/customerGroup"}},"entitiesAddresses":{"type":"array","description":"The list of locations assigned to the legal entity.","items":{"$ref":"#/components/schemas/location"}},"approvalGroup":{"type":"array","description":"The list of customer assignment of the approval group of the legal entity.","items":{"$ref":"#/components/schemas/contactAssignmentWithoutExpandedLegalEntity"}},"restrictions":{"$ref":"#/components/schemas/restrictions"},"metadata":{"$ref":"#/components/schemas/metadata"},"mixins":{"type":"object","description":"Mixins request. A map where a key represent mixins set name and a value represent a map with key-value pairs.","additionalProperties":true}}},"accountLimit":{"title":"Account Limit additional information","type":"object","properties":{"currency":{"type":"string","description":"The account limit currency."},"value":{"type":"number","description":"The purchasing limit for account in the legal entity.","minimum":0}}},"legalInfo":{"title":"Legal Entity additional information","type":"object","properties":{"legalName":{"type":"string","description":"The legal name of the entity."},"registrationDate":{"type":"string","description":"The registration date of the legal entity in the ISO 8601 format, e.g. 2020-04-30T04:00:00.000Z."},"taxRegistrationNumber":{"type":"string","description":"The tax registration number of the legal entity."},"registrationAgency":{"type":"string","description":"The registration agency of the legal entity."},"countryOfRegistration":{"type":"string","description":"The country in which the legal entity has been registered. The country needs to be defined and active in the Country Service."},"registrationId":{"type":"string","description":"The unique identifier of the legal entity registration."}}},"customerGroup":{"title":"Customer group","type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the customer group."},"name":{"additionalProperties":{"type":"string"},"description":"Localized name of a customer group."},"role":{"type":"string","description":"The customer group role."}},"required":["id"]},"location":{"title":"Location","type":"object","properties":{"id":{"type":"string","description":"The location unique identifier."},"name":{"type":"string","description":"The name of the location"},"type":{"type":"string","enum":["HEADQUARTER","WAREHOUSE","OFFICE"],"description":"The type of the location."},"contactDetails":{"$ref":"#/components/schemas/contactDetails"},"metadata":{"$ref":"#/components/schemas/metadata"},"mixins":{"type":"object","description":"Mixins request. A map where a key represent mixins set name and a value represent a map with key-value pairs.","additionalProperties":true}}},"contactDetails":{"title":"Contact Details","type":"object","properties":{"emails":{"type":"array","items":{"type":"string"},"description":"The list of contact emails."},"phones":{"type":"array","items":{"type":"string"},"description":"The list of contact phone numbers."},"addressLine1":{"type":"string","description":"The first address line of the contact."},"addressLine2":{"type":"string","description":"The second address line of the contact."},"city":{"type":"string","description":"The city of the contact."},"state":{"type":"string","description":"The state of the contact."},"postcode":{"type":"string","description":"The post code of the contact."},"countryCode":{"type":"string","description":"The country code of the contact."},"tags":{"type":"array","items":{"type":"string"},"description":"Allows to tag the location."}}},"metadata":{"type":"object","allOf":[{"$ref":"#/components/schemas/metadataUpdate"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the document was created.","type":"string"},"modifiedAt":{"description":"Date and time when the document was last modified.","type":"string"}}}]},"metadataUpdate":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the document."},"mixins":{"type":"object","description":"Links to the mixin schemas. A map where the keys represent mixins set attributes and the values represent url to a schema for a particular set.","additionalProperties":true}}},"contactAssignmentWithoutExpandedLegalEntity":{"title":"Contact Assignment","type":"object","properties":{"id":{"type":"string","description":"The customer assignment unique identifier."},"legalEntity":{"type":"object","description":"Assigned legal entity.","properties":{"id":{"type":"string","description":"The legal entity unique identifier."}}},"customer":{"$ref":"#/components/schemas/customer"},"type":{"type":"string","enum":["PRIMARY","BILLING","LOGISTICS","CONTACT"],"description":"The type of the customer assignment."},"primary":{"type":"boolean","description":"Indicates whether the customer is primary."},"metadata":{"$ref":"#/components/schemas/metadata"}}},"customer":{"title":"Customer","properties":{"id":{"type":"string","description":"The customer unique identifier."},"name":{"type":"string","description":"The name of the customer."},"surname":{"type":"string","description":"The surname of the customer."},"email":{"type":"string","description":"The email of the customer."},"phone":{"type":"string","description":"The phone number of the customer."}}},"restrictions":{"title":"Restriction","type":"array","maximum":1,"nullable":true,"description":"List of restrictions which determine who can view or manage the Legal Entity.","items":{"type":"string","description":"Access control identifier that determines who can view or manage the Legal Entity.\n\n**Purpose**: Restricts Legal Entity visibility based on scope permissions. Only users/applications \nwith matching restrictions scopes can access Legal Entities with a specific restrictions value.\n\n**Access Control**:\n- *Reading*: Users can only query and view Legal Entities whose `restrictions` value matches one of their authorized restrictions.\n\n**Validation**: The value must exist in the tenant's configured list of valid restrictions.\n"}},"errorMessage":{"title":"Error","description":"Schema for API specified errors.","type":"object","properties":{"code":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"status":{"description":"Original HTTP error name.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"type":"string","description":"Id of the resource."},"details":{"description":"List of problems causing this error.","type":"array","items":{"description":"Details for specific error cause.","type":"string"}}},"required":["status","code"]}}},"paths":{"/customer-management/{tenant}/legal-entities/search":{"post":{"summary":"Searching with parameters for legal entities","description":"Retrieves all legal entities that match provided criteria.\n\nIf the `customermanagement.legalentity_read` scope is used, then all legal entities assigned to the tenant are returned. \nIf the `customermanagement.legalentity_read_own` scope is used, then all legal entities assigned to the customer are returned. ","parameters":[{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/trait_XTotalCount_header"},{"$ref":"#/components/parameters/trait_sort"},{"$ref":"#/components/parameters/trait_fields"},{"$ref":"#/components/parameters/trait_legalEntity_id_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_name_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_type_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_parentId_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_legalName_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_registrationDate_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_taxRegistrationNumber_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_registrationAgency_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_countryOfRegistration_query_param"},{"$ref":"#/components/parameters/trait_legalEntity_registrationId_query_param"}],"requestBody":{"content":{"application/json":{"schema":{"title":"qParam","type":"object","properties":{"q":{"type":"string","description":"Query param for filtering entities by specified type."}}}}}},"responses":{"200":{"$ref":"#/components/responses/GetLegalEntities"},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"POST-customer-mgmt-search-legal-entities","tags":["Legal Entities"]}}}} ``` ## Retrieving a legal entity > Retrieves a legal entity by the specified unique identifier. ```json {"openapi":"3.0.0","info":{"title":"Customer Management Service","version":"0.0.1"},"tags":[{"name":"Legal Entities"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["customermanagement.legalentity_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"customermanagement.legalentity_read":"Needed to read legal entities.","customermanagement.legalentity_read_own":"Needed to read legal entities by customer.","customermanagement.legalentity_manage":"Needed to manage legal entities.","customermanagement.contactassignment_read":"Needed to read contact assignments.","customermanagement.contactassignment_manage":"Needed to manage contact assignments.","customermanagement.location_read":"Needed to read locations.","customermanagement.location_manage":"Needed to manage locations."}}}}},"parameters":{"trait_fields":{"in":"query","name":"fields","required":false,"description":"Comma-separated list of fields to return in the response. If not specified, all fields are returned.","schema":{"type":"string"}}},"responses":{"GetLegalEntity":{"description":"The request was successful. The requested legal entity is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/legalEntity"}}}},"BadRequest_400":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"schemas":{"legalEntity":{"title":"Legal Entity","type":"object","properties":{"id":{"type":"string","description":"The legal entity unique identifier."},"name":{"type":"string","description":"The name of the legal entity."},"type":{"type":"string","enum":["COMPANY","SUBSIDIARY"],"description":"The type of the legal entity."},"parentId":{"type":"string","description":"The id of the parent legal entity."},"accountLimit":{"$ref":"#/components/schemas/accountLimit"},"legalInfo":{"$ref":"#/components/schemas/legalInfo"},"customerGroups":{"type":"array","description":"The list of customer groups assigned to the legal entity.","items":{"$ref":"#/components/schemas/customerGroup"}},"entitiesAddresses":{"type":"array","description":"The list of locations assigned to the legal entity.","items":{"$ref":"#/components/schemas/location"}},"approvalGroup":{"type":"array","description":"The list of customer assignment of the approval group of the legal entity.","items":{"$ref":"#/components/schemas/contactAssignmentWithoutExpandedLegalEntity"}},"restrictions":{"$ref":"#/components/schemas/restrictions"},"metadata":{"$ref":"#/components/schemas/metadata"},"mixins":{"type":"object","description":"Mixins request. A map where a key represent mixins set name and a value represent a map with key-value pairs.","additionalProperties":true}}},"accountLimit":{"title":"Account Limit additional information","type":"object","properties":{"currency":{"type":"string","description":"The account limit currency."},"value":{"type":"number","description":"The purchasing limit for account in the legal entity.","minimum":0}}},"legalInfo":{"title":"Legal Entity additional information","type":"object","properties":{"legalName":{"type":"string","description":"The legal name of the entity."},"registrationDate":{"type":"string","description":"The registration date of the legal entity in the ISO 8601 format, e.g. 2020-04-30T04:00:00.000Z."},"taxRegistrationNumber":{"type":"string","description":"The tax registration number of the legal entity."},"registrationAgency":{"type":"string","description":"The registration agency of the legal entity."},"countryOfRegistration":{"type":"string","description":"The country in which the legal entity has been registered. The country needs to be defined and active in the Country Service."},"registrationId":{"type":"string","description":"The unique identifier of the legal entity registration."}}},"customerGroup":{"title":"Customer group","type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the customer group."},"name":{"additionalProperties":{"type":"string"},"description":"Localized name of a customer group."},"role":{"type":"string","description":"The customer group role."}},"required":["id"]},"location":{"title":"Location","type":"object","properties":{"id":{"type":"string","description":"The location unique identifier."},"name":{"type":"string","description":"The name of the location"},"type":{"type":"string","enum":["HEADQUARTER","WAREHOUSE","OFFICE"],"description":"The type of the location."},"contactDetails":{"$ref":"#/components/schemas/contactDetails"},"metadata":{"$ref":"#/components/schemas/metadata"},"mixins":{"type":"object","description":"Mixins request. A map where a key represent mixins set name and a value represent a map with key-value pairs.","additionalProperties":true}}},"contactDetails":{"title":"Contact Details","type":"object","properties":{"emails":{"type":"array","items":{"type":"string"},"description":"The list of contact emails."},"phones":{"type":"array","items":{"type":"string"},"description":"The list of contact phone numbers."},"addressLine1":{"type":"string","description":"The first address line of the contact."},"addressLine2":{"type":"string","description":"The second address line of the contact."},"city":{"type":"string","description":"The city of the contact."},"state":{"type":"string","description":"The state of the contact."},"postcode":{"type":"string","description":"The post code of the contact."},"countryCode":{"type":"string","description":"The country code of the contact."},"tags":{"type":"array","items":{"type":"string"},"description":"Allows to tag the location."}}},"metadata":{"type":"object","allOf":[{"$ref":"#/components/schemas/metadataUpdate"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the document was created.","type":"string"},"modifiedAt":{"description":"Date and time when the document was last modified.","type":"string"}}}]},"metadataUpdate":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the document."},"mixins":{"type":"object","description":"Links to the mixin schemas. A map where the keys represent mixins set attributes and the values represent url to a schema for a particular set.","additionalProperties":true}}},"contactAssignmentWithoutExpandedLegalEntity":{"title":"Contact Assignment","type":"object","properties":{"id":{"type":"string","description":"The customer assignment unique identifier."},"legalEntity":{"type":"object","description":"Assigned legal entity.","properties":{"id":{"type":"string","description":"The legal entity unique identifier."}}},"customer":{"$ref":"#/components/schemas/customer"},"type":{"type":"string","enum":["PRIMARY","BILLING","LOGISTICS","CONTACT"],"description":"The type of the customer assignment."},"primary":{"type":"boolean","description":"Indicates whether the customer is primary."},"metadata":{"$ref":"#/components/schemas/metadata"}}},"customer":{"title":"Customer","properties":{"id":{"type":"string","description":"The customer unique identifier."},"name":{"type":"string","description":"The name of the customer."},"surname":{"type":"string","description":"The surname of the customer."},"email":{"type":"string","description":"The email of the customer."},"phone":{"type":"string","description":"The phone number of the customer."}}},"restrictions":{"title":"Restriction","type":"array","maximum":1,"nullable":true,"description":"List of restrictions which determine who can view or manage the Legal Entity.","items":{"type":"string","description":"Access control identifier that determines who can view or manage the Legal Entity.\n\n**Purpose**: Restricts Legal Entity visibility based on scope permissions. Only users/applications \nwith matching restrictions scopes can access Legal Entities with a specific restrictions value.\n\n**Access Control**:\n- *Reading*: Users can only query and view Legal Entities whose `restrictions` value matches one of their authorized restrictions.\n\n**Validation**: The value must exist in the tenant's configured list of valid restrictions.\n"}},"errorMessage":{"title":"Error","description":"Schema for API specified errors.","type":"object","properties":{"code":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"status":{"description":"Original HTTP error name.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"type":"string","description":"Id of the resource."},"details":{"description":"List of problems causing this error.","type":"array","items":{"description":"Details for specific error cause.","type":"string"}}},"required":["status","code"]}}},"paths":{"/customer-management/{tenant}/legal-entities/{legalEntityId}":{"get":{"summary":"Retrieving a legal entity","parameters":[{"$ref":"#/components/parameters/trait_fields"}],"description":"Retrieves a legal entity by the specified unique identifier.","responses":{"200":{"$ref":"#/components/responses/GetLegalEntity"},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"GET-customer-mgmt-retrieve-legal-entity","tags":["Legal Entities"]}}}} ``` ## Upserting a legal entity > Updates or creates a legal entity with given legal entity id. You can omit the \`metadata.version\`, but then optimistic locking is not enabled.\ > \ > \*\*Important\*\*: If automatically generated customer group is not present in customerGroups list, \ > this group will be removed from iam. ```json {"openapi":"3.0.0","info":{"title":"Customer Management Service","version":"0.0.1"},"tags":[{"name":"Legal Entities"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["customermanagement.legalentity_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"customermanagement.legalentity_read":"Needed to read legal entities.","customermanagement.legalentity_read_own":"Needed to read legal entities by customer.","customermanagement.legalentity_manage":"Needed to manage legal entities.","customermanagement.contactassignment_read":"Needed to read contact assignments.","customermanagement.contactassignment_manage":"Needed to manage contact assignments.","customermanagement.location_read":"Needed to read locations.","customermanagement.location_manage":"Needed to manage locations."}}}}},"schemas":{"legalEntityUpdate":{"title":"Legal Entity update payload","type":"object","properties":{"name":{"type":"string","description":"The name of the legal entity."},"type":{"type":"string","enum":["COMPANY","SUBSIDIARY"],"description":"The type of the legal entity."},"parentId":{"type":"string","description":"The id of the parent legal entity."},"accountLimit":{"$ref":"#/components/schemas/accountLimit"},"legalInfo":{"$ref":"#/components/schemas/legalInfo"},"customerGroups":{"type":"array","description":"The list of customer group IDs assigned to the legal entity.","items":{"$ref":"#/components/schemas/resourceId"}},"entitiesAddresses":{"type":"array","description":"The list of location IDs assigned to the legal entity.","items":{"$ref":"#/components/schemas/resourceId"}},"approvalGroup":{"type":"array","description":"The list of customer assignment IDs of an approval user group of the legal entity.","items":{"$ref":"#/components/schemas/resourceId"}},"restrictions":{"$ref":"#/components/schemas/restrictions"},"metadata":{"$ref":"#/components/schemas/metadataUpdate"},"mixins":{"type":"object","description":"Mixins request. A map where a key represent mixins set name and a value represent a map with key-value pairs.","additionalProperties":true}},"required":["name","type"]},"accountLimit":{"title":"Account Limit additional information","type":"object","properties":{"currency":{"type":"string","description":"The account limit currency."},"value":{"type":"number","description":"The purchasing limit for account in the legal entity.","minimum":0}}},"legalInfo":{"title":"Legal Entity additional information","type":"object","properties":{"legalName":{"type":"string","description":"The legal name of the entity."},"registrationDate":{"type":"string","description":"The registration date of the legal entity in the ISO 8601 format, e.g. 2020-04-30T04:00:00.000Z."},"taxRegistrationNumber":{"type":"string","description":"The tax registration number of the legal entity."},"registrationAgency":{"type":"string","description":"The registration agency of the legal entity."},"countryOfRegistration":{"type":"string","description":"The country in which the legal entity has been registered. The country needs to be defined and active in the Country Service."},"registrationId":{"type":"string","description":"The unique identifier of the legal entity registration."}}},"resourceId":{"title":"Resource","type":"object","properties":{"id":{"type":"string","description":"Id of a resource."}}},"restrictions":{"title":"Restriction","type":"array","maximum":1,"nullable":true,"description":"List of restrictions which determine who can view or manage the Legal Entity.","items":{"type":"string","description":"Access control identifier that determines who can view or manage the Legal Entity.\n\n**Purpose**: Restricts Legal Entity visibility based on scope permissions. Only users/applications \nwith matching restrictions scopes can access Legal Entities with a specific restrictions value.\n\n**Access Control**:\n- *Reading*: Users can only query and view Legal Entities whose `restrictions` value matches one of their authorized restrictions.\n\n**Validation**: The value must exist in the tenant's configured list of valid restrictions.\n"}},"metadataUpdate":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the document."},"mixins":{"type":"object","description":"Links to the mixin schemas. A map where the keys represent mixins set attributes and the values represent url to a schema for a particular set.","additionalProperties":true}}},"errorMessage":{"title":"Error","description":"Schema for API specified errors.","type":"object","properties":{"code":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"status":{"description":"Original HTTP error name.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"type":"string","description":"Id of the resource."},"details":{"description":"List of problems causing this error.","type":"array","items":{"description":"Details for specific error cause.","type":"string"}}},"required":["status","code"]}},"responses":{"BadRequest_400_Update":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Conflict_409":{"description":"Given resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/customer-management/{tenant}/legal-entities/{legalEntityId}":{"put":{"summary":"Upserting a legal entity","description":"Updates or creates a legal entity with given legal entity id. You can omit the `metadata.version`, but then optimistic locking is not enabled.\n\n **Important**: If automatically generated customer group is not present in customerGroups list, \nthis group will be removed from iam.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/legalEntityUpdate"}}}},"responses":{"201":{"description":"The request was successful. The legal entity has been created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}}}}},"204":{"description":"The legal entity has been updated successfully."},"400":{"$ref":"#/components/responses/BadRequest_400_Update"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"409":{"$ref":"#/components/responses/Conflict_409"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"PUT-customer-mgmt-update-legal-entity","tags":["Legal Entities"]}}}} ``` ## Delete a legal entity > Deletes a legal entity.\ > \ > \*\*Important\*\*: This operation causes removal of all other entities exclusively subordinated to the requested legal entity in an async way. ```json {"openapi":"3.0.0","info":{"title":"Customer Management Service","version":"0.0.1"},"tags":[{"name":"Legal Entities"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["customermanagement.legalentity_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"customermanagement.legalentity_read":"Needed to read legal entities.","customermanagement.legalentity_read_own":"Needed to read legal entities by customer.","customermanagement.legalentity_manage":"Needed to manage legal entities.","customermanagement.contactassignment_read":"Needed to read contact assignments.","customermanagement.contactassignment_manage":"Needed to manage contact assignments.","customermanagement.location_read":"Needed to read locations.","customermanagement.location_manage":"Needed to manage locations."}}}}},"responses":{"BadRequest_400_Update":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"schemas":{"errorMessage":{"title":"Error","description":"Schema for API specified errors.","type":"object","properties":{"code":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"status":{"description":"Original HTTP error name.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"type":"string","description":"Id of the resource."},"details":{"description":"List of problems causing this error.","type":"array","items":{"description":"Details for specific error cause.","type":"string"}}},"required":["status","code"]}}},"paths":{"/customer-management/{tenant}/legal-entities/{legalEntityId}":{"delete":{"summary":"Delete a legal entity","description":"Deletes a legal entity.\n\n**Important**: This operation causes removal of all other entities exclusively subordinated to the requested legal entity in an async way.","responses":{"204":{"description":"The legal entity has been deleted successfully."},"400":{"$ref":"#/components/responses/BadRequest_400_Update"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"DELETE-customer-mgmt-remove-legal-entity","tags":["Legal Entities"]}}}} ``` ## Retrieving a legal entity with parent hierarchy > Retrieves the provided legal entity and all its parent legal entities. ```json {"openapi":"3.0.0","info":{"title":"Customer Management Service","version":"0.0.1"},"tags":[{"name":"Legal Entities"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["customermanagement.legalentity_read","customermanagement.legalentity_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"customermanagement.legalentity_read":"Needed to read legal entities.","customermanagement.legalentity_read_own":"Needed to read legal entities by customer.","customermanagement.legalentity_manage":"Needed to manage legal entities.","customermanagement.contactassignment_read":"Needed to read contact assignments.","customermanagement.contactassignment_manage":"Needed to manage contact assignments.","customermanagement.location_read":"Needed to read locations.","customermanagement.location_manage":"Needed to manage locations."}}}}},"responses":{"GetParentHierarchy":{"description":"The request was successful. A list of legal entities is returned.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/legalEntity"}}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"schemas":{"legalEntity":{"title":"Legal Entity","type":"object","properties":{"id":{"type":"string","description":"The legal entity unique identifier."},"name":{"type":"string","description":"The name of the legal entity."},"type":{"type":"string","enum":["COMPANY","SUBSIDIARY"],"description":"The type of the legal entity."},"parentId":{"type":"string","description":"The id of the parent legal entity."},"accountLimit":{"$ref":"#/components/schemas/accountLimit"},"legalInfo":{"$ref":"#/components/schemas/legalInfo"},"customerGroups":{"type":"array","description":"The list of customer groups assigned to the legal entity.","items":{"$ref":"#/components/schemas/customerGroup"}},"entitiesAddresses":{"type":"array","description":"The list of locations assigned to the legal entity.","items":{"$ref":"#/components/schemas/location"}},"approvalGroup":{"type":"array","description":"The list of customer assignment of the approval group of the legal entity.","items":{"$ref":"#/components/schemas/contactAssignmentWithoutExpandedLegalEntity"}},"restrictions":{"$ref":"#/components/schemas/restrictions"},"metadata":{"$ref":"#/components/schemas/metadata"},"mixins":{"type":"object","description":"Mixins request. A map where a key represent mixins set name and a value represent a map with key-value pairs.","additionalProperties":true}}},"accountLimit":{"title":"Account Limit additional information","type":"object","properties":{"currency":{"type":"string","description":"The account limit currency."},"value":{"type":"number","description":"The purchasing limit for account in the legal entity.","minimum":0}}},"legalInfo":{"title":"Legal Entity additional information","type":"object","properties":{"legalName":{"type":"string","description":"The legal name of the entity."},"registrationDate":{"type":"string","description":"The registration date of the legal entity in the ISO 8601 format, e.g. 2020-04-30T04:00:00.000Z."},"taxRegistrationNumber":{"type":"string","description":"The tax registration number of the legal entity."},"registrationAgency":{"type":"string","description":"The registration agency of the legal entity."},"countryOfRegistration":{"type":"string","description":"The country in which the legal entity has been registered. The country needs to be defined and active in the Country Service."},"registrationId":{"type":"string","description":"The unique identifier of the legal entity registration."}}},"customerGroup":{"title":"Customer group","type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the customer group."},"name":{"additionalProperties":{"type":"string"},"description":"Localized name of a customer group."},"role":{"type":"string","description":"The customer group role."}},"required":["id"]},"location":{"title":"Location","type":"object","properties":{"id":{"type":"string","description":"The location unique identifier."},"name":{"type":"string","description":"The name of the location"},"type":{"type":"string","enum":["HEADQUARTER","WAREHOUSE","OFFICE"],"description":"The type of the location."},"contactDetails":{"$ref":"#/components/schemas/contactDetails"},"metadata":{"$ref":"#/components/schemas/metadata"},"mixins":{"type":"object","description":"Mixins request. A map where a key represent mixins set name and a value represent a map with key-value pairs.","additionalProperties":true}}},"contactDetails":{"title":"Contact Details","type":"object","properties":{"emails":{"type":"array","items":{"type":"string"},"description":"The list of contact emails."},"phones":{"type":"array","items":{"type":"string"},"description":"The list of contact phone numbers."},"addressLine1":{"type":"string","description":"The first address line of the contact."},"addressLine2":{"type":"string","description":"The second address line of the contact."},"city":{"type":"string","description":"The city of the contact."},"state":{"type":"string","description":"The state of the contact."},"postcode":{"type":"string","description":"The post code of the contact."},"countryCode":{"type":"string","description":"The country code of the contact."},"tags":{"type":"array","items":{"type":"string"},"description":"Allows to tag the location."}}},"metadata":{"type":"object","allOf":[{"$ref":"#/components/schemas/metadataUpdate"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the document was created.","type":"string"},"modifiedAt":{"description":"Date and time when the document was last modified.","type":"string"}}}]},"metadataUpdate":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the document."},"mixins":{"type":"object","description":"Links to the mixin schemas. A map where the keys represent mixins set attributes and the values represent url to a schema for a particular set.","additionalProperties":true}}},"contactAssignmentWithoutExpandedLegalEntity":{"title":"Contact Assignment","type":"object","properties":{"id":{"type":"string","description":"The customer assignment unique identifier."},"legalEntity":{"type":"object","description":"Assigned legal entity.","properties":{"id":{"type":"string","description":"The legal entity unique identifier."}}},"customer":{"$ref":"#/components/schemas/customer"},"type":{"type":"string","enum":["PRIMARY","BILLING","LOGISTICS","CONTACT"],"description":"The type of the customer assignment."},"primary":{"type":"boolean","description":"Indicates whether the customer is primary."},"metadata":{"$ref":"#/components/schemas/metadata"}}},"customer":{"title":"Customer","properties":{"id":{"type":"string","description":"The customer unique identifier."},"name":{"type":"string","description":"The name of the customer."},"surname":{"type":"string","description":"The surname of the customer."},"email":{"type":"string","description":"The email of the customer."},"phone":{"type":"string","description":"The phone number of the customer."}}},"restrictions":{"title":"Restriction","type":"array","maximum":1,"nullable":true,"description":"List of restrictions which determine who can view or manage the Legal Entity.","items":{"type":"string","description":"Access control identifier that determines who can view or manage the Legal Entity.\n\n**Purpose**: Restricts Legal Entity visibility based on scope permissions. Only users/applications \nwith matching restrictions scopes can access Legal Entities with a specific restrictions value.\n\n**Access Control**:\n- *Reading*: Users can only query and view Legal Entities whose `restrictions` value matches one of their authorized restrictions.\n\n**Validation**: The value must exist in the tenant's configured list of valid restrictions.\n"}},"errorMessage":{"title":"Error","description":"Schema for API specified errors.","type":"object","properties":{"code":{"minimum":100,"maximum":599,"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"status":{"description":"Original HTTP error name.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"type":"string","description":"Id of the resource."},"details":{"description":"List of problems causing this error.","type":"array","items":{"description":"Details for specific error cause.","type":"string"}}},"required":["status","code"]}}},"paths":{"/customer-management/{tenant}/legal-entities/{legalEntityId}/parent-hierarchy":{"get":{"summary":"Retrieving a legal entity with parent hierarchy","description":"Retrieves the provided legal entity and all its parent legal entities.","responses":{"200":{"$ref":"#/components/responses/GetParentHierarchy"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"GET-customer-mgmt-retrieve-legal-entity-parent-hierarchy","tags":["Legal Entities"]}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.emporix.io/api-references-1/readme/api-reference-14/legal-entities.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.