Create a potential candidate
Create a sourced lead in an organization. Scope: sourcing:write.
POST
/api/v1/sourcing
🔒 API keyCreates a potential candidate (lead) in a target organization. Scope: sourcing:write. Requires employer-write authority in organizationId (admins bypass) and that the organization exists. The lead is linked to that organization on creation.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
fullName | string | Yes | Lead’s full name. |
organizationId | string | Yes | Organization to create the lead in. |
email | string | No | CV email (validated). |
contactEmail | string | No | Account/contact email (validated). |
phone | string | No | Phone (validated). |
summary | string | No | Free-text summary. |
skills | string[] | No | Skill tags. |
status | string | No | Lead status. Defaults to uploaded. |
Example request
curl -X POST https://app.talent-ray.com/api/v1/sourcing \
-H "Authorization: Bearer tr_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "fullName": "Sam Lee", "organizationId": "org_acme", "contactEmail": "[email protected]", "skills": ["python", "sql"] }'Response
201 Created — the created potential candidate (same shape as List potential candidates).
Status codes
| Status | Meaning |
|---|---|
201 | Created. |
400 | bad_request — missing/invalid fields, or organizationId does not exist. |
401 | No valid API key. |
403 | insufficient_scope (missing sourcing:write) or forbidden (no write authority in the target org). |
429 | Rate limit exceeded. |