Person update request (Object)

An update request is a JSON object to create, update or delete a person.

Deleting a person

The payload’s properties are:

action	Value: Delete	string, Mandatory
cid	The company ID of the person. You need to specify this value.	int, Mandatory
pid, login, email	Use any of these three properties to uniquely identify the person to delete. The system will select in this order of priority: pid, then login, then email. pid: The unique person ID. An integer. login: The login of the person. This only works if the person actually was assigned a login in the first place. email: The email of the person. Please note that Wordbee does not enforce unique emails! Examples: CODE `{ "pid": 1000 } or { "login": "john.hauser" } or { "email": "john@hauser.me" }`	int?, string?, string? Mandatory
data	An optional free-text information. It will be returned with the results for your convenience.	string, Optional

Example:

CODE

{
    "action": "Delete",
    "pid": 677,
    "cid": 537,
    "data": "just a test"
}

Creating a person

The payload’s properties are:

action	Value: Create	string, Mandatory
cid	The company ID of the person. You need to specify this value.	int, Mandatory
email	The mandatory email.	string, Mandatory
login	An optional login. Only specify if you want this user to be able to login. Note that no password will be assigned at this stage.	string?, Optional
fname	First name.	string, Mandatory
lname	Last name.	string, Mandatory
title	Optional title of person, such as “Dr.”, “Mrs.” etc.	string?, Optional
role	Optional role of the person, such as “Manager”.	string?, Optional
code	Optional name abbreviation. If not specified, the system automatically picks the initial letters of first and last name. “John Good” => “JG”	string?, Optional
phone	Optional phone number.	string?, Optional
phoneMobile	Optional mobile phone number.	string?, Optional
comments	Optional internal comments.	string?, Optional
timezone	Optional time zone. If not specified then the person inherits the time zone of the company to which he/she is attached (recommended). To enumerate available time zones see: settings/timezones/codes	string?, Optional
cfs	Optional person-level custom fields. It contains a collection of custom fields. Example: CODE `"cfs": [ { "id": 10, "v": "myvalue" }, { "t": "My field", "v": "myvalue" } ]` You can reference custom fields by their numeric ID (see id) or their title (see t). The example above shows both approaches. Configure custom fields online at Settings > Custom fields > Persons (Creating and updating Custom Fields ) Enumerate custom fields using the API: Custom field configuration	object?, Optional
active	Optional boolean. If you want the person to be able to login, you should: Set active to true. Set a login. Optionally, set a profile.	bool?, Optional
profile	Optional integer. Use to assign a specific user profile. If the new person has a login and is active, it is recommended to explicitly assign a user profile. If you do not do so then the system will automatically assign a user profile on your behalf. This will typically be the first profile in alphabetical order. See User profiles to enumerate available profiles.	int?, Optional
data	An optional free-text information. It will be returned with the results for your convenience.	string?, Optional

Creating a person without a login and the absolutely minimal required information:

CODE

{
    "action": "Create",
    "cid": 537,
    "email": "john@john.com",
    "fname": "John",
    "lname": "Hendo" 
}

Creating a person with a login and a few more properties:

CODE

{
    "action": "Create",
    "cid": 537,
    "login": "john.hendo",
    "email": "john@john.com",
    "fname": "John",
    "lname": "Hendo",
    "active": true,
    "profile": 22,
    "phone": "8818777272",
    "title": "CEO",
    "comments": "This is our CEO",
    "cfs": [ { "t": "Position", "v": "At the top" } ]
}

Changing a person

The JSON properties are:

action	Value: Change	string, Mandatory
cid	The company ID of the person. You need to specify this value.	int, Mandatory
pid, login, email	Use any of these three properties to uniquely identify the person to delete. The system will select in this order of priority: pid, then login, then email. pid: The unique person ID. An integer. login: The login of the person. This only works if the person actually was assigned a login in the first place. email: The email of the person. Please note that Wordbee does not enforce unique emails! Examples: CODE `{ "pid": 1000 } or { "login": "john.hauser" } or { "email": "john@hauser.me" }` Note: If you would want to use a person custom field as the unique identifier then set the cfid field when updating, see persons/io/updates (POST) . Although we recommend to use the login or email as unique identifiers, nothing beats the flexibility of Wordbee!	int?, string?, string? Mandatory
profile	To assign or change a user profile ID. This is only required for users that are assigned a login.	int?, Optional
profileKeepExisting	If true then the user profile ID of an existing person will not be modified. This can be useful if the profile was changed inside Wordbee Translator, and an update request shall not tamper with such a change.	bool?, Optional
*	Specify the properties that you want to change. These are those document further above for creating persons.	Optional
data	An optional free-text information. It will be returned with the results for your convenience.	string?, Optional

