{"_id":"563a35ac1846790d0089532c","parentDoc":null,"project":"563a252d50bf950d00e09798","__v":22,"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"},"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"},"user":"54c7fdeae317000d007c2765","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-04T16:43:24.654Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"GET /clients\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Collects a list of all the clients associated with the requesting account. Users with admin role privileges have access to all clients.\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"3-0\": \"Parameters\",\n    \"1-1\": \"client.access\",\n    \"2-1\": \"https://app.klipfolio.com/api/1.0/clients\",\n    \"3-1\": \"external_id (string) — show only clients that have the specified external id\\nfull (true/false) — include associations in the listing (users, groups, share_rights) (only works when specifying external_id)\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n## Example Request \n\nGET https://app.klipfolio.com/api/1/clients\n\n## Example Response \n**Note**: The external_id is not shown if the client’s external ID is null)\n\n```\n{\n    \"data\": {\n        \"clients\": [\n            {\n                \"description\": \"Company A\",\n                \"external_id\": \"client_123\",\n                \"id\": \"0123456789abcdef0123456789abcdef\",\n                \"name\": \"Client A\"\n            },\n            {\n                \"description\": \"Company B\",\n                \"id\": \"0123456789abcdef0123456789abcdef\",\n                \"name\": \"Client B\"\n            },\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 /clients/{id}\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Get the details for the specified client.\",\n    \"1-0\": \"Resource URL\",\n    \"1-1\": \"https://app.klipfolio.com/api/1.0/clients/{id}\",\n    \"2-0\": \"Permissions\",\n    \"2-1\": \"client.access\",\n    \"3-0\": \"Parameters\",\n    \"3-1\": \"full (true/false) — include associations in the listing (users, groups, share_right)\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n## Example Request\nGET https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef?full=true\n\n## Example Response \n**Note**: \tcustom_theme is shown only if the feature is enabled in the parent account\nexternal_id is not shown if the client’s external id is null \ntrial_remaining is shown only if the client is a trial user\n```\n{\n   \"data\": {\n       \"custom_theme\": true,\n       \"description\": Company C,\n       \"groups\": [\n           \"0123456789abcdef0123456789abcdef\",\n           \"23456789abcdef0123456789abcdef01\",\n           \"456789abcdef0123456789abcdef0123\"\n       ],\n       \"id\": \"0123456789abcdef0123456789abcdef\",\n       \"is_direct_billed\": false,\n       \"last_sign_in\": null,\n       \"name\": \"Client C\",\n       \"primary_contact\": null,\n       \"seats\": 50,\n       \"share_rights\": [\n           {\n               \"group_id\": \"6789abcdef0123456789abcdef012345\",\n               \"group_name\": \"Management\",\n               \"can_manage\": true\n    }],\n       \"status\": \"Trial\",\n       \"trial_remaining\": 5,\n       \"users\": [\n           \"0123456789abcdef0123456789abcdef\",\n           \"23456789abcdef0123456789abcdef01\",\n           \"456789abcdef0123456789abcdef0123\"\n       ]\n   },\n   \"meta\": {\n       \"status\": 200,\n       \"success\": true\n   }\n}\n```\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"Post /clients\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"1-0\": \"Resource URL\",\n    \"0-1\": \"Create a client.\",\n    \"1-1\": \"https://app.klipfolio.com/api/1.0/clients\",\n    \"2-0\": \"Permissions\",\n    \"2-1\": \"client.build\",\n    \"3-0\": \"Fields\",\n    \"3-1\": \"name, description, status, seats (optional), custom_theme (optional), external_id (optional)\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n## Example Request \n**Note**: 'status' can be 'active', 'disabled', ‘setup’ or ‘trial’.  ‘custom_theme’ is optional, optionally include ‘external_id’ in the post data to add an external id to the new client\n\nPOST https://app.klipfolio.com/api/1/clients -d\n“{\n 'name': 'Client From API', \n 'description': 'Hello there', \n 'seats': 20, \n 'status': 'active'\n 'custom_theme': true\n}\"\n\n```\n##Example Response\n```\n{\n   \"data\": {},\n   \"meta\": {\n       \"location\": \"/clients/0123456789abcdef0123456789abcdef\",\n       \"status\": 201,\n       \"success\": true\n   }\n}\n```\n\n[block:api-header]\n{\n  \"type\": \"put\",\n  \"title\": \"PUT/clients/{id}\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Update the specified client.\",\n    \"1-0\": \"Permissions\",\n    \"1-1\": \"client.edit\",\n    \"2-0\": \"Resource URL\",\n    \"2-1\": \"https://app.klipfolio.com/api/1.0/clients/{id}\",\n    \"3-0\": \"Fields\",\n    \"3-1\": \"name, description, status, seats, custom_theme, external_id\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request\nPUT https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef -d {“status”: “disabled”}\n\n##Example Response\n```\n{\n   \"data\": {},\n   \"meta\": {\n       \"status\": 200,\n       \"success\": true\n   }\n}\n```\n[block:api-header]\n{\n  \"type\": \"delete\",\n  \"title\": \"DELETE /clients/{id}\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Delete a client.\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"3-0\": \"Parameters\",\n    \"1-1\": \"client.delete\",\n    \"2-1\": \"https://app.klipfolio.com/api/1.0/clients/{id}\",\n    \"3-1\": \"None.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request \nDELETE https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef\n\n##Example Response\n```\n{\n   \"data\": {},\n   \"meta\": {\n       \"status\": 200,\n       \"success\": true\n   }\n}\n```\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"POST /clients/{id}/:::at:::/enable_direct_billing\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Switch a client to direct billing. This cannot be undone. This command is only available to Partner accounts.\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"1-1\": \"client.access\",\n    \"2-1\": \"https://app.klipfolio.com/api/1.0/clients/{id}/@/enable_direct_billing\",\n    \"3-0\": \"Fields\",\n    \"3-1\": \"None.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request\nPOST https://app.klipfolio.com/api/1/clients/0123456789abcdef01234589abcdef/@/enable_direct_billing\n\n##Example Response\n```\n{\n  \"data\": {\n      \"op_requested\":”enable_direct_billing” \n  },\n  \"meta\": {\n      \"status\": 200,\n      \"success\": true\n  }\n}\n```\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"POST /clients/{id}/@/extend trial\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Description\",\n    \"0-1\": \"Extend a client’s trial period.\",\n    \"1-0\": \"Permissions\",\n    \"2-0\": \"Resource URL\",\n    \"3-0\": \"Fields\",\n    \"1-1\": \"client.access\",\n    \"2-1\": \"https://app.klipfolio.com/api/1.0/clients/{id}/@/extend_trial\",\n    \"3-1\": \"None.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n##Example Request\nPOST https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef/@/extend_trial -d “{‘days’:’7’}”\n\n##Example Response\n```\n{\n  \"data\": {\n      \"op_requested\":”extend_trial” \n  },\n  \"meta\": {\n      \"status\": 200,\n      \"success\": true\n  }\n}\n```","excerpt":"View, create, update existing clients, and manage clients for all client accounts belonging to the requesting company.","slug":"test","type":"basic","title":"Clients"}

