Quick Start

Make your first API call in under 5 minutes.

Step 1: Access the Embedded API Portal

All Embedded API customers get access to the Embedded API Portal where you can:

View your primary API keys (pk_live and pk_test)
Provision end-customer API keys
Monitor usage and billing

Contact [email protected] to get portal access.

Step 2: Understand Your API Keys

You'll have access to two types of keys:

Key Type

Format

Environment

Test Key

pk_test_xxx...

embedded-api.testing.mapademics.com

Live Key

pk_live_xxx...

embedded-api.mapademics.com

Important: Production API calls require both your primary key (pk_live) and an end-customer key. Testing calls only require your test key (pk_test).

Start with the testing environment during development. It has sample data, higher rate limits, and doesn't require end-customer keys.

Step 3: Make Your First Request

Let's fetch the complete skills library tree. This is the simplest endpoint and confirms your authentication is working.

curl -X GET "https://embedded-api.testing.mapademics.com/v1/skills/domains" \
  -H "X-API-Key: pk_test_your_key_here"

const response = await fetch(
  "https://embedded-api.testing.mapademics.com/v1/skills/domains",
  {
    headers: {
      "X-API-Key": "pk_test_your_key_here",
    },
  }
);

const data = await response.json();
console.log(data);

import requests

response = requests.get(
    "https://embedded-api.testing.mapademics.com/v1/skills/domains",
    headers={
        "X-API-Key": "pk_test_your_key_here"
    }
)

print(response.json())

Step 4: Check the Response

A successful response looks like this:

{
  "object": "list",
  "data": [
    {
      "id": "msl_dom_1",
      "name": "Finance & Accounting",
      "version": "1.0",
      "skillCount": 24
    },
    {
      "id": "msl_dom_8",
      "name": "Data & Analytics",
      "version": "1.0",
      "skillCount": 18
    },
    {
      "id": "msl_dom_15",
      "name": "Information Technology",
      "version": "1.0",
      "skillCount": 32
    }
  ],
  "meta": {
    "requestId": "req_abc123xyz",
    "timestamp": "2025-01-30T12:00:00Z"
  }
}

If you see this response, congratulations! You're ready to start building.

Step 5: Try a Real Use Case

Now let's do something practical: find out what careers a Computer Science degree leads to.

curl -X POST "https://embedded-api.testing.mapademics.com/v1/labor-market-intelligence/by-cip" \
  -H "X-API-Key: pk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"cipCodes": ["11.0701"]}'

const response = await fetch(
  "https://embedded-api.testing.mapademics.com/v1/labor-market-intelligence/by-cip",
  {
    method: "POST",
    headers: {
      "X-API-Key": "pk_test_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ cipCodes: ["11.0701"] }),
  }
);

const data = await response.json();

// Print occupation names and salaries
data.data.matchedOccupations.forEach((occ) => {
  console.log(`${occ.name}: $${occ.laborMarketData.medianAnnualSalary.toLocaleString()}`);
});

This returns occupations linked to CIP code 11.0701 (Computer Science), including:

Median salaries
Employment projections
Required skills

{
  "object": "cip_labor_market",
  "data": {
    "cipCodes": ["11.0701"],
    "regionType": "national",
    "region": "United States",
    "matchedOccupations": [
      {
        "name": "Software Developers",
        "socCode": "15-1252",
        "laborMarketData": {
          "medianAnnualSalary": 127260,
          "totalEmployment": 1795300,
          "forecastedEmploymentGrowth": 0.252,
          "demand": {
            "score": 5,
            "factors": ["Bright Outlook", "In-Demand"]
          }
        },
        "skillRequirements": {
          "coreSkills": [
            {
              "mslSkillId": "msl_skill_0127",
              "mslSkillName": "Software Development"
            }
          ]
        }
      }
    ]
  }
}