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": []
}
}
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": []
}
}
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": []
}
}
| 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 |
| 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. |
| 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) | ||
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.
Adds an invoice for the client. Full documentation is in the Invoice section.
Adds a recurring invoice to the client. Full documentation is in the Invoice section.
Adds a user to the client. Full documentation is available in the User section.
Generate an invoice for the client with due services and charges. Full documentation is in the Invoice section.
Adds a service to a client. Full documentation is in the service section.
Adds a Signup to the client. Full documentation is available in the Signup section.
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"
}
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"
}
Lists all the current accounts clients.
Results can optionally be filtered by the filters listed below.
| Name | Availability | Description |
|---|---|---|
| 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. |