Load the workspace's roster (org structure and people)

POST

/contacts/roster

const url = 'https://app.surveyrock.com/api/v1/contacts/roster';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"people":[{}],"dry_run":false,"confirm_leavers":1}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://app.surveyrock.com/api/v1/contacts/roster \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "people": [ {} ], "dry_run": false, "confirm_leavers": 1 }'

Loads the whole roster in one request, exactly as an HR file uploaded on the Org Structure page: the teams and their parents and leaders, and the people with their team. The roster is the whole structure: teams not in it are archived, and people not in it lose their team and leave the workspace’s roster list (Employees (roster)). A person whose leaving_date has passed is kept as a contact but is not on the list. With employee_id, a person is matched on it before their email, so an email changed in the HR system updates their contact. Each person is an object whose keys are the roster’s column names: email, team_code, team_name, parent_code, leader_email (a string or an array), first_name, last_name, employee_id, start_date, leaving_date (YYYY-MM-DD), location, job_title, employment_type. A record with no email defines a team with nobody directly in it. Stops: a roster that would take 20% or more of the people on the roster list off it, or would pass the plan’s contact limit, is refused with 409 and nothing is written; to load one that removes that many on purpose, send it again with confirm_leavers equal to the number of leavers the refusal names. dry_run: true checks the roster and reports what it would do without writing. Requires a plan with team reports (Growth and up), a token with contacts:write, and a token owner who may manage the workspace’s settings (an owner or admin): the token itself never holds the settings right, it is checked on the person.

Authorizations

bearerAuth
contacts:write

Parameters

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 128 characters

1 to 128 characters, chosen by the caller. A retry with the same key and body replays the first response instead of applying the write twice; the same key with a different body is a 409

Request Body^required

application/json

object

people

required

Array<object>

<= 20000 items

object

dry_run

Check and report only; write nothing

boolean

confirm_leavers

The number of leavers a refused roster named, to load it anyway

integer

nullable

Responses

200

Loaded (or, with dry_run, checked). data holds counts, roster (members, joiners, leavers, newContacts), warnings, stops and, when loaded, people (created, updated, leftRoster, emailsMoved and row errors).

403

The plan does not include team reports (feature_locked), or the caller may not manage the workspace’s settings or import contacts

409

A stop refused the roster (roster_stopped): details lists each stop; nothing was written

422

The roster is not valid: each error names its record