Legal Entity v4.1

Overview

The Legal Entity API allows you to manage legal entity profiles within your company. Legal entities represent the distinct legal organizations or subsidiaries that operate within your company structure. This API is part of the Identity v4.1 APIs and follows SCIM (System for Cross-domain Identity Management) standards.

Limitations

Access to this documentation does not provide access to the API.

Products and Editions

  • Concur Expense Professional Edition
  • Concur Expense Standard Edition
  • Concur Travel Professional Edition
  • Concur Travel Standard Edition
  • Concur Invoice Professional Edition
  • Concur Invoice Standard Edition
  • Concur Request Professional Edition
  • Concur Request Standard Edition

Authentication

All Legal Entity API endpoints require authentication using an API key passed in the Authorization header:

Authorization: Bearer {access_token}

Scope Usage

Name Description Endpoint
company.legalentity.read View legal entity details and search legal entities GET /LegalEntities/{id}, POST /LegalEntities/.search
company.legalentity.writeonly Create, replace, and update legal entities POST /LegalEntities, PUT /LegalEntities/{id}, PATCH /LegalEntities/{id}

Company ID Context

Most Legal Entity endpoints require a Company ID to be provided through one of the following methods (in order of precedence):

  1. JWT token (if your token includes company context)
  2. Query parameter companyId
  3. Request body (for POST operations only)

If you’re using a JWT with company context, the companyId query parameter is optional. Otherwise, it must be explicitly provided.

Endpoints

POST /LegalEntities

Create a new Legal Entity Profile within a Company Resource.

Scopes

company.legalentity.writeonly - Refer to Scope Usage for full details.

Payloads

Query Parameters

Name Type Format Description
companyId string - Company’s UUID. Required unless provided in JWT or request body.

Request Body

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:LegalEntity"],
  "companyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Acme Corporation EMEA",
  "referenceId": "ACME-EMEA",
  "active": true,
  "registeringOrganization": "Companies House UK",
  "taxId": "GB999999999",
  "email": "legal@acme-emea.com",
  "phone": "+44-20-1234-5678",
  "address": {
    "streetAddress": "123 Business Street",
    "locality": "London",
    "region": "Greater London",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  }
}

Required Fields

  • companyId (string) - The company UUID
  • active (boolean) - Whether the legal entity is active
  • id (string) - Unique identifier (auto-generated on creation)

Optional Fields

  • name (string, max 255 chars) - Name of the legal entity
  • referenceId (string, max 255 chars) - A unique reference identifier for the legal entity
  • registeringOrganization (string, max 255 chars) - The registering organization
  • taxId (string, max 18 chars) - Tax identification number
  • email (string, max 255 chars) - Contact email address
  • phone (string, max 255 chars) - Contact phone number
  • address (object) - Physical address of the legal entity

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:LegalEntity"],
  "id": "le-550e8400-e29b-41d4-a716-446655440000",
  "companyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Acme Corporation EMEA",
  "referenceId": "ACME-EMEA",
  "active": true,
  "registeringOrganization": "Companies House UK",
  "taxId": "GB999999999",
  "email": "legal@acme-emea.com",
  "phone": "+44-20-1234-5678",
  "address": {
    "streetAddress": "123 Business Street",
    "locality": "London",
    "region": "Greater London",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  },
  "meta": {
    "resourceType": "LegalEntity",
    "created": "2026-05-06T19:45:00Z",
    "lastModified": "2026-05-06T19:45:00Z",
    "location": "https://us.api.concursolutions.com/profile/identity/v4.1/LegalEntities/le-550e8400-e29b-41d4-a716-446655440000",
    "version": 1
  }
}

GET /LegalEntities/{id}

Retrieve a specific Legal Entity Profile by its unique identifier.

Scopes

company.legalentity.read - Refer to Scope Usage for full details.

Payloads

Parameters

Name Type Format Description
id string - Required Legal entity’s UUID.
companyId string - Company’s UUID. Required unless provided in JWT.

Example

