Dex Guide
Dex Dashboard
Company Roles

Add a company role

Add a role for a contact (`contact_id`) at a company. `role.mode`: `add` (a concurrent role; ends nothing), `change_employer` (also ends the contact's other current roles, with the optional `previous_

POST /v2/company-roles/

Request body

Content-Type: application/json

contact_id
string (uuid) required
role
object required
role.mode
string enum required
Possible values: "add", "change_employer", "new_period"
role.company_id
string (uuid) required
role.previous_role_id
string (uuid)
role.title
string
role.status
string enum required
Possible values: "current", "past", "unknown"
role.is_primary
boolean
role.start_year
integer | null
role.start_month
integer | null
role.start_day
integer | null
role.end_year
integer | null
role.end_month
integer | null
role.end_day
integer | null
role.previous_end_year
integer | null
role.previous_end_month
integer | null
role.previous_end_day
integer | null

Example

{
  "contact_id": "00000000-0000-0000-0000-000000000000",
  "role": {
    "mode": "add",
    "company_id": "00000000-0000-0000-0000-000000000000",
    "status": "current"
  }
}

Responses

201 — Created

Content-Type: application/json

data
object required
data.roles
array<object> required
data.roles[].id
string (uuid) required
data.roles[].contact_id
string (uuid) required
data.roles[].company_id
string (uuid) required
data.roles[].user_id
string required
data.roles[].workspace_id
string (uuid) | null required
data.roles[].title
string | null required
data.roles[].status
string enum required
Possible values: "current", "past", "unknown"
data.roles[].is_primary
boolean required
data.roles[].start_year
integer | null required
data.roles[].start_month
integer | null required
data.roles[].start_day
integer | null required
data.roles[].end_year
integer | null required
data.roles[].end_month
integer | null required
data.roles[].end_day
integer | null required
data.roles[].provenance
string enum required
Possible values: "manual", "add_people", "csv_import", "auto_link", "copy", "mcp", "extension", "migration", "text_conversion", "merge"
data.roles[].created_at
string (date-time) required
data.roles[].updated_at
string (date-time) required
data.roles[].company
object required
data.roles[].company.id
string (uuid) required
data.roles[].company.name
string required
data.roles[].company.logo_url
string | null required
data.roles[].company.archived_at
string (date-time) required
data.contact
object required
data.contact.id
string (uuid) required
data.contact.company
string | null required

Example

{
  "data": {
    "roles": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "contact_id": "00000000-0000-0000-0000-000000000000",
        "company_id": "00000000-0000-0000-0000-000000000000",
        "user_id": "string",
        "workspace_id": "00000000-0000-0000-0000-000000000000",
        "title": "string",
        "status": "current",
        "is_primary": false,
        "start_year": 0,
        "start_month": 0,
        "start_day": 0,
        "end_year": 0,
        "end_month": 0,
        "end_day": 0,
        "provenance": "manual",
        "created_at": "2026-10-23T10:31:51.487Z",
        "updated_at": "2026-10-23T10:31:51.487Z",
        "company": {
          "id": "00000000-0000-0000-0000-000000000000",
          "name": "string",
          "logo_url": "string",
          "archived_at": "2026-10-23T10:31:51.487Z"
        }
      }
    ],
    "contact": {
      "id": "00000000-0000-0000-0000-000000000000",
      "company": "string"
    }
  }
}

400 — Request body failed validation.

Content-Type: application/json

(body)
any

401 — Missing or invalid API key.

Content-Type: application/json

(body)
any

403 — Valid key, insufficient permission.

Content-Type: application/json

(body)
any

404 — Resource does not exist.

Content-Type: application/json

(body)
any

409 — Request conflicts with the current state of the resource.

Content-Type: application/json

(body)
any

429 — Rate limit exceeded.

Content-Type: application/json

(body)
any

500 — Unexpected server error.

Content-Type: application/json

(body)
any

Code samples

curl https://api.prod.getdex.com/v2/company-roles/ \
  --request POST \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "contact_id": "00000000-0000-0000-0000-000000000000",
  "role": {
    "mode": "add",
    "company_id": "00000000-0000-0000-0000-000000000000",
    "status": "current"
  }
}'

List a contact's company roles

List the roles of one workspace contact (`contact_id`) at companies, archived companies included. 404 `record_not_found` when the contact is not in the workspace. Workspace-only: send the `X-Dex-Works

Set a contact's current company

Set a contact's current company, as the contact page's picker does. `company_id` null ends every current role (end date unknown). A company the contact already has a current role at makes that role pr

Copyright © 2026