Clients¶

24 endpoints. Authentication, errors, paging and rate limits are described once, in the API overview.

Action	Method	Description
`addclient`	POST	Create a new client account
`addclientnote`	POST	Add a note to a client's account
`addcontact`	POST	Add a sub-contact to a client
`addcredit`	POST	Add credit to a client's account balance
`adduser`	POST	Create a client-area login
`applycredit`	POST	Apply client credit to an invoice
`closeclient`	POST	Close a client account
`createclientinvite`	POST	Invite someone to a client account
`createssotoken`	POST	Create a one-time sign-in link to the client area
`deleteclient`	POST	Delete a client account
`deletecontact`	POST	Delete a sub-contact
`deleteuserclient`	POST	Remove a login from a client account
`getclientgroups`	GET	List all client groups
`getclientpassword`	GET	Read a client password (not available)
`getclients`	GET	List clients with optional search/filtering
`getclientsdetails`	GET	Get full details for a single client
`getcontacts`	GET	Get sub-contacts for a client
`getcredits`	GET	List credit entries
`getuserpermissions`	GET	Get what a login may do on a client account
`getusers`	GET	List client-area logins
`updateclient`	POST	Update an existing client's details
`updatecontact`	POST	Update a sub-contact
`updateuser`	POST	Update a client-area login
`updateuserpermissions`	POST	Change what a login may do on a client account

addclient¶

Create a new client account.

POST /api/v1/addclient

Permission: create_clients

Parameters

Name	Type	Required	Description
`firstname`	string	yes	Up to 255 characters.
`lastname`	string	yes	Up to 255 characters.
`email`	email	yes	Must not belong to another client.
`password2`	string	no	At least 8 characters. When sent, a client-area login is created with it. password is accepted too.
`companyname`	string	no	Company name.
`address1`	string	no	Street address.
`city`	string	no	City.
`state`	string	no	State or region.
`postcode`	string	no	Postal code.
`country`	string	no	Two-letter country code. Default US.
`phonenumber`	string	no	Phone number.

Response

Field	Description
`result`	`success`
`clientid`	integer

Errors

Status	When
422	A required field is missing, or the address is already a client or a login.

Example

curl -X POST https://example.com/api/v1/addclient \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "firstname=Ada" \
  --data-urlencode "lastname=Lovelace" \
  --data-urlencode "email=ada@example.com" \
  --data-urlencode "country=GB"

addclientnote¶

Add a note to a client's account.

POST /api/v1/addclientnote

Permission: create_clients

Parameters

Name	Type	Required	Description
`userid`	integer	yes	The client. clientid is accepted too.
`note`	string	yes	The note. notes and message are accepted too.
`sticky`	boolean	no	Pin it to the top of the client summary.

Response

Field	Description
`result`	`success`

Errors

Status	When
404	No such client.
422	The note is empty.

Note

Signed with the user name of the staff member the credential belongs to.

Example

curl -X POST https://example.com/api/v1/addclientnote \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "userid=1" \
  --data-urlencode "note=example"

addcontact¶

Add a sub-contact to a client.

POST /api/v1/addcontact

Permission: create_clients

Parameters

Name	Type	Required	Description
`clientid`	integer	yes	The client.
`firstname`	string	yes	First name.
`lastname`	string	yes	Last name.
`email`	email	yes	Address.
`phonenumber`	string	no	Phone number.

Response

Field	Description
`result`	`success`
`contactid`	integer

Example

curl -X POST https://example.com/api/v1/addcontact \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "clientid=1" \
  --data-urlencode "firstname=example" \
  --data-urlencode "lastname=example" \
  --data-urlencode "email=client@example.com"

addcredit¶

Add credit to a client's account balance.

POST /api/v1/addcredit

Permission: create_clients

Parameters

Name	Type	Required	Description
`clientid`	integer	yes	The client.
`description`	string	yes	What the credit is for.
`amount`	number	yes	At least 0.01.

Response

Field	Description
`result`	`success`

Note

Adds to the client credit balance and records the entry in one step.

Example

curl -X POST https://example.com/api/v1/addcredit \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "clientid=1" \
  --data-urlencode "description=example" \
  --data-urlencode "amount=10.00"