Updating the comments of a person. We select the person by its unique ID.

CODE

{
    "action": "Change",
    "cid": 537,
    "pid": 3454,
    "comments": "No more comments" 
}

Updating various properties. We select the person by its email.

CODE

{
    "action": "Change",
    "cid": 537,
    "email": "andre@lima.com",
    
    "login": "andre.lima",
    "fname": "Andre",
    "lname": "Lima",
    "active": true,
    "profile": 22,
    "phone": "8818777272",
    "title": "CEO",
    "comments": "This is our CEO",
    "cfs": [ { "t": "Position", "v": "At the top" } ]}

If the person was not changed (values are the same) then the system will tell you so! This can happen, for example, if you submit the same request twice.

Changing or Creating a person

This is a very useful mode:

If the person exists then the person will be updated from your request.
If the person does not yet exist then it will be created.

This mode thus allows to submit updates

The big advantage over Create and Change is: You do not need to verify in advance if a person exists or not.

The JSON properties are:

action	Value: ChangeOrCreate	string, Mandatory
cid	The company ID of the person. You need to specify this value.	int, Mandatory
pid, login, email	Specify any one of the three identifiers below: pid: Only specify if you have the person’s unique ID on records. login: To find back a person by login or create a person with this login email: To find back a person by email or create a person with this email. If the system cannot find back the person with the identifiers above, it will proceed with the creation of a new person. Note: If you would want to use a person custom field as the unique identifier then set the cfid field when updating, see persons/io/updates (POST) . Although we recommend to use the login or email as unique identifiers, nothing beats the flexibility of Wordbee!	int?, string?, string? Mandatory
profile	To assign or change a user profile ID. This is only required for users that are assigned a login.	int?, Optional
profileKeepExisting	If true then the user profile ID of an existing person will not be modified. This can be useful if the profile was changed inside Wordbee Translator, and an update request shall not tamper with such a change.	bool?, Optional
*	Specify the other properties. Important: All properties that are mandatory when creating persons must be specified.	Some mandatory, Some optional
data	An optional free-text information. It will be returned with the results for your convenience.	string?, Optional

Update person or create if it does not yet exist:

CODE

{
    "action": "ChangeOrCreate",
    "cid": 537,
    "email": "andre@lima.com",
    
    "login": "andre.lima",
    "fname": "Andre",
    "lname": "Lima",
    "active": true,
    "profile": 22,
    "phone": "8818777272",
    "title": "CEO",
    "comments": "This is our CEO",
    "cfs": [ { "t": "Position", "v": "At the top" } ]}

Skip person

This mode tells the system to simply disregard the request.

action	Value: Skip	string, Mandatory
data	The company ID of the person. You need to specify this value.	int, Mandatory
data	An optional free-text information. It will be returned with the results for your convenience.	string?, Optional

Example:

CODE

{
    "action": "Skip",
    "fname": "Andre",
    "lname": "Lima",
    "data": "disregard this record!"
}

Tips & Tricks

Synchronizing from external databases

When you have an external database of persons and you want to synchronize changes into Wordbee, you may consider the following recommendations:

Prefer these two actions: “ChangeOrCreate” and “Delete”.
Use the “email” or “login” as the identifier if you do not want to store back the Wordbee person IDs in your systems.
If you want to create persons with a “login” it is strongly recommended that you explicitly assign the user profile (property profile). Although the system will auto-assign a default profile, it may not be the profile you want giving either too many or too little access rights.

What password when creating new person or activating account?

When you create a new person with a login and an active account, or, if you activate an existing person then the question arises: What is the password?

In fact, the system will NOT assign any password:

Instruct users to go to the login page and click the “Forgot my password” link. Then the user will receive an email with a link to set a password.

In the case you use SSO, the authentication should work from your end (SSO provider) and does not require any further steps.