Create or Update User with multiple organization memberships?

Hi @panning,, great question and something I've run into a number of times over the years. The short answer to your question is no, you can't add multiple orgs to a user in the Create or Update User API. Instead, we point you to the Organization Memberships API, which is obviously not ideal.

I do have a slightly easier option than the Organization Memberships API, although it isn't really something that we acknowledge as a "feature". Basically what you do is make a request to Create or Update User for each organization that the user belongs to and you just pass in the name of the next organization that you want to add the user to and it and the update will function as a PATCH instead of a PUT, appending the new org to the user's org list. 

Some things to keep in mind with this:

1. This behaves differently than passing in `organization_id: 12345`, as this will replace the organization that exists.

2. The org must exist before you add the user in this way. If the org doesn't exist, no changes are made to the user, so any existing orgs will remain as is.

I'm leaving this as the last option as this is not a documented attribute, however I did test this and it works for me. Because it is not documented, I really can't guarantee the functionality of this down the road, but it does seem to work without issue:

If you pass in the attribute `"organization_ids":`, you can add an array of organization IDs, which will replace all of then user's existing organizations. If you include this attribute and pass in an empty array, it will remove all of that user's organizations. Additionally, when you pass in an array for a user who either doesn't yet exist or has no orgs, it seems to set the default organization as the first alphabetical org, not by the first organization ID that you pass into the array. 

I want to really stress that the last one seems to be completely fine, but it is a shot in the dark, so I'm going to reach out to the team that owns this endpoint to see if we can get it officially documented and supported. For now, proceed with caution just in case there are situations that I didn't account for.

Thanks for the workarounds @greg29 It kind of seems like multiple organization memberships are an afterthought and not really supported well in the various user API's (I can list a few deficiencies in this regard). 

For the first option, do you pass all other user fields and just change the `organization.name` with each request, or only submit email/external_id with the `organization`? And how does it know when to remove an org membership? (I would expect this option to only support additions.)

For the last option, other than new users, is the first ID in the `organization_ids` array considered the "default"? (At least that's what I feel you are eluding to..)

You're definitely correct that organizations and memberships don't have the seemingly-obvious options that you would want from an API and it's something that I've been personally chasing for years. There have definitely been improvements, we're just not all the way there yet.

For the first option...

For this, you only need to pass in the `"organization": {"name": "foo"}` object for the update, everything else about the user will remain unchanged. You did identify a shortcoming with this method that I hadn't considered, which would be removing the user's org membership, as you would not be able to do that here. Removing it via the Organization Memberships API would be the way to go, but I'll put an * here for the next part...

For the last option...

In this scenario, when you are doing a Create or Update, the ordering of the organizations isn't taken into account and it just defaults to the first alphabetical organization name. A solution for this might be a two-step process: first time, pass in only the `organization_id` that you want to set as the default and then follow that up with the full list list of `organization_id`'s (including the first one). Since the default org will have already been set, there doesn't need to be any "alphabetical guessing" as to what needs to be default, so it will just add those as additional orgs.

Coming back to the * from above and related directly to this last part, I did find out that we are in the process of publishing documentation that will outline the behavior that I noted wasn't documented. This means that this is a supported feature, I just don't have the full breadth of how it will work at this point. I have seen discussion that passing in only `organization_id` (singular, not an array) will only replace the default organization, but that one isn't as clear to me at the moment, so I want to wait until we have everything documented before I say it will do that.

Let me know if I can help out with anything else in this area.

Humm... would it be possible to include both `organization_id` (the default org) and `organization_ids` (all org memberships) in the same request?? Similar to how the example shows both an `email` (primary?) and `identities` (for other addresses).