adduser¶

Create a client-area login.

POST /api/v1/adduser

Permission: create_clients

Parameters

Name	Type	Required	Description
`email`	email	yes	Must not belong to another login.
`password`	string	yes	At least 8 characters.
`first_name`	string	yes	First name.
`last_name`	string	yes	Last name.
`clientid`	integer	no	Attach the new login to this client account.

Response

Field	Description
`result`	`success`
`userid`	integer

Example

curl -X POST https://example.com/api/v1/adduser \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "email=client@example.com" \
  --data-urlencode "password=example" \
  --data-urlencode "first_name=example" \
  --data-urlencode "last_name=example"

applycredit¶

Apply client credit to an invoice.

POST /api/v1/applycredit

Permission: manage_invoices

Parameters

Name	Type	Required	Description
`invoiceid`	integer	yes	The invoice to pay from credit.
`amount`	number	yes	At least 0.01, and no more than the client credit balance.
`clientid`	integer	no	When sent, must be the owner of the invoice.

Response

Field	Description
`result`	`success`
`invoiceid`	integer
`amount`	number
`remaining_credit`	number

Errors

Status	When
400	clientid is not the owner of the invoice, or the amount is more than the balance.
404	No such invoice.

Note

Spends existing credit on an invoice. To give a client credit, use addcredit.

Example

curl -X POST https://example.com/api/v1/applycredit \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "invoiceid=1" \
  --data-urlencode "amount=10.00"

closeclient¶

Close a client account.

POST /api/v1/closeclient

Permission: edit_clients

Parameters

Name	Type	Required	Description
`clientid`	integer	yes	The client.

Response

Field	Description
`result`	`success`
`clientid`	integer

Errors

Status	When
404	No such client.

Note

Sets the status to closed. Nothing is deleted.

Example

curl -X POST https://example.com/api/v1/closeclient \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "clientid=1"

createclientinvite¶

Invite someone to a client account.

POST /api/v1/createclientinvite

Permission: edit_clients

Parameters

Name	Type	Required	Description
`clientid`	integer	yes	The client account. client_id is accepted too.
`email`	email	yes	Who to invite.
`permissions`	string	no	all (the default), or a comma-separated list of: profile, contacts, products, manageproducts, productsso, domains, managedomains, invoices, quotes, tickets, affiliates, emails, orders.

Response

Field	Description
`result`	`success`
`inviteid`	integer
`email`	string
`permissions`	array or "all"

Errors

Status	When
409	That address already has a login on the account.
422	An unknown permission was named.

Note

The person gets an email with a link that is valid for 7 days. They create a login or sign in with theirs, and join the account with these permissions.

Example

curl -X POST https://example.com/api/v1/createclientinvite \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "clientid=7" \
  --data-urlencode "email=accounts@example.com" \
  --data-urlencode "permissions=invoices,tickets"

createssotoken¶

Create a one-time sign-in link to the client area.

POST /api/v1/createssotoken

Permission: edit_clients

Parameters

Name	Type	Required	Description
`client_id`	integer	yes	The client account. clientid is accepted too.
`user_id`	integer	no	Which login to sign in as. Default: the account owner. userid is accepted too.
`destination`	string	no	clientarea:homepage (default), clientarea:invoices, clientarea:services, clientarea:domains, clientarea:tickets, clientarea:product_details (with service_id), clientarea:domain_details (with domain_id) or sso:custom_redirect (with sso_redirect_path).
`service_id`	integer	no	For clientarea:product_details; must be on the account.
`domain_id`	integer	no	For clientarea:domain_details; must be on the account.
`sso_redirect_path`	string	no	For sso:custom_redirect: a path inside the client area, such as /client/invoices.

Response

Field	Description
`result`	`success`
`access_token`	string
`redirect_url`	string: open this to be signed in
`expires_in`	integer: 60 (seconds)

Errors

Status	When
404	The account has no login to sign in as.
422	Unknown destination, or it is not on this account.

Note

The link works once and for 60 seconds. Only its hash is stored. Needs the same permission as signing in as a client from the admin area (edit_clients).

Example

