# Assessments

Enterprise endpoints for custom scoring, batch operations, and career transition analysis.

**Access:** Enterprise only

## Custom Score

```http
POST /assessments/custom-score
```

Calculate custom risk scores using your own dimension weights.

### Request Body

```json
{
  "weights": {
    "procedural": 0.5,
    "digitization": 0.3,
    "physicality": -0.8,
    "socio_emotional": -1.0
  },
  "aggregation": "weighted_mean",
  "jobs": ["15-1252.00", "29-1141.00", "43-3031.00"]
}
```

### Fields

| Field                     | Type   | Required | Description                          |
| ------------------------- | ------ | -------- | ------------------------------------ |
| `weights`                 | object | Yes      | Dimension weights (-1.0 to 1.0)      |
| `weights.procedural`      | float  | Yes      | Weight for procedural dimension      |
| `weights.digitization`    | float  | Yes      | Weight for digitization dimension    |
| `weights.physicality`     | float  | Yes      | Weight for physicality dimension     |
| `weights.socio_emotional` | float  | Yes      | Weight for socio-emotional dimension |
| `aggregation`             | string | No       | `weighted_mean` (default) or `max`   |
| `jobs`                    | array  | Yes      | SOC codes to score (max 100)         |

### Weight Interpretation

* **Positive weights**: Increase the exposure score
* **Negative weights**: Decrease the exposure score (protective)
* **Zero**: Dimension is ignored

### Response

```json
{
  "methodology": {
    "weights_applied": {
      "procedural": 0.5,
      "digitization": 0.3,
      "physicality": -0.8,
      "socio_emotional": -1.0
    },
    "aggregation": "weighted_mean",
    "interpretation": "Positive = increases exposure. Negative = protective."
  },
  "results": [
    {
      "soc_code": "43-3031.00",
      "title": "Bookkeeping, Accounting, and Auditing Clerks",
      "custom_score": 78.4,
      "rank": 1,
      "standard_score": 49.3,
      "delta_from_standard": 29.1
    },
    {
      "soc_code": "15-1252.00",
      "title": "Software Developers",
      "custom_score": 58.1,
      "rank": 2,
      "standard_score": 47.5,
      "delta_from_standard": 10.6
    },
    {
      "soc_code": "29-1141.00",
      "title": "Registered Nurses",
      "custom_score": 38.4,
      "rank": 3,
      "standard_score": 47.3,
      "delta_from_standard": -8.9
    }
  ]
}
```

### Example

```bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "weights": {
      "procedural": 0.5,
      "digitization": 0.3,
      "physicality": -0.8,
      "socio_emotional": -0.5
    },
    "jobs": ["15-1252.00", "29-1141.00"]
  }' \
  "https://api.maidenlabs.tools/assessments/custom-score"
```

***

## Batch Lookup

```http
POST /jobs/batch
```

Retrieve profiles for multiple jobs in a single request.

### Request Body

```json
{
  "soc_codes": ["15-1252.00", "29-1141.00", "43-3031.00"],
  "fields": ["scores", "pillars", "classification", "keystone_skills"],
  "format": "json"
}
```

### Fields

| Field       | Type   | Required | Description                      |
| ----------- | ------ | -------- | -------------------------------- |
| `soc_codes` | array  | Yes      | SOC codes to retrieve (max 500)  |
| `fields`    | array  | No       | Fields to include (default: all) |
| `format`    | string | No       | `json` (only supported format)   |

### Available Fields

* `scores` - Automation susceptibility, resilience, balanced impact
* `pillars` - AI exposure potential, human imperative, dispositional resilience
* `classification` - Quadrant, SOC hierarchy, projected growth
* `keystone_skills` - Top 10 high-impact skills
* `industries` - Industry distribution

### Response

