{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "User Provisioning",
    "description" : "Basepom for all HubSpot Projects",
    "version" : "v3",
    "x-hubspot-product-tier-requirements" : {
      "marketing" : "FREE",
      "sales" : "FREE",
      "service" : "FREE",
      "cms" : "FREE",
      "commerce" : "FREE",
      "crmHub" : "FREE",
      "dataHub" : "FREE"
    },
    "x-hubspot-api-use-case" : "You manage employee access data in a system outside of HubSpot, and you want to ensure that specific users are dynamically allocated to the right teams in your HubSpot account.",
    "x-hubspot-related-documentation" : [ {
      "name" : "User Provisioning Guide",
      "url" : "https://developers.hubspot.com/docs/guides/api/settings/users/user-provisioning"
    } ],
    "x-hubspot-introduction" : "Use the user provisioning API to create and manage users in your HubSpot account, along with their associated teams and roles."
  },
  "servers" : [ {
    "url" : "https://api.hubapi.com"
  } ],
  "tags" : [ {
    "name" : "Basic"
  }, {
    "name" : "Roles"
  }, {
    "name" : "Teams"
  }, {
    "name" : "Users"
  } ],
  "paths" : {
    "/settings/users/v3" : {
      "get" : {
        "tags" : [ "Basic" ],
        "operationId" : "get-/settings/users/v3_/settings/users/v3",
        "parameters" : [ {
          "name" : "after",
          "in" : "query",
          "required" : false,
          "style" : "form",
          "explode" : true,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        }, {
          "name" : "limit",
          "in" : "query",
          "required" : false,
          "style" : "form",
          "explode" : true,
          "schema" : {
            "type" : "integer",
            "format" : "int32",
            "example" : null
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/CollectionResponsePublicUserForwardPaging"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "crm.objects.users.read" ]
        }, {
          "oauth2" : [ "settings.users.read" ]
        } ]
      },
      "post" : {
        "tags" : [ "Basic" ],
        "operationId" : "post-/settings/users/v3_/settings/users/v3",
        "parameters" : [ ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/UserProvisionRequest"
              },
              "example" : null
            }
          },
          "required" : true
        },
        "responses" : {
          "201" : {
            "description" : "successful operation",
            "headers" : {
              "Location" : {
                "description" : "URL of the newly created resource",
                "style" : "simple",
                "explode" : false,
                "schema" : {
                  "type" : "string",
                  "example" : null
                }
              }
            },
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/PublicUser"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "settings.users.write" ]
        }, {
          "oauth2" : [ "crm.objects.users.write" ]
        } ]
      }
    },
    "/settings/v3/users/roles" : {
      "get" : {
        "tags" : [ "Roles" ],
        "summary" : "Retrieves the roles on an account",
        "description" : "Retrieves the roles on an account",
        "operationId" : "get-/settings/v3/users/roles_getAll",
        "parameters" : [ ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/CollectionResponsePublicPermissionSetNoPaging"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "crm.objects.users.read" ]
        }, {
          "oauth2" : [ "settings.users.read" ]
        } ]
      }
    },
    "/settings/v3/users/teams" : {
      "get" : {
        "tags" : [ "Teams" ],
        "summary" : "See details about this account's teams",
        "description" : "View teams for this account",
        "operationId" : "get-/settings/v3/users/teams_getAll",
        "parameters" : [ ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/CollectionResponsePublicTeamNoPaging"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "settings.users.teams.read" ]
        } ]
      }
    },
    "/settings/v3/users/{userId}" : {
      "get" : {
        "tags" : [ "Users" ],
        "summary" : "Retrieves a user",
        "description" : "Retrieves a user identified by `userId`. `userId` refers to the user's ID by default, or optionally email as specified by the `IdProperty` query param.",
        "operationId" : "get-/settings/v3/users/{userId}_getById",
        "parameters" : [ {
          "name" : "userId",
          "in" : "path",
          "description" : "",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        }, {
          "name" : "idProperty",
          "in" : "query",
          "description" : "",
          "required" : false,
          "style" : "form",
          "explode" : true,
          "schema" : {
            "type" : "string",
            "example" : null,
            "enum" : [ "EMAIL", "USER_ID" ]
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/PublicUser"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "crm.objects.users.read" ]
        }, {
          "oauth2" : [ "settings.users.read" ]
        } ]
      },
      "put" : {
        "tags" : [ "Users" ],
        "summary" : "Modifies a user",
        "description" : "Modifies a user identified by `userId`. `userId` refers to the user's ID by default, or optionally email as specified by the `IdProperty` query param.",
        "operationId" : "put-/settings/v3/users/{userId}_update",
        "parameters" : [ {
          "name" : "userId",
          "in" : "path",
          "description" : "",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        }, {
          "name" : "idProperty",
          "in" : "query",
          "description" : "",
          "required" : false,
          "style" : "form",
          "explode" : true,
          "schema" : {
            "type" : "string",
            "example" : null,
            "enum" : [ "EMAIL", "USER_ID" ]
          }
        } ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/PublicUserUpdate"
              },
              "example" : null
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/PublicUser"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "settings.users.write" ]
        }, {
          "oauth2" : [ "crm.objects.users.write" ]
        } ]
      },
      "delete" : {
        "tags" : [ "Users" ],
        "summary" : "Removes a user",
        "description" : "Removes a user identified by `userId`. `userId` refers to the user's ID by default, or optionally email as specified by the `IdProperty` query param.",
        "operationId" : "delete-/settings/v3/users/{userId}_archive",
        "parameters" : [ {
          "name" : "userId",
          "in" : "path",
          "description" : "",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        }, {
          "name" : "idProperty",
          "in" : "query",
          "description" : "",
          "required" : false,
          "style" : "form",
          "explode" : true,
          "schema" : {
            "type" : "string",
            "example" : null,
            "enum" : [ "EMAIL", "USER_ID" ]
          }
        } ],
        "responses" : {
          "204" : {
            "description" : "No content",
            "content" : { }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "settings.users.write" ]
        }, {
          "oauth2" : [ "crm.objects.users.write" ]
        } ]
      }
    }
  },
  "components" : {
    "schemas" : {
      "CollectionResponsePublicPermissionSetNoPaging" : {
        "required" : [ "results" ],
        "type" : "object",
        "properties" : {
          "results" : {
            "type" : "array",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/PublicPermissionSet"
            }
          }
        },
        "example" : null
      },
      "CollectionResponsePublicTeamNoPaging" : {
        "required" : [ "results" ],
        "type" : "object",
        "properties" : {
          "results" : {
            "type" : "array",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/PublicTeam"
            }
          }
        },
        "example" : null
      },
      "CollectionResponsePublicUserForwardPaging" : {
        "required" : [ "results" ],
        "type" : "object",
        "properties" : {
          "paging" : {
            "$ref" : "#/components/schemas/ForwardPaging"
          },
          "results" : {
            "type" : "array",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/PublicUser"
            }
          }
        },
        "example" : null
      },
      "Error" : {
        "required" : [ "category", "correlationId", "message" ],
        "type" : "object",
        "properties" : {
          "category" : {
            "type" : "string",
            "description" : "The error category",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "type" : "string",
                "example" : null
              }
            },
            "description" : "Context about the error condition",
            "example" : "{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}"
          },
          "correlationId" : {
            "type" : "string",
            "description" : "A unique identifier for the request. Include this value with any error reports or support tickets",
            "format" : "uuid",
            "example" : "aeb5f871-7f07-4993-9211-075dc63e7cbf"
          },
          "errors" : {
            "type" : "array",
            "description" : "further information about the error",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/ErrorDetail"
            }
          },
          "links" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "string",
              "example" : null
            },
            "description" : "A map of link names to associated URIs containing documentation about the error or recommended remediation steps",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate",
            "example" : "An error occurred"
          },
          "subCategory" : {
            "type" : "string",
            "description" : "A specific category that contains more specific detail about the error",
            "example" : null
          }
        },
        "description" : "Represents an error response returned by the API when an operation fails. This component is used in various endpoints to provide detailed information about the error encountered.",
        "example" : {
          "message" : "Invalid input (details will vary based on the error)",
          "correlationId" : "aeb5f871-7f07-4993-9211-075dc63e7cbf",
          "category" : "VALIDATION_ERROR",
          "links" : {
            "knowledge-base" : "https://www.hubspot.com/products/service/knowledge-base"
          }
        }
      },
      "ErrorDetail" : {
        "required" : [ "message" ],
        "type" : "object",
        "properties" : {
          "code" : {
            "type" : "string",
            "description" : "The status code associated with the error detail",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "type" : "string",
                "example" : null
              }
            },
            "description" : "Context about the error condition",
            "example" : "{missingScopes=[scope1, scope2]}"
          },
          "in" : {
            "type" : "string",
            "description" : "The name of the field or parameter in which the error was found.",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate",
            "example" : null
          },
          "subCategory" : {
            "type" : "string",
            "description" : "A specific category that contains more specific detail about the error",
            "example" : null
          }
        },
        "description" : "Represents detailed information about an error that occurred in the API. This component is used to provide additional context and specifics about errors, typically as part of an error response.",
        "example" : null
      },
      "ForwardPaging" : {
        "type" : "object",
        "properties" : {
          "next" : {
            "$ref" : "#/components/schemas/NextPage"
          }
        },
        "description" : "Paging information for forward-only pagination. Contains the next page reference when more results are available; omitted or empty on the last page.",
        "example" : null
      },
      "NextPage" : {
        "required" : [ "after" ],
        "type" : "object",
        "properties" : {
          "after" : {
            "type" : "string",
            "description" : "A paging cursor token for retrieving subsequent pages.",
            "example" : null
          },
          "link" : {
            "type" : "string",
            "description" : "A URL that can be used to retrieve the next page results.",
            "example" : null
          }
        },
        "description" : "Specifies the paging information needed to retrieve the next set of results in a paginated API response",
        "example" : null
      },
      "PublicPermissionSet" : {
        "required" : [ "id", "name", "requiresBillingWrite" ],
        "type" : "object",
        "properties" : {
          "id" : {
            "type" : "string",
            "description" : "The role's unique ID",
            "example" : null
          },
          "name" : {
            "type" : "string",
            "description" : "The role's name",
            "example" : null
          },
          "requiresBillingWrite" : {
            "type" : "boolean",
            "description" : "Whether this role has a paid seat and requires the billing-write scope to assign/unassign to users",
            "example" : null
          }
        },
        "example" : null
      },
      "PublicTeam" : {
        "required" : [ "id", "name", "secondaryUserIds", "userIds" ],
        "type" : "object",
        "properties" : {
          "id" : {
            "type" : "string",
            "description" : "The team's unique ID",
            "example" : null
          },
          "name" : {
            "type" : "string",
            "description" : "The team's name",
            "example" : null
          },
          "secondaryUserIds" : {
            "type" : "array",
            "description" : "Secondary or additional members of this team",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "userIds" : {
            "type" : "array",
            "description" : "Primary members of this team",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          }
        },
        "example" : null
      },
      "PublicUser" : {
        "required" : [ "email", "id", "roleIds", "superAdmin" ],
        "type" : "object",
        "properties" : {
          "email" : {
            "type" : "string",
            "description" : "The user's email.",
            "example" : null
          },
          "firstName" : {
            "type" : "string",
            "description" : "The user's first name.",
            "example" : null
          },
          "id" : {
            "type" : "string",
            "description" : "The user's unique ID.",
            "example" : null
          },
          "lastName" : {
            "type" : "string",
            "description" : "The user's last name.",
            "example" : null
          },
          "primaryTeamId" : {
            "type" : "string",
            "description" : "The user's primary team",
            "example" : null
          },
          "roleId" : {
            "type" : "string",
            "description" : "The user's role.",
            "example" : null
          },
          "roleIds" : {
            "type" : "array",
            "description" : "A list of role IDs assigned to the user.",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "seatNames" : {
            "type" : "array",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "secondaryTeamIds" : {
            "type" : "array",
            "description" : "The user's additional teams.",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "sendWelcomeEmail" : {
            "type" : "boolean",
            "description" : "Whether a welcome email was sent to the user. This value will only be populated in response to a provisioning request. Subsequent queries will be false.",
            "example" : null
          },
          "superAdmin" : {
            "type" : "boolean",
            "description" : "Whether the user has super admin privileges.",
            "example" : null
          }
        },
        "example" : null
      },
      "PublicUserUpdate" : {
        "type" : "object",
        "properties" : {
          "firstName" : {
            "type" : "string",
            "description" : "The first name of the user.",
            "example" : null
          },
          "lastName" : {
            "type" : "string",
            "description" : "The last name of the user.",
            "example" : null
          },
          "primaryTeamId" : {
            "type" : "string",
            "description" : "The user's primary team.",
            "example" : null
          },
          "roleId" : {
            "type" : "string",
            "description" : "The user's role.",
            "example" : null
          },
          "seatNames" : {
            "type" : "array",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "secondaryTeamIds" : {
            "type" : "array",
            "description" : "The user's additional teams.",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          }
        },
        "example" : null
      },
      "UserProvisionRequest" : {
        "required" : [ "email", "sendWelcomeEmail" ],
        "type" : "object",
        "properties" : {
          "email" : {
            "type" : "string",
            "description" : "The user's email.",
            "example" : null
          },
          "firstName" : {
            "type" : "string",
            "description" : "The user's first name.",
            "example" : null
          },
          "lastName" : {
            "type" : "string",
            "description" : "The user's last name.",
            "example" : null
          },
          "primaryTeamId" : {
            "type" : "string",
            "description" : "The user's primary team.",
            "example" : null
          },
          "roleId" : {
            "type" : "string",
            "description" : "The user's role.",
            "example" : null
          },
          "seatNames" : {
            "type" : "array",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "secondaryTeamIds" : {
            "type" : "array",
            "description" : "The user's additional teams.",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "sendWelcomeEmail" : {
            "type" : "boolean",
            "description" : "Whether to send a welcome email.",
            "example" : null
          }
        },
        "example" : null
      }
    },
    "responses" : {
      "Error" : {
        "description" : "An error occurred.",
        "content" : {
          "*/*" : {
            "schema" : {
              "$ref" : "#/components/schemas/Error"
            },
            "example" : null
          }
        }
      }
    },
    "securitySchemes" : {
      "developer_hapikey" : {
        "type" : "apiKey",
        "name" : "hapikey",
        "in" : "query"
      },
      "oauth2" : {
        "type" : "oauth2",
        "flows" : {
          "authorizationCode" : {
            "authorizationUrl" : "https://app.hubspot.com/oauth/authorize",
            "tokenUrl" : "https://api.hubapi.com/oauth/v1/token",
            "scopes" : {
              "crm.objects.users.read" : "",
              "crm.objects.users.write" : "",
              "settings.users.read" : "",
              "settings.users.teams.read" : "",
              "settings.users.write" : ""
            }
          }
        }
      },
      "private_apps" : {
        "type" : "apiKey",
        "name" : "private-app",
        "in" : "header"
      },
      "private_apps_legacy" : {
        "type" : "apiKey",
        "name" : "private-app-legacy",
        "in" : "header"
      }
    }
  },
  "x-hubspot-available-client-libraries" : [ "Node", "Python", "Ruby", "PHP" ],
  "x-hubspot-product-tier-requirements" : {
    "marketing" : "FREE",
    "sales" : "FREE",
    "service" : "FREE",
    "cms" : "FREE",
    "commerce" : "FREE",
    "crmHub" : "FREE",
    "dataHub" : "FREE"
  }
}