---
updatedAt: 2026-04-21T16:11:36.000Z
agentTools:
  projectIndex: https://apidoc.factorialhr.com/llms.txt
---

# Teams > Membership > Bulk upserts

Subscription_type: `teams/membership/bulk_upsert`

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Factorial API",
    "description": "",
    "version": "2026-10-01"
  },
  "webhooks": {
    "Webhooks > Teams > Membership > Bulk upserts": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "description": "Subscription_type: `teams/membership/bulk_upsert`",
        "deprecated": false,
        "summary": "Teams > Membership > Bulk upserts",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Return a 200 status to indicate that the data was received successfully"
          }
        },
        "requestBody": {
          "description": "Callback payload",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/teams_membership"
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "proxy-enabled": false
  },
  "servers": [
    {
      "url": "https://api.factorialhr.com",
      "description": "Production server"
    },
    {
      "url": "https://api.demo.factorial.dev",
      "description": "Demo server (deprecated)"
    },
    {
      "url": "https://api.eu2.demo.factorial.dev",
      "description": "Demo server"
    }
  ],
  "security": [
    {
      "oauth2": []
    }
  ],
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://id.factorialhr.com/oauth/authorize",
            "tokenUrl": "https://id.factorialhr.com/api/oauth/token",
            "refreshUrl": "https://id.factorialhr.com/api/oauth/token",
            "scopes": {
              "read": "Required for all operations",
              "write": "Required for write operations",
              "approvals": "Access to approvals",
              "banking": "Access to banking",
              "company_holidays": "Access to company holidays",
              "company_legal_entities": "Access to company legal entities",
              "company_locations": "Access to company locations",
              "compensations": "Access to compensations",
              "contracts": "Access to contracts",
              "custom_fields": "Access to custom fields",
              "documents": "Access to documents",
              "employee_updates": "Access to employee updates",
              "employees": "Access to employees",
              "expenses": "Access to expenses",
              "finance": "Access to finance",
              "integrations": "Access to integrations",
              "it_management": "Access to it management",
              "job_catalog": "Access to job catalog",
              "marketplace": "Access to marketplace",
              "payroll": "Access to payroll",
              "payroll_supplements": "Access to payroll supplements",
              "performance": "Access to performance",
              "posts": "Access to posts",
              "processes": "Access to processes",
              "project_management_expenses": "Access to project management expenses",
              "project_management_projects": "Access to project management projects",
              "project_management_time": "Access to project management time",
              "recruitment": "Access to recruitment",
              "shift_management": "Access to shift management",
              "tasks": "Access to tasks",
              "time_off": "Access to time off",
              "time_tracking": "Access to time tracking",
              "trainings": "Access to trainings"
            }
          }
        }
      }
    },
    "schemas": {
      "teams_membership": {
        "type": "object",
        "required": [
          "id",
          "employee_id",
          "team_id",
          "lead",
          "source_team_ids",
          "parent_team_ids"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Membership ID",
            "example": "1"
          },
          "company_id": {
            "type": "string",
            "description": "Company ID of the membership",
            "example": "1"
          },
          "employee_id": {
            "type": "string",
            "description": "Employee ID of the membership",
            "example": "12"
          },
          "team_id": {
            "type": "string",
            "description": "Team ID of the membership",
            "example": "3"
          },
          "lead": {
            "type": "boolean",
            "description": "Whether the employee is a lead of the team or not",
            "example": true
          },
          "source_team_ids": {
            "type": "array",
            "description": "IDs of the teams this membership originates from (nested teams). In a company with nested teams, a direct membership includes the team itself; an inherited one, the sub-team(s) where the employee is a direct member. Only populated on reads that compute source attribution — reads filtered by a single team, or by a single employee with `with_source_attribution` enabled. Empty otherwise, including create, update and delete responses, and always empty for companies without nested teams. An empty array does not distinguish \"computed and genuinely empty\" from \"not computed for this read\" or \"could not be computed\", so only apply attribution-dependent logic to a read you explicitly shaped for it. A team-anchored read stops attributing above roughly a thousand members of the filtered team: past that the attribution is not computed at all and every row comes back empty, behind a normal `200`.",
            "example": [
              "3"
            ],
            "items": {
              "type": "string"
            }
          },
          "parent_team_ids": {
            "type": "array",
            "description": "IDs of the ancestor teams that receive an inherited membership through this row (nested teams) — the teams this membership rolls up into. Populated under the same conditions as `source_team_ids`; empty otherwise.",
            "example": [
              "2"
            ],
            "items": {
              "type": "string"
            }
          },
          "direct": {
            "type": "boolean",
            "description": "Whether the employee is a direct member of the team (nested teams). Always present. `true` means direct member; `false` means the row exists only through inheritance from a sub-team; `null` means not computed for this read. Computed on reads filtered by a single `team_ids` value, and on reads filtered by a single employee with `with_source_attribution` enabled — always `null` otherwise, including create, update and delete responses and companies without nested teams. `null` is also returned when directness could not be resolved for a transient reason, so never treat `null` as `false` — retry the read instead."
          }
        }
      }
    }
  }
}
```