Docs

User Tools

Site Tools

Trace: • Clients
developers:api:client

Table of Contents

Clients

/v1/client/id/get

Retrieve a client by id and return it's details. 

    $ curl -u user:pass -d "" \
    >      https://api.snapbill.com/v1/client/158975/get.json

File: examples/client.txt-1.json - 

    {
      "code": 200,
      "type": "item",
      "class": "client",
      "client": {
        "depth": 0,
        "id": 158975,
        "xid": "Clw:mz_",
        "state": "active",
        "number": "018",
        "name": "jane",
        "account": {
          "depth": 1,
          "id": 10608,
          "xid": "Clw:Clw",
          "username": "demo"
        },
        "cell": "",
        "company": "",
        "country": {
          "code": "ZA",
          "iso2": "ZA",
          "iso3": "ZAF",
          "name": "South Africa"
        },
        "credit": "0.00",
        "credit_cents": 0,
        "currency": {
          "code": "ZAR",
          "format": "R%.2f",
          "enabled": true
        },
        "discount": "0.00",
        "email": "jane@example.com",
        "firstname": "jane",
        "payment": "netcash",
        "payment_method": {
          "depth": 1,
          "code": "netcash",
          "name": "Netcash Collect",
          "enabled": true
        },
        "surname": "",
        "totals": {
          "unpaid_invoices": "0.00",
          "unpaid_invoices_cents": 0,
          "paid_payments": "0.00",
          "paid_payments_cents": 0
        },
        "urls": {
          "statement": "https://demo.snapbill.com/statement/Clw:mz_/=YzhjNzU1Y2Mx",
          "payment": "https://demo.snapbill.com/payment/client/Clw:mz_/=NTdkMTBmMTIz"
        },
        "data": {
          "public_city": null,
          "public_country": null,
          "public_fax": null,
          "public_phone": null,
          "public_postal": null,
          "public_postcode": null,
          "public_province": null,
          "public_street": null,
          "vat_number": null
        },
        "services": []
      }
    }

/v1/client/add

Creates a new client and returns it's details. 

    $ curl -u user:pass -d "firstname=jane&email=jane@example.com" \
    >      https://api.snapbill.com/v1/client/add.json

File: examples/client.txt-2.json - 

    {
      "code": 200,
      "type": "item",
      "class": "client",
      "client": {
        "depth": 0,
        "id": 158975,
        "xid": "Clw:mz_",
        "state": "active",
        "number": "018",
        "name": "jane",
        "account": {
          "depth": 1,
          "id": 10608,
          "xid": "Clw:Clw",
          "username": "demo"
        },
        "cell": "",
        "company": "",
        "country": {
          "code": "ZA",
          "iso2": "ZA",
          "iso3": "ZAF",
          "name": "South Africa"
        },
        "credit": "0.00",
        "credit_cents": 0,
        "currency": {
          "code": "ZAR",
          "format": "R%.2f",
          "enabled": true
        },
        "discount": "0.00",
        "email": "jane@example.com",
        "firstname": "jane",
        "payment": "netcash",
        "payment_method": {
          "depth": 1,
          "code": "netcash",
          "name": "Netcash Collect",
          "enabled": true
        },
        "surname": "",
        "totals": {
          "unpaid_invoices": "0.00",
          "unpaid_invoices_cents": 0,
          "paid_payments": "0.00",
          "paid_payments_cents": 0
        },
        "urls": {
          "statement": "https://demo.snapbill.com/statement/Clw:mz_/=YzhjNzU1Y2Mx",
          "payment": "https://demo.snapbill.com/payment/client/Clw:mz_/=NTdkMTBmMTIz"
        },
        "data": {
          "public_city": null,
          "public_country": null,
          "public_fax": null,
          "public_phone": null,
          "public_postal": null,
          "public_postcode": null,
          "public_province": null,
          "public_street": null,
          "vat_number": null
        },
        "services": []
      }
    }

/v1/client/id/update

Updates details about the given client in the database 

    $ curl -u user:pass -d "company=helkom&state=suspended" \
    >      https://api.snapbill.com/v1/client/158975/update.json

File: examples/client.txt-3.json - 

    {
      "code": 200,
      "type": "result",
      "status": "ok",
      "class": "client",
      "client": {
        "depth": 0,
        "id": 158975,
        "xid": "Clw:mz_",
        "state": "active",
        "number": "018",
        "name": "helkom (jane)",
        "account": {
          "depth": 1,
          "id": 10608,
          "xid": "Clw:Clw",
          "username": "demo"
        },
        "cell": "",
        "company": "helkom",
        "country": {
          "code": "ZA",
          "iso2": "ZA",
          "iso3": "ZAF",
          "name": "South Africa"
        },
        "credit": "0.00",
        "credit_cents": 0,
        "currency": {
          "code": "ZAR",
          "format": "R%.2f",
          "enabled": true
        },
        "discount": "0.00",
        "email": "jane@example.com",
        "firstname": "jane",
        "payment": "netcash",
        "payment_method": {
          "depth": 1,
          "code": "netcash",
          "name": "Netcash Collect",
          "enabled": true
        },
        "surname": "",
        "totals": {
          "unpaid_invoices": "0.00",
          "unpaid_invoices_cents": 0,
          "paid_payments": "0.00",
          "paid_payments_cents": 0
        },
        "urls": {
          "statement": "https://demo.snapbill.com/statement/Clw:mz_/=YzhjNzU1Y2Mx",
          "payment": "https://demo.snapbill.com/payment/client/Clw:mz_/=NTdkMTBmMTIz"
        },
        "data": {
          "public_city": null,
          "public_country": null,
          "public_fax": null,
          "public_phone": null,
          "public_postal": null,
          "public_postcode": null,
          "public_province": null,
          "public_street": null,
          "vat_number": null
        },
        "services": []
      }
    }

