Skills

Every mandate needs skills from Record’s skill taxonomy. Store the skill_id values your recruiters pick and send them as the mandate’s skills. These are helper endpoints: the sample mandate already uses real skill ids, so you can skip this and come back when you build your own skill list.

Need	Endpoint
Type-ahead search	`GET /skills/search`
Browse the tree	`GET /skills/domains` → `GET /skills/domains/{domain_id}/sub-domains` → `GET /skills/sub-domains/{sub_domain_id}/skills`
One skill	`GET /skills/{skill_id}`
Re-check stored ids	`POST /skills/lookup` (up to 50)
Map free text to skills	`POST /skills/match`. `suggestion` is `auto` (use it), `confirm` (ask the recruiter) or `none`.
Suggest from a job description	`POST /skills/extract`
Ask for a missing skill	`POST /skill-requests`

Missing skills

If search cannot find a skill, ask Record to add it with POST /skill-requests and put it on the mandate as { "name": "Reach Truck Operation", "pending": true }. A pending skill is kept on the mandate but cannot be verified until the request is resolved. Track the request with GET /skill-requests/{request_id}.

Usage limits

Search and browse return at most 15,000 different skills per key per day, and more than 200 browse pages in an hour puts the key in cooldown. There is no bulk export: store only the skills your recruiters pick. See Limits.

Endpoints

Search skills

GET /skills/search Type-ahead: find skills by a few letters (e.g. “fork”) and keep the skill_id the recruiter picks. Scope: skills:read

Query	Type	Description
`q`	`string`	2 to 60 characters; matches the start of words, tolerates small typos.
`collar`	`string`	Ranks this collar first; does not hide the others. One of `blue`, `grey`, `white`.
`domain_id`	`string`	Only skills in this domain (from `GET /skills/domains`).
`sub_domain_id`	`string`	Only skills in this sub-domain.
`limit`	`integer`	1 to 20, default 10.

const res = await call("GET", "/api/v1/partner/skills/search?q=forklift&limit=10");
const { data } = await res.json();

res = call("GET", "/api/v1/partner/skills/search?q=forklift&limit=10")
data = res.json()["data"]

pcall GET "/api/v1/partner/skills/search?q=forklift&limit=10"

{
  "success": true,
  "data": {
    "query": "forklift",
    "count": 2,
    "items": [
      {
        "skill_id": "sk_5177",
        "name": "Forklift Truck",
        "sub_domain": {
          "id": "sub_architecture_and_construction__heavy_equipment_operation",
          "name": "Heavy Equipment Operation"
        },
        "domain": {
          "id": "dom_architecture_and_construction",
          "name": "Architecture and Construction"
        },
        "collar": "white",
        "verifiable": true
      },
      {
        "skill_id": "sk_5176",
        "name": "Forklift Safety",
        "sub_domain": {
          "id": "sub_architecture_and_construction__heavy_equipment_operation",
          "name": "Heavy Equipment Operation"
        },
        "domain": {
          "id": "dom_architecture_and_construction",
          "name": "Architecture and Construction"
        },
        "collar": "white",
        "verifiable": true
      }
    ]
  }
}

Error	When
400 `VALIDATION_FAILED`	`q` shorter than 2 characters, or only wildcards.
429 `DAILY_CAP`	15,000 different skills already seen today.

Can also return the common errors. Full schema

List skill domains

GET /skills/domains The top of the skill tree: all primary domains, for a browse menu. Scope: skills:read

const res = await call("GET", "/api/v1/partner/skills/domains");
const { data } = await res.json();

res = call("GET", "/api/v1/partner/skills/domains")
data = res.json()["data"]

pcall GET "/api/v1/partner/skills/domains"

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "dom_logistics_and_mobility_management",
        "name": "Logistics & Mobility Management",
        "sub_domain_count": 14,
        "skill_count": 2320
      },
      {
        "id": "dom_manufacturing_and_production",
        "name": "Manufacturing and Production",
        "sub_domain_count": 17,
        "skill_count": 4203
      }
    ],
    "count": 2,
    "total": 2,
    "next_cursor": null,
    "has_more": false
  }
}

Can also return the common errors. Full schema

List sub-domains

