Import Users

POST /api/import/users

Bulk create or update users. The unique identifier is the internal user id (the Boolanga ID, returned by this endpoint’s response and by Find User by Email) — if id is included for a record, that user is updated; if id is omitted, a new user is always created.

Headers

Header	Value
api-key	Import API key
Content-Type	application/json

Request body

{
  "users": [
    {
      "id": 1071,
      "email": "john.doe@example.com",
      "uber_id": 12345,
      "first_name": "John",
      "last_name": "Doe",
      "partner_name": "Adecco",
      "agency_id": "P-12345",
      "active": 1
    }
  ]
}

Fields

Field	Type	Required	Description
id	int	no	Internal user ID (Boolanga ID) to update. Omit to create a new user. If provided but no matching user exists, the record fails.
email	string	yes	Email address — must be unique across all users
uber_id	numeric	yes	The user’s Uber ID — must be unique across all users. No longer used for matching (use id instead).
first_name	string	yes	First name
last_name	string	yes	Last name
partner_name	string	yes	Partner name (must exactly match the name stored in the database, e.g. Adecco or Randstad)
agency_id	string	no	Agency identifier — must be unique across all users
active	boolean	yes	1 = active, 0 = inactive

Success response

{
  "success": true,
  "results": {
    "created": 2,
    "updated": 1,
    "failed": [],
    "users": [
      {
        "index": 0,
        "id": 1071,
        "uber_id": "12345",
        "email": "john.doe@example.com",
        "action": "created"
      }
    ]
  }
}

results.users[].id is the internal, permanent identifier for the user in our system — referred to as the Boolanga ID. Use it (not uber_id) for any follow-up calls that need to address this specific user.

Partial success response

{
  "success": true,
  "results": {
    "created": 1,
    "updated": 0,
    "failed": [
      {
        "index": 1,
        "id": null,
        "uber_id": 99999,
        "email": "john.doe@example.com",
        "error": "Partner not found: \"Unknown Partner\"."
      }
    ],
    "users": []
  }
}

results.users field reference

Field	Type	Description
index	int	Index of this record in the request users array
id	int	The Boolanga ID — internal, permanent user identifier
uber_id	string	The uber_id submitted for this record
email	string	The user’s email
action	string	created or updated

HTTP error codes

Status	Description
401	Missing api-key header
403	Invalid api-key
422	Validation error (missing or invalid field)

Record-level errors

Error	Description
Partner not found: "..."	The given partner name does not exist in the database
User not found for id: "..."	The given id does not match any existing user
Email already belongs to a different user.	The email is already associated with a different user
uber_id already belongs to a different user.	The uber_id is already associated with a different user
agency_id already belongs to a different user.	The agency_id is already associated with a different user

Business logic

• No id provided: always creates a new user and sends a welcome email
• id provided and found: updates that record; if active changes from 0 to 1, a reactivation email is sent
• id provided but not found: the record fails, no user is created
• Records listed in failed are not saved; all other records in the batch are processed independently