curl -X POST https://example.com/api/v1/createssotoken \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "client_id=7" \
  --data-urlencode "destination=clientarea:invoices"

deleteclient¶

Delete a client account.

POST /api/v1/deleteclient

Permission: delete_clients

Parameters

Name	Type	Required	Description
`clientid`	integer	yes	The client.

Response

Field	Description
`result`	`success`
`clientid`	integer

Errors

Status	When
404	No such client.
422	The client still has services that are not terminated, or registered domains.

Note

Terminate the services first, as in the admin area, so the accounts are really closed on the servers.

Example

curl -X POST https://example.com/api/v1/deleteclient \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "clientid=1"

deletecontact¶

Delete a sub-contact.

POST /api/v1/deletecontact

Permission: delete_clients

Parameters

Name	Type	Required	Description
`contactid`	integer	yes	The contact.

Response

Field	Description
`result`	`success`

Errors

Status	When
404	No such contact.

Example

curl -X POST https://example.com/api/v1/deletecontact \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "contactid=1"

deleteuserclient¶

Remove a login from a client account.

POST /api/v1/deleteuserclient

Permission: delete_clients

Parameters

Name	Type	Required	Description
`userid`	integer	yes	The login.
`clientid`	integer	yes	The client account to take it off.

Response

Field	Description
`result`	`success`
`userid`	integer
`clientid`	integer

Errors

Status	When
404	No such login, or it is not on that account.

Note

Only the link goes: the login keeps any other accounts it belongs to.

Example

curl -X POST https://example.com/api/v1/deleteuserclient \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "userid=1" \
  --data-urlencode "clientid=1"

getclientgroups¶

List all client groups.

GET /api/v1/getclientgroups

Permission: list_clients

Parameters

None.

Response

Field	Description
`result`	`success`
`groups`	array of every client group

Example

curl -G https://example.com/api/v1/getclientgroups \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

getclientpassword¶

Read a client password (not available).

GET /api/v1/getclientpassword

Permission: list_clients

Not available

Always answers 403: passwords are stored hashed and cannot be read back. Use resetpassword to send a reset link.

getclients¶

List clients with optional search/filtering.

GET /api/v1/getclients

Permission: list_clients

Parameters

Name	Type	Required	Description
`search`	string	no	Matches first name, last name, email or company name.
`status`	string	no	active, inactive or closed.
`group_id`	integer	no	Only clients in this client group.
`orderby`	string	no	id (default), first_name, last_name, email, company_name, status or created_at.
`sorting`	string	no	ASC (default) or DESC.
`limitstart`	integer	no	Where the page starts. Default 0.
`limitnum`	integer	no	Page size, 1 to 250. Default 25.

Response

Field	Description
`result`	`success`
`totalresults`	integer: rows matching the filters
`startnumber`	integer: where this page starts
`numreturned`	integer: rows on this page
`data`	array: the rows

Example

curl -G https://example.com/api/v1/getclients \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

getclientsdetails¶

Get full details for a single client.

GET /api/v1/getclientsdetails

Permission: list_clients

Parameters

Name	Type	Required	Description
`clientid`	integer	no	The client. Required unless email is sent.
`email`	email	no	Find the client by address instead.

One of clientid or email is required.

Response

Field	Description
`result`	`success`
`client`	object: the client with its contacts

Errors

Status	When
400	Neither clientid nor email was sent.
404	No such client.

Example

curl -G https://example.com/api/v1/getclientsdetails \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "clientid=1"

getcontacts¶

Get sub-contacts for a client.

GET /api/v1/getcontacts

Permission: list_clients

Parameters

Name	Type	Required	Description
`userid`	integer	no	Only this client's contacts.
`limitstart`	integer	no	Where the page starts. Default 0.
`limitnum`	integer	no	Page size, 1 to 250. Default 25.

Response

Field	Description
`result`	`success`
`totalresults`	integer: rows matching the filters
`startnumber`	integer: where this page starts
`numreturned`	integer: rows on this page
`data`	array: the rows

Example

curl -G https://example.com/api/v1/getcontacts \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

getcredits¶

List credit entries.

GET /api/v1/getcredits

Permission: list_clients