GET /skills/domains/{domain_id}/sub-domains The sub-domains inside one domain. Scope: skills:read

const res = await call("GET", "/api/v1/partner/skills/domains/dom_logistics_and_mobility_management/sub-domains");
const { data } = await res.json();

res = call("GET", "/api/v1/partner/skills/domains/dom_logistics_and_mobility_management/sub-domains")
data = res.json()["data"]

pcall GET "/api/v1/partner/skills/domains/dom_logistics_and_mobility_management/sub-domains"

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "sub_logistics_and_mobility_management__inventory_and_warehousing",
        "name": "Inventory and Warehousing",
        "skill_count": 316
      },
      {
        "id": "sub_logistics_and_mobility_management__logistics",
        "name": "Logistics",
        "skill_count": 160
      }
    ],
    "count": 2,
    "total": 2,
    "next_cursor": null,
    "has_more": false
  }
}

Error	When
404 `NOT_FOUND`	Unknown `domain_id`.

Can also return the common errors. Full schema

List skills in a sub-domain

GET /skills/sub-domains/{sub_domain_id}/skills The skills inside one sub-domain, 50 per page (700 at most). Scope: skills:read

Query	Type	Description
`limit`	`integer`	1 to 50, default 50.
`cursor`	`string`	The next_cursor of the previous page.
`collar`	`string`	One of `blue`, `grey`, `white`.

const res = await call("GET", "/api/v1/partner/skills/sub-domains/sub_logistics_and_mobility_management__inventory_and_warehousing/skills?limit=50");
const { data } = await res.json();

res = call("GET", "/api/v1/partner/skills/sub-domains/sub_logistics_and_mobility_management__inventory_and_warehousing/skills?limit=50")
data = res.json()["data"]

pcall GET "/api/v1/partner/skills/sub-domains/sub_logistics_and_mobility_management__inventory_and_warehousing/skills?limit=50"

{
  "success": true,
  "data": {
    "items": [
      {
        "skill_id": "sk_2298",
        "name": "American Production And Inventory Control Society (APICS) Certification",
        "sub_domain": {
          "id": "sub_logistics_and_mobility_management__inventory_and_warehousing",
          "name": "Inventory and Warehousing"
        },
        "domain": {
          "id": "dom_logistics_and_mobility_management",
          "name": "Logistics & Mobility Management"
        },
        "collar": "white",
        "verifiable": true
      },
      {
        "skill_id": "sk_2299",
        "name": "Assortment Optimization",
        "sub_domain": {
          "id": "sub_logistics_and_mobility_management__inventory_and_warehousing",
          "name": "Inventory and Warehousing"
        },
        "domain": {
          "id": "dom_logistics_and_mobility_management",
          "name": "Logistics & Mobility Management"
        },
        "collar": "white",
        "verifiable": true
      }
    ],
    "count": 2,
    "total": 316,
    "next_cursor": "eyJvIjo1MH0",
    "has_more": true
  }
}

Error	When
404 `NOT_FOUND`	Unknown `sub_domain_id`.
429 `COOLDOWN`	More than 200 browse pages in an hour.
429 `DAILY_CAP`	15,000 different skills already seen today.

Can also return the common errors. Full schema

Get a skill

GET /skills/{skill_id} Fetch one skill by its skill_id. Scope: skills:read

const res = await call("GET", "/api/v1/partner/skills/sk_38824");
const { data } = await res.json();

res = call("GET", "/api/v1/partner/skills/sk_38824")
data = res.json()["data"]

pcall GET "/api/v1/partner/skills/sk_38824"

{
  "success": true,
  "data": {
    "skill_id": "sk_38824",
    "name": "Packing Station Setup",
    "sub_domain": {
      "id": "sub_logistics_and_mobility_management__inventory_and_warehousing",
      "name": "Inventory and Warehousing"
    },
    "domain": {
      "id": "dom_logistics_and_mobility_management",
      "name": "Logistics & Mobility Management"
    },
    "collar": "blue",
    "verifiable": true,
    "status": "active"
  }
}

Error	When
404 `NOT_FOUND`	Unknown `skill_id`.

Can also return the common errors. Full schema

Look up skills