GET /profile/identity/v4.1/LegalEntities/le-550e8400-e29b-41d4-a716-446655440000?companyId=a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer {access_token}
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

Returns the Legal Entity resource (same structure as Create response above).

PATCH /LegalEntities/{id}

Update an existing Legal Entity Profile using SCIM PATCH operations. This allows partial updates to specific fields.

Scopes

company.legalentity.writeonly - Refer to Scope Usage for full details.

Payloads

Parameters

Name Type Format Description
id string - Required Legal entity’s UUID.
companyId string - Company’s UUID. Required unless provided in JWT.

Request Body

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "phone",
      "value": "+44-20-9876-5432"
    },
    {
      "op": "replace",
      "path": "address.streetAddress",
      "value": "456 New Business Park"
    }
  ]
}

Supported Operations

Name Description
replace Update an existing field.
add Add a new field or value.
remove Remove a field. 
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": false
    }
  ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

Returns the updated Legal Entity resource.

PUT /LegalEntities/{id}

Replace an existing Legal Entity Profile entirely. Unlike PATCH, this replaces the entire resource.

Warning: PUT operations overwrite the entire legal entity. Use PATCH for partial updates.

Scopes

company.legalentity.writeonly - Refer to Scope Usage for full details.

Payloads

Parameters

Name Type Format Description
id string - Required Legal entity’s UUID.
companyId string - Company’s UUID. Required unless provided in JWT.

Request Body

Provide the complete Legal Entity object (same structure as POST request).

Response

HTTP/1.1 200 OK
Content-Type: application/json

Returns the replaced Legal Entity resource.

POST /LegalEntities/.search

Retrieve all matching legal entity profiles using SCIM search filters.

Scopes

company.legalentity.read - Refer to Scope Usage for full details.

Payloads

Parameters

Name Type Format Description
companyId string - Company’s UUID. Required unless provided in JWT.

Request Body

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
  "filter": "active eq true",
  "count": 50,
  "cursor": ""
}

Search Parameters

Name Type Description
filter string SCIM filter expression to narrow results.
attributes array List of attributes to return (overrides default).
excludedAttributes array List of attributes to exclude from response.
count integer Maximum number of results per page (default varies).
cursor string Pagination cursor from previous response.

Filter Examples

Get all active legal entities:

{
  "filter": "active eq true"
}

Get legal entities by country:

{
  "filter": "address.country eq \"GB\""
}

Get legal entities by reference ID:

{
  "filter": "referenceId eq \"ACME-EMEA\""
}

Get legal entities by name (partial match):

{
  "filter": "name co \"Acme\""
}

SCIM Filter Operators

Name Description Example
eq Equal active eq true
ne Not equal active ne false
co Contains name co "Corporation"
sw Starts with referenceId sw "ACME"
ew Ends with referenceId ew "EMEA"
pr Present (not null) taxId pr
gt Greater than N/A for legal entities
ge Greater than or equal N/A for legal entities
lt Less than N/A for legal entities
le Less than or equal N/A for legal entities

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 3,
  "itemsPerPage": 50,
  "startIndex": 1,
  "Resources": [
    {
      "id": "le-550e8400-e29b-41d4-a716-446655440000",
      "companyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Acme Corporation EMEA",
      "referenceId": "ACME-EMEA",
      "active": true,
      "taxId": "GB999999999",
      "meta": {
        "created": "2026-05-06T19:45:00Z",
        "lastModified": "2026-05-06T19:45:00Z",
        "version": 1
      }
    },
    {
      "id": "le-660e8400-e29b-41d4-a716-446655440001",
      "companyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Acme Corporation APAC",
      "referenceId": "ACME-APAC",
      "active": true,
      "taxId": "SG123456789",
      "meta": {
        "created": "2026-04-15T10:30:00Z",
        "lastModified": "2026-04-15T10:30:00Z",
        "version": 1
      }
    }
  ],
  "nextCursor": "eyJpZCI6ImxlLTY2MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMSJ9"
}

Pagination

Use the nextCursor value from the response in your next request to retrieve the next page:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
  "filter": "active eq true",
  "count": 50,
  "cursor": "eyJpZCI6ImxlLTY2MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMSJ9"
}

Schema

Name Type Format Description
id string UUID Required Unique identifier. Auto-generated on creation.
companyId string UUID Required The company this legal entity belongs to.
active boolean - Required Whether the legal entity is active.
name string - Name of the legal entity. Max 255 characters.
referenceId string - Unique reference identifier for the legal entity. Max 255 characters.
registeringOrganization string - Organization that issued registration. Max 255 characters.
taxId string - Tax identification number. Max 18 characters.
email string - Contact email address. Max 255 characters.
phone string - Contact phone number. Max 255 characters.
address object Address Physical address of the legal entity.
meta object Meta Read-only resource metadata.

Address

Name Type Format Description
streetAddress string - Full street address. May include newlines.
locality string - City or locality. Max 30 characters.
region string - State, province, or region. Max 30 characters.
postalCode string - ZIP or postal code. Max 20 characters.
country string - Two-letter country code (ISO 3166-1 alpha-2).

Meta

Name Type Format Description
resourceType string - Always LegalEntity. Read-only.
created string dateTime ISO 8601 timestamp of creation. Read-only.
lastModified string dateTime ISO 8601 timestamp of last update. Read-only.
location string URL Full URL to this resource. Read-only.
version integer - Number of times the resource has been modified. Read-only.

Error

Name Type Format Description
status string - Required HTTP status code.
scimType string - Required Machine readable error type. See SCIM Error Types.
detail string - Required Human-readable error description.
urn:ietf:params:scim:api:messages:concur:2.0:Error object - Concur-specific error extension.

SCIM Error Types

Name Description
invalidValue A required field is missing or a field has an invalid value.
tooMany Too many results would be returned.
uniqueness A unique constraint was violated.
mutability Attempted to modify a read-only field.
invalidSyntax Request body is not valid JSON or SCIM format.
invalidFilter The filter syntax is invalid.

Error Example

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "status": "400",
  "scimType": "invalidValue",
  "detail": "The request is invalid",
  "urn:ietf:params:scim:api:messages:concur:2.0:Error": {
    "messages": [
      {
        "code": "INVALID_FIELD",
        "type": "error",
        "message": "taxId exceeds maximum length of 18 characters",
        "schemaPath": "taxId"
      }
    ]
  }
}

Use Cases

Use Case 1: Multi-Entity Corporate Structure

Scenario: A global company operates through multiple legal entities across different countries.

Solution: Create separate legal entity profiles for each subsidiary:

POST /LegalEntities

{
  "companyId": "parent-company-uuid",
  "name": "Acme UK Limited",
  "referenceId": "ACME-UK",
  "active": true,
  "taxId": "GB999999999",
  "address": { "country": "GB" }
}

POST /LegalEntities

{
  "companyId": "parent-company-uuid",
  "name": "Acme Singapore Pte Ltd",
  "referenceId": "ACME-SG",
  "active": true,
  "taxId": "SG123456789",
  "address": { "country": "SG" }
}

Scenario: Assign employees to their respective legal entities for compliance and reporting.

Solution: Reference the legal entity in the User’s enterprise extension:

PATCH /Users/{userId}

{
  "Operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:legalEntity",
      "value": "le-550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

Scenario: Generate expense reports grouped by legal entity.

Solution: Use the search endpoint to find all active legal entities, then query users by legal entity:

POST /LegalEntities/.search

{
  "filter": "active eq true"
}

POST /Users/.search

{
  "filter": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:legalEntity eq \"le-550e8400-e29b-41d4-a716-446655440000\""
}

Use Case 4: Merger & Acquisition - Deactivate Legal Entity

Scenario: A subsidiary is sold or merged, and its legal entity needs to be deactivated.

Solution: Update the legal entity status to inactive:

PATCH /LegalEntities/{id}

{
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": false
    }
  ]
}

On this page