Clients

View, create, update existing clients, and manage clients for all client accounts belonging to the requesting company.

[block:api-header] { "type": "get", "title": "GET /clients" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Collects a list of all the clients associated with the requesting account. Users with admin role privileges have access to all clients.", "1-0": "Permissions", "2-0": "Resource URL", "3-0": "Parameters", "1-1": "client.access", "2-1": "https://app.klipfolio.com/api/1.0/clients", "3-1": "external_id (string) — show only clients that have the specified external id\nfull (true/false) — include associations in the listing (users, groups, share_rights) (only works when specifying external_id)" }, "cols": 2, "rows": 4 } [/block] ## Example Request GET https://app.klipfolio.com/api/1/clients ## Example Response **Note**: The external_id is not shown if the client’s external ID is null) ``` { "data": { "clients": [ { "description": "Company A", "external_id": "client_123", "id": "0123456789abcdef0123456789abcdef", "name": "Client A" }, { "description": "Company B", "id": "0123456789abcdef0123456789abcdef", "name": "Client B" }, ... ] }, "meta": { "status": 200, "success": true } } ``` [block:api-header] { "type": "get", "title": "GET /clients/{id}" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Get the details for the specified client.", "1-0": "Resource URL", "1-1": "https://app.klipfolio.com/api/1.0/clients/{id}", "2-0": "Permissions", "2-1": "client.access", "3-0": "Parameters", "3-1": "full (true/false) — include associations in the listing (users, groups, share_right)" }, "cols": 2, "rows": 4 } [/block] ## Example Request GET https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef?full=true ## Example Response **Note**: custom_theme is shown only if the feature is enabled in the parent account external_id is not shown if the client’s external id is null trial_remaining is shown only if the client is a trial user ``` { "data": { "custom_theme": true, "description": Company C, "groups": [ "0123456789abcdef0123456789abcdef", "23456789abcdef0123456789abcdef01", "456789abcdef0123456789abcdef0123" ], "id": "0123456789abcdef0123456789abcdef", "is_direct_billed": false, "last_sign_in": null, "name": "Client C", "primary_contact": null, "seats": 50, "share_rights": [ { "group_id": "6789abcdef0123456789abcdef012345", "group_name": "Management", "can_manage": true }], "status": "Trial", "trial_remaining": 5, "users": [ "0123456789abcdef0123456789abcdef", "23456789abcdef0123456789abcdef01", "456789abcdef0123456789abcdef0123" ] }, "meta": { "status": 200, "success": true } } ``` [block:api-header] { "type": "post", "title": "Post /clients" } [/block] [block:parameters] { "data": { "0-0": "Description", "1-0": "Resource URL", "0-1": "Create a client.", "1-1": "https://app.klipfolio.com/api/1.0/clients", "2-0": "Permissions", "2-1": "client.build", "3-0": "Fields", "3-1": "name, description, status, seats (optional), custom_theme (optional), external_id (optional)" }, "cols": 2, "rows": 4 } [/block] ## Example Request **Note**: 'status' can be 'active', 'disabled', ‘setup’ or ‘trial’. ‘custom_theme’ is optional, optionally include ‘external_id’ in the post data to add an external id to the new client POST https://app.klipfolio.com/api/1/clients -d “{ 'name': 'Client From API', 'description': 'Hello there', 'seats': 20, 'status': 'active' 'custom_theme': true }" ``` ##Example Response ``` { "data": {}, "meta": { "location": "/clients/0123456789abcdef0123456789abcdef", "status": 201, "success": true } } ``` [block:api-header] { "type": "put", "title": "PUT/clients/{id}" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Update the specified client.", "1-0": "Permissions", "1-1": "client.edit", "2-0": "Resource URL", "2-1": "https://app.klipfolio.com/api/1.0/clients/{id}", "3-0": "Fields", "3-1": "name, description, status, seats, custom_theme, external_id" }, "cols": 2, "rows": 4 } [/block] ##Example Request PUT https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef -d {“status”: “disabled”} ##Example Response ``` { "data": {}, "meta": { "status": 200, "success": true } } ``` [block:api-header] { "type": "delete", "title": "DELETE /clients/{id}" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Delete a client.", "1-0": "Permissions", "2-0": "Resource URL", "3-0": "Parameters", "1-1": "client.delete", "2-1": "https://app.klipfolio.com/api/1.0/clients/{id}", "3-1": "None." }, "cols": 2, "rows": 4 } [/block] ##Example Request DELETE https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef ##Example Response ``` { "data": {}, "meta": { "status": 200, "success": true } } ``` [block:api-header] { "type": "post", "title": "POST /clients/{id}/@/enable_direct_billing" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Switch a client to direct billing. This cannot be undone. This command is only available to Partner accounts.", "1-0": "Permissions", "2-0": "Resource URL", "1-1": "client.access", "2-1": "https://app.klipfolio.com/api/1.0/clients/{id}/@/enable_direct_billing", "3-0": "Fields", "3-1": "None." }, "cols": 2, "rows": 4 } [/block] ##Example Request POST https://app.klipfolio.com/api/1/clients/0123456789abcdef01234589abcdef/@/enable_direct_billing ##Example Response ``` { "data": { "op_requested":”enable_direct_billing” }, "meta": { "status": 200, "success": true } } ``` [block:api-header] { "type": "post", "title": "POST /clients/{id}/@/extend trial" } [/block] [block:parameters] { "data": { "0-0": "Description", "0-1": "Extend a client’s trial period.", "1-0": "Permissions", "2-0": "Resource URL", "3-0": "Fields", "1-1": "client.access", "2-1": "https://app.klipfolio.com/api/1.0/clients/{id}/@/extend_trial", "3-1": "None." }, "cols": 2, "rows": 4 } [/block] ##Example Request POST https://app.klipfolio.com/api/1/clients/0123456789abcdef0123456789abcdef/@/extend_trial -d “{‘days’:’7’}” ##Example Response ``` { "data": { "op_requested":”extend_trial” }, "meta": { "status": 200, "success": true } } ```