Create User
Use this API to create a new user in OneLogin.
Early Preview
This API is in early preview and may be subject to change.
Users can be created with a password specified or without one. In the case where a password is not set the user will be created with a status of 7 (Password Pending) and they will not be able to login.
An invite email is not sent when users are created via this API.
Mappings
By default mappings will be run after the response for this API is returned. If you’re relying on mappings to update a user value and you want that in the response then set the mappings query parameter to sync.
Resource URL
https://<api-domain>/api/2/users
Header Parameters
Authorization required string |
Set to Set The access token must have been generated using an API credential pair created using the scope required to call this API. This API can be called using any one of the following scopes: |
Content-Type required string |
Set to application/json . |
Query Parameters
mappings | Controls how mappings will be applied to the user on creation.
Defaults to async
async: Mappings will be run after the API returns a response |
validate_policy | Will passwords be validated against the User Policy?
Defaults to true |
Request Parameters
You must have either a username, email or both set as the minimum requirement for creating a user.
username
required |
string | A username for the user |
email
required |
string | A valid email for the user |
firstname | string | The users first name |
lastname | string | The users last name |
password | string | The password to set for a user. |
password_confirmation | string | Required if the password is being set |
password_algorithm | string | Only use this when importing a password has already been hashed.
salt+sha256 b​crypt |
salt | string | The salt value that was used with the password_algorithm. |
title | string | The users job title |
department | string | The users department |
company | string | The company the user belongs to |
comment | string | Free text related to the user |
group_id | integer | The ID of the Group in OneLogin that the user will be assigned to |
role_ids | array | A list of OneLogin Role IDs the user will be assigned to. |
phone | string | The E.164 format phone number for a user. |
state | integer |
0: Unapproved 1: Approved 2: Rejected 3: Unlicensed |
status | integer |
0: Unactivated 1: Active 2: Suspended 3: Locked 4: Password expired 5: Awaiting password reset 7: Password Pending 8: Security questions required |
directory_id | integer | The ID of the OneLogin Directory the user will be assigned to |
trusted_idp_id | integer | The ID of the OneLogin Trusted IDP the user will be assigned to |
manager_ad_id | integer | The ID of the users manager in Active Directory |
manager_user_id | integer | The OneLogin User ID of the users manager |
samaccountname | string | The users Active Directory username |
member_of | string | The users directory membership |
userprincipalname | string | The principle name of the user |
distinguished_name | string | The distinguished name of the user |
external_id | string | The ID of the user in an external directory |
Sample Request Body
Create a user with minimum required fields
{
"username":"min.requirements"
}
or
{
"email":"min.requirements@onelogin.com"
}
Create a user with password and custom attribute value.
{
"firstname":"Happy",
"lastname":"Gilmore",
"username":"happy.gilmore",
"password": "helloworld123",
"password_confirmation": "helloworld123",
"custom_attributes": {
"food": "pizza"
}
}
Create a user without a password
{
"email": "chacha@oneloginc.com",
"department": "Fish Tank Cleaners",
"company": "Tropical Fish World",
"username": "chacha",
"title": "Cleaner",
"comment": "This is a comment",
"group_id": 461331,
"role_ids": [272445],
"custom_attributes": {
"employeenumber": "Z88765543",
"food": "Sushi"
},
"invalid_login_attempts": 0,
"phone": "+1555987654",
"manager_user_id": null,
"samaccountname": "chacha.ad",
"directory_id": null,
"lastname": "Cha",
"userprincipalname": "chacha.principle",
"distinguished_name": "sir.chacha",
"external_id": "z9876",
"firstname": "Cha"
}
Sample Response
- 201 Created
- 400 Bad Request
- 401 Unauthorized
- 422 Unprocessable Entity
{
"created_at": "2020-07-16T03:29:41.420Z",
"id": 87735981,
"state": 1,
"department": null,
"email": null,
"last_login": null,
"password_changed_at": "2020-07-16T03:29:41.377Z",
"preferred_locale_code": null,
"firstname": "Scuba",
"status": 1,
"userprincipalname": null,
"title": null,
"role_ids": [],
"custom_attributes": {
"food": null,
"employeenumber": null
},
"lastname": "Steve",
"updated_at": "2020-07-16T03:29:41.420Z",
"member_of": null,
"phone": null,
"company": null,
"username": "scuba.steve",
"manager_ad_id": null,
"activated_at": null,
"samaccountname": null,
"directory_id": null,
"external_id": null,
"group_id": null,
"invalid_login_attempts": 0,
"invitation_sent_at": null,
"trusted_idp_id": null,
"comment": null,
"distinguished_name": null,
"locked_until": null,
"manager_user_id": null
}
{
"message": "unknown attribute: employee_number",
"name": "BadRequestError",
"statusCode": 400
}
Typically, this error means that your access token value is invalid.
{
"message": "Unauthorized",
"name": "UnauthorizedError",
"statusCode": 401
}
{
"message": "Validation failed: Username must be unique within {subdomain}",
"name": "UnprocessableEntityError",
"statusCode": 422
}
{
"message": "Validation failed: Your new password and confirmation password do not match",
"name": "UnprocessableEntityError",
"statusCode": 422
}
Postman Collection
Replace sample variables indicated by < >
in the sample request body with your actual values. Also, be sure to set Postman-specific environment variables indicated by {{ }}
.
Download for the Users API
Sample Code
cURL
Replace sample values indicated by < >
with your actual values.
curl 'https://<api-domain>/api/2/users' \
-X POST \
-H "Authorization: bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"firstname":"<firstname>",
"lastname":"<lastname>",
"email":"<email>",
"username":"<username>"
}'
Have a Question?

Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.

Found a bug? Submit a support ticket.

Have a product idea or request? Share it with us in our Ideas Portal.