persons/io/updates (POST)
This method lets you create, update or delete one or more persons.
A typical use case is: Synchronize an external directory and import changes to Wordbee Translator. Create new persons, update existing persons or delete persons.
This method is an asynchronous operation: Asynchronous operations
URL
(POST) /api/persons/io/updates
PARAMETERS
The body must contain a JSON object with these properties:
fileToken | The token that references the JSON array with all updates (your requests for creation, change or deletion of persons). Use media/upload to upload JSON and obtain the token. The JSON payload is an array of update requests, see Person update request (Object) | string, Mandatory |
readonly | Optional. If not specified, then value is set to false.
Please use the read-only mode for development or testing only. It should not be used in production. | bool, Optional |
callbackurl, callback | Specify a URL which will be called upon success or failure of operation. This makes polling for operation status unnecessary. See Callbacks (with asynchronous operations) | Optional |
cfid | Optional. By default, persons are uniquely identified by either the person ID, the login or the email. It is your choice. Although not recommended, you may have decided to use a person custom field as the unique identifier. If this is the case, then set the numeric identifier for that person custom field into this property. When you then submit person change requests, you MUST include the persons' custom field value. Otherwise, the system would not be able to find back people to update. | int?, Optional |
The JSON payload (which is referenced by the file token) is an array of update requests: Person update request (Object) . Example:
[
{ "action": "Change", .... }, To change an existing person
{ "action": "Create", .... }, To create a new person
{ "action": "ChangeOrCreate", .... }, To change person if exists or create if not yet exists.
{ "action": "Delete", .... }, To delete a person
{ "action": "Skip", .... }, A request that is disregarded
]
RESULTS
The API method returns an Asynchronous operation result:
{
"trm": {
"requestid":32230,
"status":"Waiting",
"statusText":"Waiting..."
}
}
You can poll the status or use the callback parameter. When the operation is complete, the results are in the custom property
{
"trm": {
"requestid": 32230,
"isbatch": false,
"status": "Finished",
"statusText": "Finished!"
},
"custom": {
"filetokenLog": "97ba14d5cccc4d29b531456002dc3da2",
"summary": {
"readonly": false,
"count": 4,
"success": 4,
"failed": 0,
"created": 1,
"updated": 2,
"deleted": 1
}
}
}
The custom property is a JSON object:
filetokenLog | Call method media/get/{token} with this token to get the detailed update log. This log is a JSON array. It contains all your requests with detailed status and error information: See Person update result (Object). | string |
readonly | Same as input parameter. If true then no changes were actually committed. | bool |
count | Total number of your change requests in payload. | int |
success | Total change requests that were applied with success. | int |
failed | Total change requests that failed. | int |
created | Total persons newly created. The count included in success value. Creation fails if the update request is invalid or the person already exists. Errors are indicated in the log. | int |
updated | Total persons that were updated. The count included in success value. Updates fail if the update request is invalid, the person does not exist or no property of the person was actually modified. Errors are indicated in the log. | int |
deleted | Total persons that were deleted. The count included in success value. Deletions fail if the update request is invalid or the person does not exist. Errors are indicated in the log. | int |
EXAMPLES
We construct a payload with a deletion, an update and a creation request:
[
{
"action": "Delete",
"pid": 677,
"cid": 537,
"data": "we want to delete this person"
},
{
"action": "Update",
"pid": 387,
"cid": 1001,
"phone": "0199973672",
"data": "we want to update the phone number"
},
{
"action": "Create",
"cid": 1001,
"fname": "Alex",
"lname": "Nowhere",
"email": "alex@nowhere.com"
"data": "we want to create a new person. without a login in this example."
}
]
We now upload the payload above using media/upload. The method returns a token which we need for the next step.
POST /api/media/upload
BODY: multipart attachment of the JSON payload
We finally submit the updates:
POST /api/persons/io/updates
BODY:
{
"fileToken": "178eee3996bd4898b31da69a4fe5b206"
}
This returns the status of the asynchronous operation.
Now poll for completion every couple of seconds.
We can also include the URL callback parameter in the payload to notify us. This makes it unnecessary to waste API calls with polling!
You should read about these mechanisms here: Asynchronous operations
When the operation is finished, we get:
{
"trm": {
"requestid": 11230,
"isbatch": false,
"status": "Finished",
"statusText": "Finished!"
},
"result": {
"items": []
},
"custom": {
"filetokenLog": "97ba14d5cccc4d29b531456002dc3da2",
"summary": {
"readonly": false,
"count": 3,
"success": 3,
"failed": 0,
"created": 1,
"updated": 1,
"deleted": 1
}
}
}
If you need it, you can download the detailed log:
GET /api/media/get/97ba14d5cccc4d29b531456002dc3da2
The content is a JSON array containing your requests with status and error information. See details at Person update request (Object)