--- title: "PeopleSync" url: "https://dev.4hse.com/api/peoplesync" --- # PeopleSync **PeopleSync** synchronises the people of a project from a CSV file. It compares the file with what is already recorded, works out the difference, and applies only the changes needed: missing people are created, existing ones updated, and their offices and job assignments aligned to the file. The synchronisation runs as an asynchronous **Task**, because a file can hold thousands of rows. Starting a sync returns a task reference: poll the Task API to follow its progress and read the outcome. Use this API to: - Upload a CSV file and start a synchronisation for a project - Check the status and the result of a synchronisation you started Version 1.0.0 OpenAPI version 3.0.0 ## Authentication [Section titled “ Authentication ”](#authentication) ### OAuth2 [Section titled “OAuth2 ”](#oauth2) **Security scheme type:** oauth2 **Flow type:** password **Token URL:** [https://auth.4hse.com/realms/4hse/protocol/openid-connect/token](https://auth.4hse.com/realms/4hse/protocol/openid-connect/token) **Flow type:** refreshToken **Token URL:** [https://auth.4hse.com/realms/4hse/protocol/openid-connect/token](https://auth.4hse.com/realms/4hse/protocol/openid-connect/token) ### AccessToken [Section titled “AccessToken ”](#accesstoken) **Security scheme type:** apiKey **Query parameter name:** access-token ## Operations [Section titled “Operations”](#operations) ### create [Section titled “create”](#operation-createPeopleSync-post) POST /people-sync/create - Create a new people sync task by uploading a CSV file and specifying the project and sync options. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[Oauth2](/api/peoplesync/#oauth2)** - **[AccessToken](/api/peoplesync/#accesstoken)** #### Request Body [Section titled “Request Body ”](#request-body) Select media typemultipart/form-data object **file** required CSV file that contains data to synchronize. string format: binary **project\_id** required The project identifier of people to synchronize. string ``` b190e786-8b47-4575-9947-3b1f782e6356 ``` **pk** The name of the primary key field. It is used to uniquely identify a person. string default: code ``` tax_code ``` **emulation** If true, the request is executed in emulation mode (no changes are made, but the changes and errors are reported). boolean 0 ``` 1 ``` **max\_changes** Maximum number of changes allowed in the task. If exceeded, the task is aborted. integer default: 100 ``` 150 ``` **sync\_type** Defines which datasets will be synchronized. “people” syncs a single person, “offices” syncs person-office associations, “jobs” syncs person-job associations. “offices” requires “people”, “jobs” requires “offices”. Array default: people Allowed values: people offices jobs ``` [ "people", "offices", "jobs"] ``` #### Responses [Section titled “ Responses ”](#responses) ##### 201 [Section titled “201 ”](#201) Task was created and put in queue Select media typeapplication/json object **task\_id** The created task ID. Use it to retrieve the current task status via the /view endpoint. string ``` task-1234 ``` ##### Example ``` { "task_id": "task-1234"} ``` ##### 400 [Section titled “400 ”](#400) Bad request. Required parameter missing or invalid value. ##### 403 [Section titled “403 ”](#403) Not allowed to synchronize data on the specified project due to permissions. ##### 413 [Section titled “413 ”](#413) CSV file is too large. ##### 500 [Section titled “500 ”](#500) Unknown internal server error. ### view [Section titled “view”](#operation-viewPeopleSync-get) GET /people-sync/view/{id} - Retrieve the status and result of a people sync task by its unique ID. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[Oauth2](/api/peoplesync/#oauth2)** - **[AccessToken](/api/peoplesync/#accesstoken)** #### Path Parameters [Section titled “Path Parameters ”](#path-parameters) **id** required string The task identifier #### Responses [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) The requested task data Select media typeapplication/json object **task\_id** Task identifier string ``` task-1234 ``` **user\_id** Identifier of the user who created the task string ``` admin@myproject.com ``` **status** The current task status string Allowed values: TODO PENDING PROCESSING DONE FAILED **response** object **result** object ``` { "PS2": [ { "id": "PS2", "action": "activate", "periods": [ { "end_date": "2021-07-01 00:00:00", "start_date": "2020-07-01 00:00:0" }, { "end_date": "", "start_date": "2023-06-08 00:00:00" } ] } ], "PS3": [ { "id": "PS3", "action": "add" } ], "PS4": [ { "id": "PS4", "action": "deactivate", "periods": [ { "end_date": "2023-06-08 00:00:00", "start_date": "2020-07-01 00:00:00" } ] } ], "PS5": [ { "id": "PS5", "action": "update", "changes": { "street": "New street address", "locality": "New locality" } } ], "PS6": [ { "id": "OF2", "action": "add" }, { "id": "OF1", "action": "deactivate", "periods": [ { "end_date": "2023-06-14 00:00:00", "start_date": "1970-01-01 00:00:00" } ] }, { "id": "OF2-JOB1", "action": "add" } ]} ``` **errors** It lists eventually task execution errors Array object **line** CSV file line that cointains the error integer ``` 9 ``` **message** The error esplication string ``` Invalid office code OF1234 ``` **info** Error additional informations string ``` ... ``` **changes** It presents a summary of the applied changes after the task execution. object **add** The total number of add operations integer ``` 2 ``` **update** The total number of update operations integer ``` 3 ``` **activate** The total number of activate operations integer ``` 5 ``` **deactivate** The total number of deactivate operations integer ``` 4 ``` **total** The total number of operations executed integer ``` 14 ``` **created\_at** Date time when task was created string ``` 2023-06-30 10:40:00 ``` **updated\_at** Date time when task was updated last string ``` 2023-06-30 10:40:00 ``` ##### Example ``` { "task_id": "task-1234", "user_id": "admin@myproject.com", "status": "DONE", "response": { "result": { "PS2": [ { "id": "PS2", "action": "activate", "periods": [ { "end_date": "2021-07-01 00:00:00", "start_date": "2020-07-01 00:00:00" }, { "end_date": "", "start_date": "2023-06-08 00:00:00" } ] } ], "PS3": [ { "id": "PS3", "action": "add" } ], "PS4": [ { "id": "PS4", "action": "deactivate", "periods": [ { "end_date": "2023-06-08 00:00:00", "start_date": "2020-07-01 00:00:00" } ] } ], "PS5": [ { "id": "PS5", "action": "update", "changes": { "street": "New street address", "locality": "New locality" } } ], "PS6": [ { "id": "OF2", "action": "add" }, { "id": "OF1", "action": "deactivate", "periods": [ { "end_date": "2023-06-14 00:00:00", "start_date": "1970-01-01 00:00:00" } ] }, { "id": "OF2-JOB1", "action": "add" } ] }, "errors": [ { "line": 9, "message": "Invalid office code OF1234", "info": "..." } ], "changes": { "add": 2, "update": 3, "activate": 5, "deactivate": 4, "total": 14 } }, "created_at": "2023-06-30 10:40:00", "updated_at": "2023-06-30 10:40:00"} ``` ##### 403 [Section titled “403 ”](#403) Not allowed to fetch task data due to permissions. This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply.