Enterprise API Reference

Enterprise API v1

The Intercultural Teams Enterprise API provides machine-to-machine access to cultural profiles, team analysis, country intelligence, and user management. It is designed for HR platform integrations, custom portals, and workflow automation.

Base URL: https://interculturalteams.com/api/enterprise/v1

Authentication

All API requests require an API key generated in Admin > L&D Plugins > API Keys.

Required Header

X-Api-Key: your-api-key-here

Optional HMAC Signature

For additional security, sign request bodies with HMAC-SHA256 using your API secret:

X-Signature: hmac-sha256-hash-of-request-body

The signature is computed as: HMAC-SHA256(request_body, api_secret_hash)

For GET requests with no body, the signature is not required.

Rate Limiting

Each API key has a configurable rate limit (default: 60 requests/minute). When exceeded, the API returns:

{
  "error": "Rate limit exceeded",
  "retry_after": 45
}

Status code: 429 Too Many Requests

Scopes

API keys can optionally be scoped to specific endpoints. If scopes are configured, the key can only access endpoints matching its scopes.

Response Format

All successful responses follow this structure:

{
  "data": { ... },
  "message": "Optional human-readable message"
}

Error Responses

{
  "error": "Description of what went wrong"
}

Status Codes

Endpoints

Cultural Profiles

Get Cultural Profile

Retrieve a user's Hofstede cultural dimension profile.

GET /cultural-profile/{externalId}

Path parameters:

• externalId (string, required) — The employee's external ID from your HR platform

Response (200):

{
  "data": {
    "external_id": "EMP-12345",
    "dimensions": {
      "power_distance": 45,
      "individualism": 72,
      "masculinity": 58,
      "uncertainty_avoidance": 63,
      "long_term_orientation": 51,
      "indulgence": 68
    },
    "is_complete": true,
    "home_country": "Germany",
    "updated_at": "2026-03-15T10:30:00+00:00"
  }
}

Response (404): {"error": "User not found"} — Run user sync first.

Response (200, no profile):

{
  "data": null,
  "message": "No cultural profile exists for this user. They need to complete the cultural survey."
}

Save Cultural Profile

Create or update a cultural profile from survey answers.

POST /cultural-profile/{externalId}

Path parameters:

• externalId (string, required) — Employee external ID

Request body:

{
  "answers": {
    "q1": 4,
    "q2": 2,
    "q3": 5,
    "...": "minimum 30 answers required"
  },
  "home_country_slug": "germany"
}

Parameters:

• answers (object, required) — Survey question answers, minimum 30 entries
• home_country_slug (string, optional) — Slug of the user's home country (must exist in country briefs)

Response (201):

{
  "data": {
    "external_id": "EMP-12345",
    "dimensions": {
      "power_distance": 45,
      "individualism": 72,
      "masculinity": 58,
      "uncertainty_avoidance": 63,
      "long_term_orientation": 51,
      "indulgence": 68
    },
    "is_complete": true
  },
  "message": "Cultural profile saved successfully."
}

Delete Cultural Profile

Remove a user's cultural profile data.

DELETE /cultural-profile/{externalId}

Response (200):

{
  "message": "Cultural profile deleted successfully."
}

Team Analysis

Team Culture Comparison

Analyse cultural diversity within a team. Returns dimension averages, spread metrics, pairwise distances, and collaboration tips.

POST /team-culture-comparison

Request body:

{
  "member_ids": ["EMP-001", "EMP-002", "EMP-003", "EMP-004"],
  "include_country_baseline": true
}

Parameters:

• member_ids (array of strings, required) — External IDs of team members (min: 2, max: 50)
• include_country_baseline (boolean, optional, default: true) — Include home country averages for comparison

Response (200):

{
  "data": {
    "team_size": 4,
    "dimensions": {
      "power_distance": {
        "average": 52.3,
        "std_dev": 18.7,
        "min": 30,
        "max": 78,
        "range": 48
      }
    },
    "pairwise_distances": [
      {"pair": ["EMP-001", "EMP-002"], "distance": 32.5}
    ],
    "collaboration_tips": [
      "High spread in power_distance (range: 48) — clarify decision-making authority explicitly"
    ]
  }
}

Assignment Briefing

Generate a personalised cultural briefing for an international assignment.

POST /assignment-briefing

Request body:

{
  "employee_id": "EMP-12345",
  "destination_country": "japan",
  "assignment_type": "relocation",
  "role": "senior_manager"
}

Parameters:

• employee_id (string, required) — Employee external ID
• destination_country (string, required) — Destination country slug
• assignment_type (string, optional) — One of: relocation, short_term, business_trip, remote, general (default: general)
• role (string, optional) — Employee's role context (default: general)

Response (200):

{
  "data": {
    "employee_external_id": "EMP-12345",
    "destination": {
      "name": "Japan",
      "flag_emoji": "\ud83c\uddef\ud83c\uddf5",
      "dimensions": { ... }
    },
    "key_differences": [
      {
        "dimension": "power_distance",
        "employee_score": 35,
        "country_score": 54,
        "gap": 19,
        "insight": "Japan has a moderately hierarchical culture..."
      }
    ],
    "communication_tips": [ ... ],
    "business_etiquette": [ ... ],
    "suggested_learning": [ ... ]
  }
}

Country Intelligence

List Country Briefs

Retrieve all available country briefs with optional region filtering.

GET /country-briefs
GET /country-briefs?region=europe

Query parameters:

• region (string, optional) — Filter by region (e.g. europe, asia, americas)

Response (200):

