{"_id":"564cf5462248461700bd4017","__v":15,"parentDoc":null,"category":{"_id":"563a252e50bf950d00e0979c","project":"563a252d50bf950d00e09798","pages":["563a252f50bf950d00e0979e","563a35ac1846790d0089532c","563d1407d8f2d20d00448d3c","563d1d3f9799fb0d0004776a","564509aa2c74cf1900da48c7","56453b7e9f3f550d00fa3c7b","564b498aeed7de0d003672c3","564b523ce5d9d61700d580e0","564b58ea1a8e610d006bfd49","564b59baee12850d00958656","564b6773d969330d00aba984","564b69b2d7b95d0d00ed050f","564b7fa8cc472d0d00da9447","564b905fa8a0ba21002ad6b1","564ba051288b1a2b00b3ae83","564ba6275cc43717009bcff1","564bb2138841060d00abb2e0","564bb74e05c99e1700161dd1","564c8ad60ddedc210051e582","564cca42d0c5b42b002305e8","564cca8ecfa4452b0019926d","564ce34f404ce53500fdb255","564cea76404ce53500fdb272","564cedb77d4d31170028dd2e","564cefc1bc81632100b10468","564cf17d1f42792b00820515","564cf5462248461700bd4017","564ddd49a8671617004e7b90","564ddf9ead1d5217003e2e18","564de1dea8671617004e7b99","564de3c11133043500f4bf96","564de669e39c4435005a1f65","564df3f16eaa3a2100868961","5655d3519347d30d00d7e8e2"],"version":"563a252d50bf950d00e0979b","__v":34,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-04T15:33:02.244Z","from_sync":false,"order":9999,"slug":"documentation","title":"Documentation"},"version":{"_id":"563a252d50bf950d00e0979b","__v":7,"project":"563a252d50bf950d00e09798","createdAt":"2015-11-04T15:33:01.701Z","releaseDate":"2015-11-04T15:33:01.701Z","categories":["563a252e50bf950d00e0979c","563a2a691846790d008952fe","563a3394daf1c00d00136d9b","563a3467d25e8919005f3f0c","563a347850bf950d00e097b4","570e5cec10aa423200391fb5","5890d358d6cb8e2500a3f311"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"project":"563a252d50bf950d00e09798","user":"54c7fdeae317000d007c2765","updates":["565e1c1e413e06170093dcb6","579f1968dbf6160e0036b120"],"next":{"pages":[],"description":""},"createdAt":"2015-11-18T22:01:42.748Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":35,"body":"[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"GET /users\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Get a list of all the users in the client account.\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"3-0\": \"Parameters\",\n    \"1-1\": \"user.manage\",\n    \"2-1\": \"https://app.klipfolio.com/api/1.0/users\",\n    \"3-1\": \"client_id (string) — show only users belonging to a specific client\\nemail (string) — search for a user by email address\\nexternal_id (string) — show only users that have the specified external_id\\nfull (true/false) — include associations (tab_instances, properties) (only works when specifying external_id)\\ninclude_roles (true/false) — include the user’s roles\\ninclude_groups (true/false) — include the user’s groups\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request\n`GET https://app.klipfolio.com/api/1/users`\n\n##Example Response (external_id is not displayed if it is null)\n```\n{\n   \"data\": {\n       \"users\": [\n           {\n               \"id\": \"ab05f4a011e6a93fb307f4e3e970c3c0\",\n                \"first_name\": \"Trial\",\n                \"last_name\": \"User\",\n                 \"email\": \"jdoe:::at:::klipfolio.com\",\n                 \"date_last_login\": \"2016-06-03T17:05:54Z\"\n           }\n       ]\n   },\n   \"meta\": {\n       \"status\": 200,\n       \"success\": true\n   }\n}\n```\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"GET /users/{id}\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Get details for the specified user.\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"3-0\": \"Parameters\",\n    \"1-1\": \"user.manage\",\n    \"2-1\": \"https://app.klipfolio.com/api/1.0/users/{id}\",\n    \"3-1\": \"full (true/false) — include associations (tab_instances, groups, roles, properties)\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request\n`GET https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef?full=true`\n\n##Example Response (external_id is not displayed if it is null)\n```\n{\n  \"meta\": {\n    \"success\": true,\n    \"status\": 200\n  },\n  \"data\": {\n    \"id\": \"c17db511dbc00421d0a093fc8c236064\",\n    \"company\": \"Hello\",\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"email\": \"Doe+12@klipfolio.com\",\n    \"date_last_login\": \"2016-06-17T18:12:11Z\",\n    \"date_created\": \"2016-06-17T18:12:06Z\",\n    \"is_locked_out\": false,\n    \"tab_instances\": [\n      \"a46d2e3fb99072c19f7997128e3e6f66\",\n      \"b8b305c4ba9287b7fbabc40831744444\"\n    ],\n    \"groups\": [\n      {\n        \"id\": \"0016c12db53a58901bf19fd5e285c438\",\n        \"name\": \"Trial Users\"\n      }\n    ],\n    \"roles\": [\n      \"26a3d3fb4cd6bf23d35b4126be26e5f3\"\n    ],\n    \"properties\": {}\n  }\n}\n```\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"POST /users\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Create a new user, optionally for a client.\\nuser.manage\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"3-0\": \"Fields\",\n    \"1-1\": \"user.manage\",\n    \"2-1\": \"https://app.klipfolio.com/api/1/users or\\nhttps://app.klipfolio.com/api/1/users?send_email=true\",\n    \"3-1\": \"first_name, last_name, roles, email, password (optional), external_id (optional), client_id (optional), send_email (default is false).\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request \n**Note:** Optionally include 'client_id' in the post data to create a user for a client, optionally include ‘external_id’ in the post data to add an external id to the new user, optionally include 'password' in the post data to set the password, optionally include ?send_email=true in the post data to send a welcome email to the user.\n```\nPOST https://app.klipfolio.com/api/1/users -d \n\"{\n'client_id': '0123456789abcdef0123456789abcdef', \n'first_name': 'Jane', \n'last_name': 'Doe', \n'email': 'jdoe@klipfolio.com', \n'roles': ['0123456789abcdef0123456789abcdef'],\n'password': 'tempPassword'\n}\"\n```\n##Example Response\n```\n{\n   \"data\": {},\n   \"meta\": {\n       \"location\": \"/users/0123456789abcdef0123456789abcdef\",\n       \"status\": 201,\n       \"success\": true\n   }\n}\n```\n[block:api-header]\n{\n  \"type\": \"put\",\n  \"title\": \"PUT /users/{id}\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Update the specified user.\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"3-0\": \"Fields\",\n    \"1-1\": \"user.manage\",\n    \"2-1\": \"https://app.klipfolio.com/api/1.0/users\",\n    \"3-1\": \"first_name, last_name, external_id, email\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request (only fields to be updated need to be sent)\n```\nPUT https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef -d \n\"{\n'first_name': 'Janet', \n}\"\n```\n\n##Example Response\n```\n{\n   \"data\": {},\n   \"meta\": {\n       \"status\": 200,\n       \"success\": true\n   }\n}\n```\n\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"DELETE /users/{id}\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description \\nPermissions\\nResource URL \\nParameters\\nResponse codes\",\n    \"0-1\": \"Delete the specified user.\\nuser.manage\\nhttps://app.klipfolio.com/api/1.0/users\\nnone\\n400 — missing {id}\\n401 — access denied to non-admins and users from other companies\\n403 — forbidden to: delete your own account, delete the super admin, delete the technical contact, delete the business contact 404 ({id} not found\",\n    \"1-1\": \"user.manage\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"3-0\": \"Parameters\",\n    \"2-1\": \"https://app.klipfolio.com/api/1/users\",\n    \"3-1\": \"None.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request\n`DELETE https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef`\n\n##Example Response\n```\n{\n   \"data\": {},\n   \"meta\": {\n       \"status\": 200,\n       \"success\": true\n   }\n}\n```","excerpt":"View, create, update and manage users belonging to the requesting company.","slug":"users","type":"basic","title":"Users"}

Users

View, create, update and manage users belonging to the requesting company.

[block:api-header] { "type": "get", "title": "GET /users" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Get a list of all the users in the client account.", "1-0": "Permissions", "2-0": "Resource URL", "3-0": "Parameters", "1-1": "user.manage", "2-1": "https://app.klipfolio.com/api/1.0/users", "3-1": "client_id (string) — show only users belonging to a specific client\nemail (string) — search for a user by email address\nexternal_id (string) — show only users that have the specified external_id\nfull (true/false) — include associations (tab_instances, properties) (only works when specifying external_id)\ninclude_roles (true/false) — include the user’s roles\ninclude_groups (true/false) — include the user’s groups" }, "cols": 2, "rows": 4 } [/block] ##Example Request `GET https://app.klipfolio.com/api/1/users` ##Example Response (external_id is not displayed if it is null) ``` { "data": { "users": [ { "id": "ab05f4a011e6a93fb307f4e3e970c3c0", "first_name": "Trial", "last_name": "User", "email": "jdoe@klipfolio.com", "date_last_login": "2016-06-03T17:05:54Z" } ] }, "meta": { "status": 200, "success": true } } ``` [block:api-header] { "type": "get", "title": "GET /users/{id}" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Get details for the specified user.", "1-0": "Permissions", "2-0": "Resource URL", "3-0": "Parameters", "1-1": "user.manage", "2-1": "https://app.klipfolio.com/api/1.0/users/{id}", "3-1": "full (true/false) — include associations (tab_instances, groups, roles, properties)" }, "cols": 2, "rows": 4 } [/block] ##Example Request `GET https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef?full=true` ##Example Response (external_id is not displayed if it is null) ``` { "meta": { "success": true, "status": 200 }, "data": { "id": "c17db511dbc00421d0a093fc8c236064", "company": "Hello", "first_name": "Jane", "last_name": "Doe", "email": "Doe+12@klipfolio.com", "date_last_login": "2016-06-17T18:12:11Z", "date_created": "2016-06-17T18:12:06Z", "is_locked_out": false, "tab_instances": [ "a46d2e3fb99072c19f7997128e3e6f66", "b8b305c4ba9287b7fbabc40831744444" ], "groups": [ { "id": "0016c12db53a58901bf19fd5e285c438", "name": "Trial Users" } ], "roles": [ "26a3d3fb4cd6bf23d35b4126be26e5f3" ], "properties": {} } } ``` [block:api-header] { "type": "post", "title": "POST /users" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Create a new user, optionally for a client.\nuser.manage", "1-0": "Permissions", "2-0": "Resource URL", "3-0": "Fields", "1-1": "user.manage", "2-1": "https://app.klipfolio.com/api/1/users or\nhttps://app.klipfolio.com/api/1/users?send_email=true", "3-1": "first_name, last_name, roles, email, password (optional), external_id (optional), client_id (optional), send_email (default is false)." }, "cols": 2, "rows": 4 } [/block] ##Example Request **Note:** Optionally include 'client_id' in the post data to create a user for a client, optionally include ‘external_id’ in the post data to add an external id to the new user, optionally include 'password' in the post data to set the password, optionally include ?send_email=true in the post data to send a welcome email to the user. ``` POST https://app.klipfolio.com/api/1/users -d "{ 'client_id': '0123456789abcdef0123456789abcdef', 'first_name': 'Jane', 'last_name': 'Doe', 'email': 'jdoe@klipfolio.com', 'roles': ['0123456789abcdef0123456789abcdef'], 'password': 'tempPassword' }" ``` ##Example Response ``` { "data": {}, "meta": { "location": "/users/0123456789abcdef0123456789abcdef", "status": 201, "success": true } } ``` [block:api-header] { "type": "put", "title": "PUT /users/{id}" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Update the specified user.", "1-0": "Permissions", "2-0": "Resource URL", "3-0": "Fields", "1-1": "user.manage", "2-1": "https://app.klipfolio.com/api/1.0/users", "3-1": "first_name, last_name, external_id, email" }, "cols": 2, "rows": 4 } [/block] ##Example Request (only fields to be updated need to be sent) ``` PUT https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef -d "{ 'first_name': 'Janet', }" ``` ##Example Response ``` { "data": {}, "meta": { "status": 200, "success": true } } ``` [block:api-header] { "type": "basic", "title": "DELETE /users/{id}" } [/block] [block:parameters] { "data": { "0-0": "Description \nPermissions\nResource URL \nParameters\nResponse codes", "0-1": "Delete the specified user.\nuser.manage\nhttps://app.klipfolio.com/api/1.0/users\nnone\n400 — missing {id}\n401 — access denied to non-admins and users from other companies\n403 — forbidden to: delete your own account, delete the super admin, delete the technical contact, delete the business contact 404 ({id} not found", "1-1": "user.manage", "1-0": "Permissions", "2-0": "Resource URL", "3-0": "Parameters", "2-1": "https://app.klipfolio.com/api/1/users", "3-1": "None." }, "cols": 2, "rows": 4 } [/block] ##Example Request `DELETE https://app.klipfolio.com/api/1/users/0123456789abcdef0123456789abcdef` ##Example Response ``` { "data": {}, "meta": { "status": 200, "success": true } } ```