Available states

Name Description
new The state that all new clients are created in
active The state for a normal active client
suspended This client has been suspended and can no longer access any services
dead The client has been removed and is no longer visible through the interface

Parameter listing

Name Availability Description
depth get The depth parameter signals the amount of data for the client that was provided. depth=0 is the highest level that provides full detail, while depth=2 only provides id, state, number and name
id get The id of the client in the system. This is guaranteed to be unique only over a single account.
xid get The xid of the client in the system. This is guaranteed to be unique over all accounts (see Concepts - Xid)
state get update The state of the client in the system. The available states are new, active, suspended and dead. For more details see States.
number add get update A unique number representing the client. Note that this can contain any characters instead of just numbers. If not provided to an add call it will automatically be generated.
name get Automatically generated display name for the client, based on available details (firstname, surname, company)
firstname add get update Clients firstname. This field is required unless either surname, or company are provided.
surname add get update Clients surname. This field is required unless either firstname, or company are provided.
company add get update Clients company. This field is required unless either firstname, or surname are provided.
email add get update Email address for the client. This is used as the default address for all communication and nothing can/will be sent unless it is provided or a relevant contact is added.
cell add get update Cellphone number for the client. This is the default number for SMS communication unless a relevant contact is added.
country get An object representing the country the user is from. Use country_code for add or update operations.
country_code add update The ISO2 code of the country that the client is from. This is automatically detected based on IP address during a signup.
credit get update The total amount of credit on a users account. Any manual changes to this will automatically log a credit-typed payment which will appear on the clients statements (note this behaviour is likely to change in the future).
currency get An object reperesenting the currency the client is using. Use currency_code for add or update operations.
currency_code add update The ISO 4217 code for the currency the client is currently using. This can only be updated if the client has zero unpaid invoices, no recurring services and no charges.
payment get This is deprecated, please use payment_method_code instead
payment_method get An object reperesenting the payment method the client is set to. Use payment_method_code for add or update operations.
payment_method_code add update A short code representing one of the payment methods used by SnapBill.
reseller get An object representing the account that owns the client
totals get An object with quick details about the finanical totals of a given account
↳ unpaid_invoices get The total sum of the totals from unpaid invoices on the account
↳ total_paid get The total sum of payments that are marked as paid on the account
urls get An object with permalinks to access the clients details
↳ statement get A permalink to the clients statement in the client area (includes authorization)

/v1/client/id/lost_password

Used to recover a client's password. Submit a post request and a password recovery email will be sent to the email account associated with this client.

/v1/client/id/add_invoice

Adds an invoice for the client. Full documentation is in the Invoice section.

/v1/client/id/add_recurring_invoice

Adds a recurring invoice to the client. Full documentation is in the Invoice section.

/v1/client/id/add_user

Adds a user to the client. Full documentation is available in the User section.

/v1/client/id/generate_invoice

Generate an invoice for the client with due services and charges. Full documentation is in the Invoice section.

/v1/client/id/add_service

Adds a service to a client. Full documentation is in the service section.

/v1/client/id/add_signup

Adds a Signup to the client. Full documentation is available in the Signup section.

/v1/client/id/set_payment

Sets the payment method and details for a client. The parameters passed in depend on the payment method. To find out the parameters visit https://api.snapbill.com/v1/client/id/set_payment.json?post or https://api.snapbill.com/v1/client/id/set_payment

The example below updates the payment type to other which requires no extra parameters. 

    $ curl -u user:pass -d "payment_method_code=other" \
    >      https://api.snapbill.com/v1/client/158975/set_payment.json

File: examples/client.txt-4.json - 

    {
      "code": 200,
      "type": "result",
      "status": "ok"
    }

/v1/client/id/delete

Deletes a client from the database 

    $ curl -u user:pass -d "" \
    >      https://api.snapbill.com/v1/client/158975/delete.json

File: examples/client.txt-5.json - 

    {
      "code": 200,
      "type": "result",
      "status": "ok"
    }

/v1/client/list

Lists all the current accounts clients.

Results can optionally be filtered by the filters listed below.

List Clients Filters

Name Availability Description
email get The email address of the clients.
query get A search query. This parameter is handled in the same way as the search on billing.snapbill.com works.
page get The page of results to return.
perpage get The number of results per page to return.
developers/api/client.txt · Last modified: 2014/10/18 07:13 by Jaco van Wyk

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3
GNU Free Documentation License 1.3 Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki