Org Team

Overview

Org teams represent your company’s organizational hierarchy: for example departments, regions, or business units. Use org teams to group users, define managers, and scope spend or benefits. Create org teams before assigning users to teams or referencing them in budget mappings (teamId).

Typical flow:

1. Create an org team: POST /md/api/OrgTeams
2. Update an org team: PATCH /md/api/OrgTeams/{orgTeamId}
3. Retrieve by ID: GET /md/api/OrgTeams/{orgTeamId}
4. Assign a user to the team: POST /md/api/TeamUserMappings
5. Update a mapping: PATCH /md/api/TeamUserMappings/{teamUserMappingId}
6. Remove a user from the team: DELETE /md/api/TeamUserMappings/{teamUserMappingId}
7. List members: GET /md/api/OrgTeams/{orgTeamId}/allMembers

Create Org Team

Creates a new org team for the company associated with your access token. The platform sets companyId, id, active, and status automatically.

Request Body: mandatory fields

Optional fields

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/OrgTeams \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Regional Sales Team"
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/OrgTeams', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Regional Sales Team'
  })
});

const orgTeam = await response.json();

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Regional Sales Team",
  "active": true,
  "companyId": "your-company-id",
  "status": "active"
}

Update Org Team

Partially updates an existing org team. Only include fields you want to change. Do not send companyId or id: they cannot be changed via this endpoint.

Path Parameters

Request Body

All fields are optional on update. Send only the properties you want to change:

Example Request

Rename the team and assign a leader:

Using cURL:

curl -X PATCH https://sandbox.custodia-tech.com/md/api/OrgTeams/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "North America Sales Team",
    "leaderId": "your-user-id"
  }'

Using JavaScript (fetch):

const orgTeamId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/OrgTeams/${orgTeamId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'North America Sales Team',
    leaderId: 'your-user-id'
  })
});

const orgTeam = await response.json();

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "North America Sales Team",
  "active": true,
  "companyId": "your-company-id",
  "leaderId": "your-user-id",
  "status": "active"
}

Get Org Team by ID

Retrieves a single org team by its ID. Use the id returned from create org team.

Path Parameters

Example Request

Using cURL:

curl -X GET https://sandbox.custodia-tech.com/md/api/OrgTeams/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID"

Using JavaScript (fetch):

const orgTeamId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/OrgTeams/${orgTeamId}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const orgTeam = await response.json();

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Regional Sales Team",
  "active": true,
  "companyId": "your-company-id",
  "leaderId": null,
  "subsidiaryId": null,
  "externalId": null,
  "status": "active",
  "deletedOn": null,
  "deletedBy": null
}

Create Team User Mapping

Assigns a user to an org team by creating a team user mapping: the join record that links a user (memberId) to a team (teamId). Users are not added to teams by updating the org team or user record directly.

Prerequisites: the org team and user must already exist. Create users via Create User and org teams via create org team before calling this endpoint.

Request Body: mandatory fields

Optional fields

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/TeamUserMappings \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "teamType": "OrgTeam",
    "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/TeamUserMappings', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    teamId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    teamType: 'OrgTeam',
    memberId: 'b2c3d4e5-f6a7-8901-bcde-f12345678901'
  })
});

const mapping = await response.json();

Response

{
  "id": "f6a7b8c9-d0e1-2345-fabc-678901234567",
  "teamId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "teamType": "OrgTeam",
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "order": 0,
  "companyId": "your-company-id"
}

After creating the mapping, confirm membership with get org team members. Save the returned id to update or remove the mapping later.

Update Team User Mapping

Partially updates an existing team user mapping. Only include fields you want to change. Do not send companyId or id: they cannot be changed via this endpoint.

Path Parameters

Request Body

All fields are optional on update. Send only the properties you want to change:

To move a user to a different org team, you can update teamId or delete the existing mapping and create a new one.

Example Request

Change the sort order for a user with multiple team memberships:

Using cURL:

curl -X PATCH https://sandbox.custodia-tech.com/md/api/TeamUserMappings/f6a7b8c9-d0e1-2345-fabc-678901234567 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "order": 1
  }'

Using JavaScript (fetch):

const teamUserMappingId = 'f6a7b8c9-d0e1-2345-fabc-678901234567';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/TeamUserMappings/${teamUserMappingId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    order: 1
  })
});

const mapping = await response.json();

Response

{
  "id": "f6a7b8c9-d0e1-2345-fabc-678901234567",
  "teamId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "teamType": "OrgTeam",
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "order": 1,
  "companyId": "your-company-id"
}

Delete Team User Mapping

Removes a user from an org team by deleting the team user mapping. Use the mapping id returned from create team user mapping. This soft-deletes the mapping record: the user and org team are not deleted.

Path Parameters

Example Request

Using cURL:

curl -X DELETE https://sandbox.custodia-tech.com/md/api/TeamUserMappings/f6a7b8c9-d0e1-2345-fabc-678901234567 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID"

Using JavaScript (fetch):

const teamUserMappingId = 'f6a7b8c9-d0e1-2345-fabc-678901234567';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/TeamUserMappings/${teamUserMappingId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const result = await response.json();

Response

{
  "count": 1
}

A count of 1 confirms one mapping was removed. A count of 0 means no matching mapping was found (already deleted or invalid ID).

Get Org Team Members

Returns all users who are members of the org team, including members of child teams in the hierarchy. Use the org team id from create org team or get org team by ID.

Path Parameters

Query Parameters

Example Request

Using cURL:

curl -X GET https://sandbox.custodia-tech.com/md/api/OrgTeams/a1b2c3d4-e5f6-7890-abcd-ef1234567890/allMembers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID"

Using JavaScript (fetch):

const orgTeamId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/OrgTeams/${orgTeamId}/allMembers`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const { members } = await response.json();

Response

{
  "members": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "firstname": "Alex",
      "lastname": "Rivera",
      "middlename": null,
      "suffix": null,
      "reason": "active",
      "photoId": null,
      "email": "alex.rivera@example.com",
      "employeeId": "1042",
      "subsidiaryId": null,
      "name": "Alex Rivera"
    },
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "firstname": "Jordan",
      "lastname": "Lee",
      "middlename": null,
      "suffix": null,
      "reason": "active",
      "photoId": "profile-photo-abc123.png",
      "email": "jordan.lee@example.com",
      "employeeId": null,
      "subsidiaryId": null,
      "name": "Jordan Lee"
    },
    {
      "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
      "firstname": "Sam",
      "lastname": "Taylor",
      "middlename": null,
      "suffix": null,
      "reason": "new",
      "photoId": null,
      "email": "sam.taylor@example.com",
      "employeeId": "2201",
      "subsidiaryId": null,
      "name": "Sam Taylor"
    }
  ]
}

Member fields

Org Team Fields

Summary of all fields returned by the API:

Error Responses

All endpoints may return the following error responses:

Related documentation

• Users: create and manage users in your company
• Cost center: accounting tags for spend routing
• Budget mapping: route spend by teamId
• Authentication: obtain access tokens