{
  "data": [
    {
      "id": 1,
      "name": "Germany",
      "slug": "germany",
      "flag_emoji": "\ud83c\udde9\ud83c\uddea",
      "region": "europe",
      "hofstede_dimensions": {
        "power_distance": 35,
        "individualism": 67,
        "masculinity": 66,
        "uncertainty_avoidance": 65,
        "long_term_orientation": 83,
        "indulgence": 40
      }
    }
  ]
}

Get Country Brief

Retrieve detailed cultural information for a specific country.

GET /country-briefs/{slug}

Path parameters:

• slug (string, required) — Country slug (e.g. germany, japan, brazil)

Response (200):

{
  "data": {
    "name": "Japan",
    "slug": "japan",
    "flag_emoji": "\ud83c\uddef\ud83c\uddf5",
    "region": "asia",
    "dimensions": { ... },
    "sections": {
      "general_knowledge": "...",
      "communication_styles": "...",
      "business_practices": "..."
    },
    "sub_cultures": [ ... ]
  }
}

Interaction Tips

Get cross-cultural communication tips for a specific country pair.

GET /interaction-tips?source=DE&target=JP

Query parameters:

• source (string, required) — ISO 3166-1 alpha-2 country code of the source culture
• target (string, required) — ISO 3166-1 alpha-2 country code of the target culture

Response (200):

{
  "data": {
    "source_country": "DE",
    "target_country": "JP",
    "colleague_tips": [ ... ],
    "customer_tips": [ ... ]
  }
}

Response (200, no tips available):

{
  "data": null,
  "message": "No interaction tips available for this country pair."
}

Cultural Dimensions

Get Hofstede dimension scores for all countries in the database.

GET /cultural-dimensions

Response (200):

{
  "data": [
    {
      "code": "DE",
      "name": "Germany",
      "power_distance": 35,
      "individualism": 67,
      "masculinity": 66,
      "uncertainty_avoidance": 65,
      "long_term_orientation": 83,
      "indulgence": 40
    }
  ]
}

Learning Tools

Simulator Access

Generate a time-limited embed URL for the Cultural Scenarios.

POST /simulator-access

Request body:

{
  "external_user_id": "EMP-12345",
  "country": "japan"
}

Parameters:

• external_user_id (string, required) — Employee external ID
• country (string, required) — Country slug for the simulation

Response (200):

{
  "data": {
    "embed_url": "https://interculturalteams.com/tools/cultural-scenarios/japan?embed_token=abc123...",
    "expires_in": 3600
  }
}

The embed URL is valid for 1 hour and can be used in an iframe.

User Progress

Get a user's learning progress across Intercultural Teams.

GET /user-progress/{externalId}

Path parameters:

• externalId (string, required) — Employee external ID

Response (200):

{
  "data": {
    "cultural_profile": true,
    "courses_enrolled": 3,
    "courses_completed": 1
  }
}

User Management

Sync Users

Bulk create or update employee records. Maps external HR system IDs to Intercultural Teams user accounts.

POST /users/sync

Request body:

{
  "employees": [
    {
      "external_id": "EMP-12345",
      "email": "jane.doe@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "department": "Engineering",
      "location": "Berlin",
      "country_code": "DE",
      "manager_id": "EMP-00100",
      "job_profile": "Senior Software Engineer"
    }
  ]
}

Parameters (per employee):

• external_id (string, required) — Unique employee identifier in your HR system
• email (string, required) — Employee email address
• first_name (string, optional) — First name
• last_name (string, optional) — Last name
• department (string, optional) — Department name
• location (string, optional) — Office location
• country_code (string, optional) — ISO 3166-1 alpha-2 country code
• manager_id (string, optional) — Manager's external ID
• job_profile (string, optional) — Job title or profile

Limits: Maximum 500 employees per request.

Response (200):

{
  "data": {
    "created": 12,
    "updated": 38,
    "errors": [
      {
        "external_id": "EMP-99999",
        "error": "Invalid email format"
      }
    ]
  },
  "message": "Synced 12 new, 38 updated, 1 errors."
}

Platform Management

List Platforms

Get all active platforms with user mapping counts.

GET /platforms

Response (200):

{
  "data": [
    {
      "id": 1,
      "name": "Acme Corp Workday",
      "platform_type": "workday",
      "is_active": true,
      "user_mappings_count": 250
    }
  ]
}

Get Platform Details

Get detailed information about a specific platform.

GET /platforms/{id}

Path parameters:

• id (integer, required) — Platform ID

Response (200):

{
  "data": {
    "id": 1,
    "name": "Acme Corp Workday",
    "platform_type": "workday",
    "is_active": true,
    "ags_enabled": true,
    "nrps_enabled": false,
    "users_count": 250,
    "sessions_count": 1024,
    "deployments_count": 1
  }
}

Example: Complete Integration Flow

Here is a typical integration sequence:

1. Sync employees
   POST /users/sync  (body: {employees: [...]})

2. Check if an employee has a cultural profile
   GET /cultural-profile/EMP-12345

3. Compare a project team's cultural diversity
   POST /team-culture-comparison  (body: {member_ids: ["EMP-001", "EMP-002", ...]})

4. Generate a briefing for an international assignment
   POST /assignment-briefing  (body: {employee_id: "EMP-12345", destination_country: "japan"})

5. Get interaction tips for a specific meeting
   GET /interaction-tips?source=DE&target=JP

6. Generate a simulator embed for training
   POST /simulator-access  (body: {external_user_id: "EMP-12345", country: "japan"})

Need Help?

Contact us at support@interculturalteams.com for integration support.