POST /skills/lookup Check up to 50 skill ids you stored: still active, or not_found (removed)? Scope: skills:read · Idempotency-Key: optional

Field	Type	Description
`skill_ids`	`array<string>`	Required. 1 to 50 items.

const res = await call("POST", "/api/v1/partner/skills/lookup", {
  "skill_ids": ["sk_38824", "sk_36440", "sk_99999999"]
});
const { data } = await res.json();

res = call("POST", "/api/v1/partner/skills/lookup", {
    "skill_ids": ["sk_38824", "sk_36440", "sk_99999999"]
})
data = res.json()["data"]

pcall POST "/api/v1/partner/skills/lookup" '{
  "skill_ids": ["sk_38824", "sk_36440", "sk_99999999"]
}'

{
  "success": true,
  "data": {
    "items": [
      {
        "skill_id": "sk_38824",
        "name": "Packing Station Setup",
        "sub_domain": {
          "id": "sub_logistics_and_mobility_management__inventory_and_warehousing",
          "name": "Inventory and Warehousing"
        },
        "domain": {
          "id": "dom_logistics_and_mobility_management",
          "name": "Logistics & Mobility Management"
        },
        "collar": "blue",
        "verifiable": true,
        "status": "active"
      },
      {
        "skill_id": "sk_36440",
        "name": "Forklift Basic Operation",
        "sub_domain": {
          "id": "sub_architecture_and_construction__heavy_equipment_operation",
          "name": "Heavy Equipment Operation"
        },
        "domain": {
          "id": "dom_architecture_and_construction",
          "name": "Architecture and Construction"
        },
        "collar": "blue",
        "verifiable": true,
        "status": "active"
      },
      { "skill_id": "sk_99999999", "status": "not_found" }
    ]
  }
}

Error	When
400 `VALIDATION_FAILED`	More than 50 ids, repeated ids, or a bad id format.

Can also return idempotency errors (IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_KEY_REUSED) and the common errors. Full schema

Match text to skills

POST /skills/match Turn free text into official skills; suggestion is auto (use it), confirm (ask the recruiter) or none. Scope: skills:read · Idempotency-Key: optional

Field	Type	Description
`texts`	`array<string>`	Required. 1 to 20 items.
`collar`	`string`	One of `blue`, `grey`, `white`.
`top_k`	`integer`	1 to 3. Default `3`.

const res = await call("POST", "/api/v1/partner/skills/match", {
  "texts": ["Forklift Basic Operation", "warehouse picking", "reach truck driver"],
  "top_k": 2
});
const { data } = await res.json();

res = call("POST", "/api/v1/partner/skills/match", {
    "texts": ["Forklift Basic Operation", "warehouse picking", "reach truck driver"],
    "top_k": 2
})
data = res.json()["data"]

pcall POST "/api/v1/partner/skills/match" '{
  "texts": ["Forklift Basic Operation", "warehouse picking", "reach truck driver"],
  "top_k": 2
}'

{
  "success": true,
  "data": {
    "items": [
      {
        "text": "Forklift Basic Operation",
        "suggestion": "auto",
        "matches": [
          {
            "skill": {
              "skill_id": "sk_36440",
              "name": "Forklift Basic Operation",
              "sub_domain": {
                "id": "sub_architecture_and_construction__heavy_equipment_operation",
                "name": "Heavy Equipment Operation"
              },
              "domain": {
                "id": "dom_architecture_and_construction",
                "name": "Architecture and Construction"
              },
              "collar": "blue",
              "verifiable": true
            },
            "confidence": 1
          }
        ]
      },
      {
        "text": "warehouse picking",
        "suggestion": "confirm",
        "matches": [
          {
            "skill": {
              "skill_id": "sk_2381",
              "name": "Warehousing",
              "sub_domain": {
                "id": "sub_logistics_and_mobility_management__inventory_and_warehousing",
                "name": "Inventory and Warehousing"
              },
              "domain": {
                "id": "dom_logistics_and_mobility_management",
                "name": "Logistics & Mobility Management"
              },
              "collar": "white",
              "verifiable": true
            },
            "confidence": 0.72
          }
        ]
      },
      {
        "text": "reach truck driver",
        "suggestion": "none",
        "matches": []
      }
    ]
  }
}

