Create/Update User (upsert)

An overview of the Create/Update User endpoint

Endpoint Description

This endpoint allows you to create or update a company users.

HTTP Method

POST /api/v2/users/{companyId}

Request

Headers:

• Content-Type: application/json - Specifies that the request body format is JSON.

• Accept: application/json - Indicates that the client expects a JSON response.

• Authorization: Bearer {token} - A valid Bearer token must be provided to authenticate the request.

URL Parameters

• companyId (integer, required): The id of the company (subscription) to create or update Users data. Example: 1234

Query Parameters:

• client_id (string): A unique identifier for the user from the integration partner system. This ID must be unique within R1 Discover. (ex. R1-TechPartnerCode-SharedClientCode-0001). If it doesn't match it a new user will be created.

• username (string): The global username for the user. This must be unique across the R1 Discover system, see the Check Global Username Availability endpoint. You may also leave this blank and the system will autogenerate a username.

• company_username (string, optional): A specific username tied to this company, if different from the general username. If a company wants their users to a have speciic username. Must be unique within the company account, see Check Company Username Availability endpoint.

• first_name (string, optional): The first name of the user. Example: John

• last_name (string, optional): The last name of the user. Example: Doe

• initial_password (string, optional): The initial password for the user account. It should meet the system's security requirements for complexity (Number, Upper/Lower Case, Special Character, 8+ Characters). System will auto-generate if left blank.

• client_email (string, optional): The email address of the user, STRONGLY RECOMMENDED, but not required. System will return a password in the response if an email is not included.

• client_location (string): The primary location of the user within the company. See List Company Locations.

• client_program (string): The program to which the user is assigned. See List Company Programs.

• client_practitioner (string): The email address of the practitioner aligned to the user, overseeing their activities and progress. See List Company Practitioners.

• client_status (string): Indicates whether the user account is active or inactive.

Request Examples

Bash

curl --request POST \
    "https://api.r1learning.com/api/v2/users/1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Authorization: Bearer {token}" \
    --data "{
    \"client_id\": \"r1-user-123456-01\",
    \"username\": \"user123\",
    \"company_username\": \"user123\",
    \"first_name\": \"John\",
    \"last_name\": \"Doe\",
    \"client_email\": \"[email protected]\",
    \"client_location\": \"AZ Treatment Center\",
    \"client_program\": \"Virtual Outatient\",
    \"client_practitioner\": \"[email protected]\",
    \"client_status\": \"active\"
}"

JavaScript

const url = new URL(
    "https://api.r1learning.com/api/v2/users/1"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

let body = {
    "client_id": "r1-user-123456-01",
    "username": "user123",
    "company_username": "user123",
    "first_name": "John",
    "last_name": "Doe",
    "client_email": "[email protected]",
    "client_location": "AZ Treatment Center",
    "client_program": "Virtual Outatient",
    "client_practitioner": "[email protected]",
    "client_status": "active"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

C# - Http

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.r1learning.com/api/v2/users/1");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer {token}");
var content = new StringContent("{\"client_id\":\"r1-user-123456-01\",\"username\":\"user123\",\"company_username\":\"user123\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"client_email\":\"[email protected]\",\"client_location\":\"AZ Treatment Center\",\"client_program\":\"Virtual Outatient\",\"client_practitioner\":\"[email protected]\",\"client_status\":\"active\"}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response

Data Dictionary:

• id (integer): The unique id of the user within the R1 Discover platform.

• client_id (string): The unique identifier for the user from the integration partner system.

• username (string): The global R1 Discover username for the user.

• company_username (string): A specific username tied to this company, if different from the general username. If a company wants their users to a have specific username, a special login page can be established for users to use the unique id. .

• first_name (string): The first name of the user. Example: John

• last_name (string): The last name of the user. Example: Doe

• initial_password (string): The initial password for the user account. It will only display if an email was not provided for the user. This must be shared with the user so they can access their account.

• client_email (string): The email address of the user. If email is not provided the system will return a password in the response, otherwise it will be sent to the specified email.

• location (string): The location where the user is aligned.

• program (string): The program where the user is aligned.

• practitioner (strong): The email of the practitioner aligned to the user

• status (string): Indicates the user license status (active/inactive)

Response Examples

200: OK

{
    "error": 0,
    "message": "User created successfully",
    "data": {
        "id": 67890,
        "unique_id": "abcxyz123456",
        "username": "johndoe",
        "company_username": "johndoe_company",
        "first_name": "John",
        "last_name": "Doe",
        "client_email": "[email protected]"
    }
}

201: OK

{
    "error": 0,
    "message": "User updated successfully!",
    "data": [
        {
            "id": 123456,
            "unique_id": "test-user-1234",
            "username": "user123456",
            "company_username": "",
            "first_name": "User",
            "last_name": "Example",
            "email": "[email protected]",
            "location": "Sample Location",
            "practitioner": "[email protected]",
            "program": "Sample Program",
            "status": "active"
        }
    ]
}
 

401: Unauthorized

{
    "error": 1,
    "message": "Unauthenticated",
    "details": "Authentication is required to access this resource."
}

403: Unauthorized

{
    "error": 1,
    "message": "Unauthorized",
    "details": "You do not have the necessary permissions to perform this action."
}

Postman Link

https://www.postman.com/fbomher/r1-discover-api/request/s1jutnf/create-update-userwww.postman.com

Link to the endpoint in Postman.

Notes

• Authorization Required: Ensure the provided Bearer token is valid and has sufficient privileges to access the endpoint.