User Membership

Add a User to Multiple Tenants

This endpoint is used to add a user to multiple tenants in one call.

A custom profile can also be supplied for each tenant. This profile will be merged with the user's main profile when sending to the user with that tenant.

URL: https://api.courier.com/users/:user_id/tenants

Method: PUT

Path Parameters:

user_idstringrequired

Id of the user to be added to the supplied tenants

Body:

tenantsUserTenantAssociation

A list of tenants the user a member of.

+ Show user tenant association type

Example:

PUT /users/john/tenants

{
  "tenants": [
    {
      "tenant_id": "acme",
      "profile": {
        "email": "john@acme.com",
      }
    },
    {
      "tenant_id": "bizcorp",
      "profile": {
        "email": "john@bizcorp.com",
      }
    },
  ]
}

Response:

status: 204

Add a User to a Single Tenant

This endpoint is used to add a single tenant.

A custom profile can also be supplied with the tenant. This profile will be merged with the user's main profile when sending to the user with that tenant.

URL: https://api.courier.com/users/:user_id/tenants/:tenant_id

Method: PUT

Path Parameters:

user_idstringrequired

Id of the user to be added to the supplied tenant.

tenant_idstringrequired

Id of the tenant the user should be added to.

Body:

profileProfile

A profile to merge with the main user profile when sending via this tenant.

+ Show profile type

Example:

PUT /users/john/tenants/acme

{
  "profile": {
    "email": "john@acme.com",
  }
}

Response:

status: 204

Remove User From All Associated Tenants

Removes a user from any tenants they may have been associated with.

URL: https://api.courier.com/users/:user_id/tenants

Method: DELETE

Path Parameters:

user_idstringrequired

Id of the user to be removed from all tenants.

Example:

DELETE /users/john/tenants

Response:

status: 204

Remove User from a Tenant

Removes a user from the supplied tenant.

URL: https://api.courier.com/users/:user_id/tenants/:tenant_id

Method: DELETE

Path Parameters:

user_idstringrequired

Id of the user to be removed from the supplied tenant.

tenant_idstringrequired

Id of the tenant the user should be removed from.

Example:

DELETE /users/john/tenants/acme

Response:

status: 204

Get tenants associated with a given user

Returns a paginated list of user tenant associations.

URL: https://api.courier.com/users/:user_id/tenants

Method: GET

Path Parameters:

user_idstringrequired

Id of the user to retrieve all associated tenants for.

Query Parameters

limitnumber

The number of accounts to return (defaults to 20, maximum value of 100)

starting_afterstring

Value of next_page from previous response

Response Body:

itemsarray<UserTenantAssociation>

An array of user tenant associations.

+ Show user tenant association type

has_moreboolean

Set to true when there are more pages that can be retrieved.

urlstring

A url that may be used to generate these results.

next_urlstring?

A url that may be used to generate fetch the next set of results. Defined only whenhas_more is set to true

cursorstring?

A pointer to the next page of results. Defined only whenhas_more is set to true

type"list"

Always set to "list". Represents the type of this object.

Example:

GET /users/john/tenants

Response:

status: 200

{
  "has_more": false,
  "items": [
    {
      "tenant_id": "acme",
      "profile": {
        "role": "admin"
      },
      "user_id": "john"
    },
    {
      "tenant_id": "biggle",
      "profile": {
        "role": "normal"
      },
      "user_id": "john"
    },
    {
      "tenant_id": "example",
      "profile": {
        "role": "guest"
      },
      "user_id": "john"
    }
  ],
  "type": "list"
}

Get a User Tenant Association

Returns the details of a user's membership with the supplied tenant.

URL: https://api.courier.com/users/:user_id/tenants/:tenant_id

Method: GET

Path Parameters:

user_idstringrequired

Id of the user to retrieve tenant details for.

tenant_idstringrequired

Id of the tenant to retrieve details for.

Response Body:

user_idstringrequired

User id the association is tied to.

tenant_idstringrequired

Tenant id the association is tied to.

profileProfile

A profile merged with the main user profile when sending via this tenant.

+ Show profile type

Example:

GET /users/john/tenants/acme

Response:

status: 200

{
  "tenant_id": "acme",
  "profile": {
    "role": "admin"
  },
  "user_id": "john"
}