Error	When
400 `VALIDATION_FAILED`	Send 1–20 texts; `top_k` 1–3.
429 `DAILY_CAP`	50,000 matches already used today.

Can also return idempotency errors (IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_KEY_REUSED) and the common errors. Full schema

Extract skills from a job

POST /skills/extract Suggest skills from a job title and description. Nothing is saved. Scope: skills:read · Idempotency-Key: optional

Field	Type	Description
`title`	`string`	Required. 1 to 200 characters.
`description`	`string`	At most 5000 characters. Default `""`.
`collar`	`string`	One of `blue`, `grey`, `white`.

const res = await call("POST", "/api/v1/partner/skills/extract", {
  "title": "Forklift Truck Operator",
  "description": "Must hold Forklift Certification. Order Picking and Loading And Unloading of trucks."
});
const { data } = await res.json();

res = call("POST", "/api/v1/partner/skills/extract", {
    "title": "Forklift Truck Operator",
    "description": "Must hold Forklift Certification. Order Picking and Loading And Unloading of trucks."
})
data = res.json()["data"]

pcall POST "/api/v1/partner/skills/extract" '{
  "title": "Forklift Truck Operator",
  "description": "Must hold Forklift Certification. Order Picking and Loading And Unloading of trucks."
}'

{
  "success": true,
  "data": {
    "items": [
      {
        "skill": {
          "skill_id": "sk_5177",
          "name": "Forklift Truck",
          "sub_domain": {
            "id": "sub_architecture_and_construction__heavy_equipment_operation",
            "name": "Heavy Equipment Operation"
          },
          "domain": {
            "id": "dom_architecture_and_construction",
            "name": "Architecture and Construction"
          },
          "collar": "white",
          "verifiable": true
        },
        "confidence": 0.97,
        "matched_text": "forklift truck"
      },
      {
        "skill": {
          "skill_id": "sk_2338",
          "name": "Order Picking",
          "sub_domain": {
            "id": "sub_logistics_and_mobility_management__inventory_and_warehousing",
            "name": "Inventory and Warehousing"
          },
          "domain": {
            "id": "dom_logistics_and_mobility_management",
            "name": "Logistics & Mobility Management"
          },
          "collar": "white",
          "verifiable": true
        },
        "confidence": 0.9,
        "matched_text": "order picking"
      },
      {
        "skill": {
          "skill_id": "sk_5175",
          "name": "Forklift Certification",
          "sub_domain": {
            "id": "sub_architecture_and_construction__heavy_equipment_operation",
            "name": "Heavy Equipment Operation"
          },
          "domain": {
            "id": "dom_architecture_and_construction",
            "name": "Architecture and Construction"
          },
          "collar": "white",
          "verifiable": true
        },
        "confidence": 0.9,
        "matched_text": "forklift certification"
      }
    ]
  }
}

Error	When
400 `VALIDATION_FAILED`	Missing `title`.

Can also return idempotency errors (IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_KEY_REUSED) and the common errors. Full schema

Request a skill

POST /skill-requests Ask Record to add a skill that search could not find. Returns request_id. Scope: skills:request · Idempotency-Key: required

Field	Type	Description
`name`	`string`	Required. 2 to 120 characters.
`collar`	`string`	One of `blue`, `grey`, `white`.
`domain_hint`	`string`	At most 200 characters.
`mandate_external_id`	`string`	Your own id (1 to 128 of A-Z a-z 0-9 . _ : -).
`requested_by`	`string`	Your ATS user id.

const res = await call("POST", "/api/v1/partner/skill-requests", {
  "name": "Reach Truck Operation",
  "collar": "blue",
  "domain_hint": "Logistics and warehousing",
  "mandate_external_id": "job-10452",
  "requested_by": "recruiter_1042"
});
const { data } = await res.json();

res = call("POST", "/api/v1/partner/skill-requests", {
    "name": "Reach Truck Operation",
    "collar": "blue",
    "domain_hint": "Logistics and warehousing",
    "mandate_external_id": "job-10452",
    "requested_by": "recruiter_1042"
})
data = res.json()["data"]

