Skip to content
SpartanAuth SpartanAuth Docs

Bulk Import Users

POST
/api/v1/sectors/{sectorID}/users/bulk-import
 
curl --request POST \
  --url https://api.spartanauth.com/api/v1/sectors/example/users/bulk-import \
  --header 'Content-Type: application/json' \
  --data '{ "users": [ { "email": "example", "name": "example", "givenName": "example", "familyName": "example", "emailVerified": true, "hashedPassword": "example", "passwordHashAlgorithm": "example", "sendInvite": true, "phoneNumber": "example", "locale": "example", "address": { "formatted": "example", "streetAddress": "example", "locality": "example", "region": "example", "postalCode": "example", "country": "example" }, "nickname": "example", "gender": "example", "birthdate": "example", "zoneinfo": "example", "website": "example", "picture": "example" } ] }'

Imports a list of users into a sector in a single request. Each record may include a full OIDC profile, an optional pre-hashed password with its algorithm, and an optional flag to send an invite email. Processing is best-effort — per-user results are returned for each entry regardless of individual failures. Requires the caller to be an admin of the sector or the default sector.

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
sectorID
required
string

Request Body

Section titled “Request Body ”
Media type application/json
object
users
Array<object>

BulkImportUser represents a single user record in a bulk import request.

object
email

Required: email address used as the user’s login identifier.

string
name

Full display name (e.g. “Jane Smith”).

string
givenName

Given (first) name.

string
familyName

Family (last) name.

string
emailVerified

Whether the email address is already verified in the source system.

boolean
hashedPassword

Pre-hashed credential from the source system (optional). Must be supplied together with password_hash_algorithm. Currently only “bcrypt” hashes can be verified at login; hashes with other algorithms are stored but login will fail until the algorithm is added to the verification pipeline. In that case, set send_invite=true so the user receives an invite email to set a new password.

string
passwordHashAlgorithm

Algorithm used to produce hashed_password (e.g. “bcrypt”, “argon2id”, “scrypt”). Required when hashed_password is non-empty.

string
sendInvite

When true, send an invite email to this user after the profile is created. Ignored when hashed_password is also set (the account is immediately usable).

boolean
phoneNumber

Additional OIDC standard profile fields.

string
locale
string
address
object
formatted
string
streetAddress
string
locality
string
region
string
postalCode
string
country
string
nickname
string
gender
string
birthdate
string
zoneinfo
string
website
string
picture
string
Example generated
{
  "users": [
    {
      "email": "example",
      "name": "example",
      "givenName": "example",
      "familyName": "example",
      "emailVerified": true,
      "hashedPassword": "example",
      "passwordHashAlgorithm": "example",
      "sendInvite": true,
      "phoneNumber": "example",
      "locale": "example",
      "address": {
        "formatted": "example",
        "streetAddress": "example",
        "locality": "example",
        "region": "example",
        "postalCode": "example",
        "country": "example"
      },
      "nickname": "example",
      "gender": "example",
      "birthdate": "example",
      "zoneinfo": "example",
      "website": "example",
      "picture": "example"
    }
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

A successful response.

Media type application/json
object
results

Per-user results in the same order as the input list.

Array<object>

BulkImportUserResult is the per-user outcome included in BulkImportUsersResponse.

object
email

The email address from the submitted BulkImportUser record.

string
sub

Subject identifier assigned to the created profile (empty on error or skip).

string
status

One of: “created”, “skipped” (email already exists), “error”.

string
errorMessage

Human-readable error description when status is “error”.

string
total

Summary counts.

integer format: int32
created
integer format: int32
skipped
integer format: int32
errors
integer format: int32
Example generated
{
  "results": [
    {
      "email": "example",
      "sub": "example",
      "status": "example",
      "errorMessage": "example"
    }
  ],
  "total": 1,
  "created": 1,
  "skipped": 1,
  "errors": 1
}

default

Section titled “default ”

An unexpected error response.

Media type application/json
object
code
integer format: int32
message
string
details
Array<object>
object
@type
string
key
additional properties
Example generated
{
  "code": 1,
  "message": "example",
  "details": [
    {
      "@type": "example"
    }
  ]
}