API Documentation

Roster ¶

Bulk sync of an external org chart — roles, brands (offices), and users — into Rechat under a single brand. Intended for identity/HR integrations that own the source of truth and push their full roster on a schedule.

Everything hangs off a roster source, one per brand. Create it once, then PUT the roster to it. Records are keyed by the caller’s own external_id, so syncing is idempotent: an external_id seen before updates the existing record, a new one creates it, and re-sending the same payload is a no-op.

A sync payload has three optional arrays, each resolved by external_id:

• roles — { external_id, name, acl }, where acl is an array of Rechat permission strings (e.g. CRM, Deals, Admin).

• brands — { external_id, name, type, parent }. type is Brokerage or Office; parent references another brand’s external_id to build the tree.

• users — { external_id, email, first_name, last_name, user_type, memberships }. memberships is an array of { brand, role } pairs referencing brand and role external_ids, placing the user in the tree. Missing brand/role references in a membership are skipped rather than erroring.

Omitting an array leaves that dimension untouched. Related records are returned via associations — request them with ?associations[]=roster_source.roles and ?associations[]=roster_source.users.

Endpoints ¶

{
  "code": "OK",
  "data": {
    "type": "roster_source",
    "id": "49bf0077-ca7a-431d-a860-ffc5c45a8638",
    "created_at": 1785502022.194653,
    "updated_at": 1785502022.194653,
    "deleted_at": null
  }
}

{
  "code": "OK",
  "data": {
    "type": "roster_source",
    "id": "49bf0077-ca7a-431d-a860-ffc5c45a8638",
    "created_at": 1785502022.194653,
    "updated_at": 1785502022.194653,
    "deleted_at": null
  }
}

{
  "roles": [
    {
      "external_id": "agent",
      "name": "Agent",
      "acl": [
        "CRM",
        "Deals"
      ]
    },
    {
      "external_id": "admin",
      "name": "Admin",
      "acl": [
        "Admin",
        "BackOffice"
      ]
    }
  ],
  "brands": [
    {
      "external_id": "region-east",
      "name": "East Region",
      "type": "Brokerage"
    },
    {
      "external_id": "region-west",
      "name": "West Region",
      "type": "Brokerage"
    },
    {
      "external_id": "office-ny",
      "name": "New York Office",
      "type": "Office",
      "parent": "region-east"
    },
    {
      "external_id": "office-la",
      "name": "Los Angeles Office",
      "type": "Office",
      "parent": "region-west"
    }
  ],
  "users": [
    {
      "external_id": "user-001",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "user_type": "Agent",
      "memberships": [
        {
          "brand": "office-ny",
          "role": "agent"
        }
      ]
    },
    {
      "external_id": "user-002",
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Smith",
      "user_type": "Agent",
      "memberships": [
        {
          "brand": "office-la",
          "role": "agent"
        }
      ]
    },
    {
      "external_id": "user-003",
      "email": "[email protected]",
      "first_name": "Admin",
      "last_name": "User",
      "user_type": "Agent",
      "memberships": [
        {
          "brand": "region-east",
          "role": "admin"
        },
        {
          "brand": "region-west",
          "role": "admin"
        }
      ]
    }
  ]
}

{
  "code": "OK",
  "data": {
    "type": "roster_source",
    "id": "49bf0077-ca7a-431d-a860-ffc5c45a8638",
    "created_at": 1785502022.194653,
    "updated_at": 1785502022.194653,
    "deleted_at": null,
    "roles": [
      {
        "type": "roster_role",
        "id": "a9d1b627-478c-420b-8ec7-d83598c35a73",
        "source": "49bf0077-ca7a-431d-a860-ffc5c45a8638",
        "external_id": "agent",
        "created_at": 1785502022.194653,
        "updated_at": 1785502022.194653,
        "deleted_at": null
      },
      {
        "type": "roster_role",
        "id": "6dd985f1-7ea7-440f-ade4-5c315d82a173",
        "source": "49bf0077-ca7a-431d-a860-ffc5c45a8638",
        "external_id": "admin",
        "created_at": 1785502022.194653,
        "updated_at": 1785502022.194653,
        "deleted_at": null
      }
    ],
    "users": [
      {
        "type": "roster_user",
        "id": "a68762a4-8bc9-4419-b5c2-6015ff7280c6",
        "source": "49bf0077-ca7a-431d-a860-ffc5c45a8638",
        "external_id": "user-001",
        "object": {
          "email": "[email protected]",
          "last_name": "Doe",
          "user_type": "Agent",
          "first_name": "John",
          "external_id": "user-001"
        },
        "created_at": 1785502022.194653,
        "updated_at": 1785502022.194653,
        "deleted_at": null
      },
      {
        "type": "roster_user",
        "id": "6551927b-016a-4818-9617-9ea04e68ca8e",
        "source": "49bf0077-ca7a-431d-a860-ffc5c45a8638",
        "external_id": "user-002",
        "object": {
          "email": "[email protected]",
          "last_name": "Smith",
          "user_type": "Agent",
          "first_name": "Jane",
          "external_id": "user-002"
        },
        "created_at": 1785502022.194653,
        "updated_at": 1785502022.194653,
        "deleted_at": null
      },
      {
        "type": "roster_user",
        "id": "6609e44b-f90a-4eb7-8838-8fd544c28f9c",
        "source": "49bf0077-ca7a-431d-a860-ffc5c45a8638",
        "external_id": "user-003",
        "object": {
          "email": "[email protected]",
          "last_name": "User",
          "user_type": "Agent",
          "first_name": "Admin",
          "external_id": "user-003"
        },
        "created_at": 1785502022.194653,
        "updated_at": 1785502022.194653,
        "deleted_at": null
      }
    ]
  }
}