pcall POST "/api/v1/partner/skill-requests" '{
  "name": "Reach Truck Operation",
  "collar": "blue",
  "domain_hint": "Logistics and warehousing",
  "mandate_external_id": "job-10452",
  "requested_by": "recruiter_1042"
}'

{
  "success": true,
  "data": {
    "request_id": "skr_9f2c41d7a8b3e65f1c02",
    "name": "Reach Truck Operation",
    "status": "pending",
    "collar": "blue",
    "domain_hint": "Logistics and warehousing",
    "mandate_external_id": "job-10452",
    "requested_by": "recruiter_1042",
    "skill": null,
    "reason": null,
    "created_at": "2026-10-09T10:20:00.000Z",
    "updated_at": "2026-10-09T10:20:00.000Z"
  }
}

Save data.request_id for the next step.

Error	When
400 `VALIDATION_FAILED`	`name` shorter than 2 characters.

Can also return idempotency errors (IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_KEY_REUSED) and the common errors. Full schema

List skill requests

GET /skill-requests See every skill you asked for and where it stands. Scope: skills:request

Query	Type	Description
`status`	`string`	One of `pending`, `approved`, `merged`, `rejected`, `duplicate_of`.
`limit`	`integer`	1 to 100, default 50.
`cursor`	`string`	The next_cursor of the previous page.

const res = await call("GET", "/api/v1/partner/skill-requests?status=pending&limit=50");
const { data } = await res.json();

res = call("GET", "/api/v1/partner/skill-requests?status=pending&limit=50")
data = res.json()["data"]

pcall GET "/api/v1/partner/skill-requests?status=pending&limit=50"

{
  "success": true,
  "data": {
    "items": [
      {
        "request_id": "skr_9f2c41d7a8b3e65f1c02",
        "name": "Reach Truck Operation",
        "status": "pending",
        "collar": "blue",
        "domain_hint": "Logistics and warehousing",
        "mandate_external_id": "job-10452",
        "requested_by": "recruiter_1042",
        "skill": null,
        "reason": null,
        "created_at": "2026-10-09T10:20:00.000Z",
        "updated_at": "2026-10-09T10:20:00.000Z"
      }
    ],
    "count": 1,
    "total": 1,
    "next_cursor": null,
    "has_more": false
  }
}

Can also return the common errors. Full schema

Get a skill request

GET /skill-requests/{request_id} Check one skill request, for example whether Record approved it. Scope: skills:request

const res = await call("GET", "/api/v1/partner/skill-requests/skr_9f2c41d7a8b3e65f1c02");
const { data } = await res.json();

res = call("GET", "/api/v1/partner/skill-requests/skr_9f2c41d7a8b3e65f1c02")
data = res.json()["data"]

pcall GET "/api/v1/partner/skill-requests/skr_9f2c41d7a8b3e65f1c02"

{
  "success": true,
  "data": {
    "request_id": "skr_9f2c41d7a8b3e65f1c02",
    "name": "Reach Truck Operation",
    "status": "pending",
    "collar": "blue",
    "domain_hint": "Logistics and warehousing",
    "mandate_external_id": "job-10452",
    "requested_by": "recruiter_1042",
    "skill": null,
    "reason": null,
    "created_at": "2026-10-09T10:20:00.000Z",
    "updated_at": "2026-10-09T10:20:00.000Z"
  }
}

Error	When
404 `NOT_FOUND`	No such `request_id`.

Can also return the common errors. Full schema

Get started

Integration

Reference

Missing skills

Usage limits

Endpoints

Search skills

List skill domains

List sub-domains

List skills in a sub-domain

Get a skill

Look up skills

Match text to skills

Extract skills from a job

Request a skill

List skill requests

Get a skill request

​Missing skills

​Usage limits

​Endpoints

​Search skills

​List skill domains

​List sub-domains

​List skills in a sub-domain

​Get a skill

​Look up skills

​Match text to skills

​Extract skills from a job

​Request a skill

​List skill requests

​Get a skill request

Missing skills

Usage limits

Endpoints

Search skills

List skill domains

List sub-domains

List skills in a sub-domain

Get a skill

Look up skills

Match text to skills

Extract skills from a job

Request a skill

List skill requests

Get a skill request