Parameters

Name	Type	Required	Description
`clientid`	integer	no	Only this client's credit history.

Response

Field	Description
`result`	`success`
`credits`	array of credit entries, newest first

Example

curl -G https://example.com/api/v1/getcredits \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

getuserpermissions¶

Get what a login may do on a client account.

GET /api/v1/getuserpermissions

Permission: list_clients

Parameters

Name	Type	Required	Description
`userid`	integer	yes	The login. user_id is accepted too.
`clientid`	integer	yes	The client account. client_id is accepted too.

Response

Field	Description
`result`	`success`
`userid`	integer
`clientid`	integer
`owner`	boolean
`permissions`	array or "all"

Errors

Status	When
404	The login is not on that account.

Example

curl -G https://example.com/api/v1/getuserpermissions \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "userid=1" \
  --data-urlencode "clientid=1"

getusers¶

List client-area logins.

GET /api/v1/getusers

Permission: list_clients

Parameters

Name	Type	Required	Description
`clientid`	integer	no	Only the logins on this client account.
`limitstart`	integer	no	Where the page starts. Default 0.
`limitnum`	integer	no	Page size, 1 to 250. Default 25.

Response

Field	Description
`result`	`success`
`users`	array of client-area logins (one page)

Note

A login (user) can open several client accounts; a client account can have several logins.

Example

curl -G https://example.com/api/v1/getusers \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

updateclient¶

Update an existing client's details.

POST /api/v1/updateclient

Permission: edit_clients

Parameters

Name	Type	Required	Description
`clientid`	integer	yes	The client.
`firstname`	string	no	Cannot be empty.
`lastname`	string	no	Cannot be empty.
`email`	email	no	Must not belong to another client.
`companyname`	string	no	Company name.
`address1`	string	no	Street address.
`city`	string	no	City.
`state`	string	no	State or region.
`postcode`	string	no	Postal code.
`country`	string	no	Two-letter country code.
`phonenumber`	string	no	Phone number.
`status`	string	no	active, inactive or closed.

Response

Field	Description
`result`	`success`
`clientid`	integer

Errors

Status	When
404	No such client.

Note

Only the fields you send are changed.

Example

curl -X POST https://example.com/api/v1/updateclient \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "clientid=1"

updatecontact¶

Update a sub-contact.

POST /api/v1/updatecontact

Permission: edit_clients

Parameters

Name	Type	Required	Description
`contactid`	integer	yes	The contact.
`firstname`	string	no	Cannot be empty.
`lastname`	string	no	Cannot be empty.
`email`	email	no	Address.

Response

Field	Description
`result`	`success`
`contactid`	integer

Errors

Status	When
404	No such contact.

Example

curl -X POST https://example.com/api/v1/updatecontact \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "contactid=1"

updateuser¶

Update a client-area login.

POST /api/v1/updateuser

Permission: edit_clients

Parameters

Name	Type	Required	Description
`userid`	integer	yes	The login.
`email`	email	no	Must not belong to another login.
`first_name`	string	no	First name.
`last_name`	string	no	Last name.
`password`	string	no	At least 8 characters.

Response

Field	Description
`result`	`success`
`userid`	integer

Errors

Status	When
404	No such login.

Example

curl -X POST https://example.com/api/v1/updateuser \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "userid=1"

updateuserpermissions¶

Change what a login may do on a client account.

POST /api/v1/updateuserpermissions

Permission: edit_clients

Parameters

Name	Type	Required	Description
`userid`	integer	yes	The login. user_id is accepted too.
`clientid`	integer	yes	The client account. client_id is accepted too.
`permissions`	string	yes	all, or a comma-separated list (see createclientinvite).

Response

Field	Description
`result`	`success`
`userid`	integer
`clientid`	integer
`permissions`	array or "all"

Errors

Status	When
404	The login is not on that account.
422	The login is the account owner (who always has everything), or an unknown permission was named.

Note

Enforced in the client area: a login without a permission cannot open that part of the account.

Example

curl -X POST https://example.com/api/v1/updateuserpermissions \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "userid=1" \
  --data-urlencode "clientid=1" \
  --data-urlencode "permissions=example"