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

GET /clients

Description

Collects a list of all the clients associated with the requesting account. Users with admin role privileges have access to all clients.

Permissions

client.access

Resource URL

https://app.klipfolio.com/api/1.0/clients

Parameters

external_id (string) — show only clients that have the specified external id

full (true/false) — include associations in the listing (users, groups, share_rights) (only works when specifying external_id)

status (active, trial, setup, disabled) — show only clients that have the specified account status.

Example Requests

GET https://app.klipfolio.com/api/1/clients
GET https://app.klipfolio.com/api/1.0/clients?status=active

Example Response

{
    "meta": {
        "success": true,
        "status": 200,
        "count": 3,
        "total": 3
    },
    "data": {
        "clients": [
            {
                "id": "0123456789abcdef0123456789abcdef",
                "name": "Company A",
                "description": "Testing for demo",
                "status": "Active",
                "seats": -1,
                "last_sign_in": "2015-02-26T23:58:29Z"
            },
            {
                "id": "0123456789abcdef0123456789abcdef",
                "name": "Company B,
                "description": "Marketing",
                "status": "Active",
                "seats": -1,
                "last_sign_in": "2017-03-02T18:03:07Z"
            },
            {
                "id": "0123456789abcdef0123456789abcdef",
                "name": "Company C",
                "description": "Stats for Google Analytics",
                "status": "Active",
                "seats": -1,
                "last_sign_in": null
            }
        ]
    }
}

Note: The external_id is not shown if the client’s external ID is null

GET /clients/{id}

Description

Get the details for the specified client.

Resource URL

https://app.klipfolio.com/api/1.0/clients/{id}

Permissions

client.access

Parameters

full (true/false) — include associations in the listing (users, groups, share_right)

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
   }
}

POST /clients

Description

Create a client.

Resource URL

https://app.klipfolio.com/api/1.0/clients

Permissions

client.build

Fields

name, description, status, seats (optional), custom_theme (optional), external_id (optional)

Example Request

Note: 'status' can be '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': 'trial'
'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
}
}