```json
{
  "job_count": 3,
  "fields_included": ["scores", "pillars", "classification"],
  "jobs": [
    {
      "soc_code": "15-1252.00",
      "title": "Software Developers",
      "scores": {
        "automation_susceptibility_score": 47.5,
        "human_centric_resilience_score": 54.7,
        "balanced_impact_score": 7.2
      },
      "pillars": {
        "ai_exposure_potential": 0.475,
        "human_imperative": 0.361,
        "dispositional_resilience": 0.734
      },
      "classification": {
        "quadrant": "augmentation",
        "major_group": "15-0000",
        "major_group_label": "Computer and Mathematical Occupations"
      }
    }
  ]
}
```

### Example

```bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "soc_codes": ["15-1252.00", "29-1141.00"],
    "fields": ["scores", "keystone_skills"]
  }' \
  "https://api.maidenlabs.tools/jobs/batch"
```

***

## Career Transitions

```http
POST /jobs/transitions
```

Find career transition pathways using skill-based similarity.

### Request Body

```json
{
  "source_soc": "43-3031.00",
  "similarity_threshold": 0.70,
  "max_results": 20,
  "filters": {
    "min_resilience_gain": 10,
    "require_positive_growth": true
  }
}
```

### Fields

| Field                  | Type   | Required | Default | Description                          |
| ---------------------- | ------ | -------- | ------- | ------------------------------------ |
| `source_soc`           | string | Yes      | -       | Starting job SOC code                |
| `similarity_threshold` | float  | No       | 0.80    | Minimum skill similarity (0.5-1.0)   |
| `max_results`          | int    | No       | 10      | Maximum transitions to return (1-50) |
| `filters`              | object | No       | -       | Filter criteria                      |

### Filter Options

| Filter                    | Type  | Description                          |
| ------------------------- | ----- | ------------------------------------ |
| `min_resilience_gain`     | float | Minimum resilience score improvement |
| `max_resilience_loss`     | float | Maximum resilience score decrease    |
| `require_positive_growth` | bool  | Only include growing occupations     |
| `min_projected_growth`    | float | Minimum projected growth rate        |
| `exclude_soc_codes`       | array | SOC codes to exclude from results    |

### Response

```json
{
  "source_job": {
    "soc_code": "43-3031.00",
    "title": "Bookkeeping, Accounting, and Auditing Clerks",
    "automation_susceptibility_score": 49.3,
    "human_centric_resilience_score": 49.3
  },
  "transition_count": 8,
  "transitions": [
    {
      "target_soc": "13-2011.00",
      "target_title": "Accountants and Auditors",
      "skill_similarity": 0.91,
      "resilience_gain": 11.4,
      "target_resilience_score": 60.7,
      "projected_growth": "Faster than average",
      "overlapping_skills": [
        "Mathematics",
        "Critical Thinking",
        "Active Listening",
        "Reading Comprehension"
      ],
      "gap_skills": [
        "Complex Problem Solving",
        "Judgment and Decision Making",
        "Negotiation"
      ],
      "transition_difficulty": "low"
    }
  ]
}
```

### Transition Difficulty Levels

| Level    | Skill Similarity | Typical Meaning                 |
| -------- | ---------------- | ------------------------------- |
| `low`    | >= 85%           | Minimal retraining, same field  |
| `medium` | 70-84%           | Moderate skill development      |
| `high`   | < 70%            | Significant retraining required |

### Example

```bash
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_soc": "43-9061.00",
    "similarity_threshold": 0.7,
    "max_results": 10,
    "filters": {
      "min_resilience_gain": 5,
      "require_positive_growth": true
    }
  }' \
  "https://api.maidenlabs.tools/jobs/transitions"
```

***

## Rate Limits

Enterprise endpoints have the same rate limits as other endpoints (10,000/day), but batch operations count as a single request regardless of how many jobs are included.

| Operation               | Rate Limit Impact |
| ----------------------- | ----------------- |
| Batch lookup (500 jobs) | 1 request         |
| Custom score (100 jobs) | 1 request         |
| Transitions             | 1 request         |


---

# 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://docs.maidenlabs.tools/api-reference/assessments.md?ask=<question>
```

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.