Accounts

Accounts represent billable entities in the system. For more information see here.

An account is a member of the crm module and provides information about a system account.

An account record holds the following information:

  • shipping_address_locality
  • import_id
  • primary_contact_id
  • tel
  • address_unit
  • converted_balance
  • default_approver
  • company_number
  • no_publicity
  • url
  • shipping_address_street
  • vat_number
  • address_postcode
  • billing_address_country_id
  • address_country
  • id
  • shipping_address_postcode
  • industries
  • address_street
  • source
  • address_region
  • is_employee
  • default_price_level_id
  • is_individual
  • is_supplier
  • parent_id
  • source_details
  • notes
  • billing_contact_person
  • billing_address_locality
  • is_partner
  • email
  • billing_address_region
  • fax
  • account_type
  • description
  • tags
  • company
  • billing_address_unit
  • partner_type
  • default_price_level
  • address_town
  • billing_address_postcode
  • shipping_address_town
  • billing_address_street
  • shipping_address_region
  • shipping_address_country_id
  • is_deleted
  • name
  • customer_since
  • mobile
  • shipping_contact_person
  • created
  • shipping_address_unit
  • is_customer
  • address_locality
  • initial_contact_id
  • balance
  • external_id
  • bank_details
  • billing_address_town

Getting Accounts

GET (/api/v2/crm/accounts/:id()

  • statuscode 200

    no error

  • statuscode 404

    does not exist

Using Curl:

curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts/4     -k -u (login):(password)

Using PHP:

<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts/4';
$options = array(
  'http' => array(
    'method'  => 'GET',
    'header'=>  "Accept: application/json\r\n" .
                "Authorization: Basic " . base64_encode($credentials)
    )
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Using Python:

import json
import requests

response = requests.get('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts/4',
                         auth=('<username>', '<password>'))

print response.json

Example response:

{
    "shipping_address_locality": null,
    "import_id": null,
    "primary_contact_id": null,
    "tel": null,
    "address_unit": null,
    "converted_balance": null,
    "default_approver": 0,
    "company_number": null,
    "no_publicity": null,
    "url": null,
    "shipping_address_street": null,
    "vat_number": null,
    "address_postcode": null,
    "billing_address_country_id": null,
    "address_country": null,
    "id": 4,
    "shipping_address_postcode": null,
    "industries": [],
    "address_street": null,
    "source": null,
    "address_region": null,
    "is_employee": false,
    "default_price_level_id": null,
    "is_individual": false,
    "is_supplier": false,
    "parent_id": null,
    "source_details": null,
    "notes": null,
    "billing_contact_person": null,
    "billing_address_locality": null,
    "is_partner": false,
    "email": null,
    "billing_address_region": null,
    "fax": null,
    "account_type": null,
    "description": null,
    "tags": null,
    "company": {
        "registration_numbers": null,
        "code": "ACM",
        "name": "Acme Corporation",
        "settings": {
            "time_format": "H:i",
            "date_format": "Y-m-d",
            "locale": "en_GB",
            "week_starts": null,
            "non_working_days": null
        },
        "bank_details": null,
        "currency": {
            "code": "GBP",
            "name": "British Pound Sterling",
            "symbol": "\u00a3",
            "html_code": null,
            "id": 1,
            "is_base": true
        },
        "id": 1,
        "currency_code": "GBP",
        "account_id": null
    },
    "billing_address_unit": null,
    "partner_type": null,
    "default_price_level": null,
    "address_town": null,
    "billing_address_postcode": null,
    "shipping_address_town": null,
    "billing_address_street": null,
    "shipping_address_region": null,
    "shipping_address_country_id": null,
    "is_deleted": false,
    "name": "My account",
    "customer_since": null,
    "mobile": null,
    "shipping_contact_person": null,
    "created": "2016-12-13T11:23:23",
    "shipping_address_unit": null,
    "is_customer": true,
    "address_locality": null,
    "initial_contact_id": null,
    "balance": {},
    "external_id": null,
    "bank_details": null,
    "billing_address_town": null
}

Getting the Account Balance

The balance field will show the balance on this account broken down by currency in which the invoices were issued in. You can pass in a display_currency parameter which will convert all of these to a single currency, which will be in the converted_currency field.

Example

GET (/api/v2/crm/accounts/:id?display_currency=USD()

{
  "balance": {
    "GBP": 3241,
    "EUR": 1234
  },
  "converted_balance": 5427
}

Getting more than one Account

GET (/api/v2/crm/accounts()

  • statuscode 200

    no error

  • statuscode 404

    does not exist

Using Curl:

curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts     -k -u (login):(password)

Using PHP:

<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts';
$options = array(
  'http' => array(
    'method'  => 'GET',
    'header'=>  "Accept: application/json\r\n" .
                "Authorization: Basic " . base64_encode($credentials)
    )
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Using Python:

import json
import requests

response = requests.get('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts',
                         auth=('<username>', '<password>'))

print response.json

Example response:

[
    {
        "shipping_address_locality": null,
        "import_id": null,
        "primary_contact_id": null,
        "tel": null,
        "address_unit": null,
        "default_approver": 0,
        "company_number": null,
        "no_publicity": null,
        "url": null,
        "shipping_address_street": null,
        "vat_number": null,
        "address_postcode": null,
        "billing_address_country_id": null,
        "address_country": null,
        "id": 2,
        "shipping_address_postcode": null,
        "industries": [],
        "address_street": null,
        "source": null,
        "address_region": null,
        "is_employee": false,
        "default_price_level_id": null,
        "is_individual": false,
        "is_supplier": false,
        "parent_id": null,
        "source_details": null,
        "notes": null,
        "billing_contact_person": null,
        "billing_address_locality": null,
        "is_partner": false,
        "email": null,
        "billing_address_region": null,
        "fax": null,
        "account_type": null,
        "description": null,
        "tags": null,
        "company": {
            "registration_numbers": null,
            "code": "ACM",
            "name": "Acme Corporation",
            "settings": {
                "time_format": "H:i",
                "date_format": "Y-m-d",
                "locale": "en_GB",
                "week_starts": null,
                "non_working_days": null
            },
            "bank_details": null,
            "currency": {
                "code": "GBP",
                "name": "British Pound Sterling",
                "symbol": "\u00a3",
                "html_code": null,
                "id": 1,
                "is_base": true
            },
            "id": 1,
            "currency_code": "GBP",
            "account_id": null
        },
        "billing_address_unit": null,
        "partner_type": null,
        "default_price_level": null,
        "address_town": null,
        "billing_address_postcode": null,
        "shipping_address_town": null,
        "billing_address_street": null,
        "shipping_address_region": null,
        "shipping_address_country_id": null,
        "is_deleted": false,
        "name": "My account",
        "customer_since": null,
        "mobile": null,
        "shipping_contact_person": null,
        "created": "2016-12-13T11:23:23",
        "shipping_address_unit": null,
        "is_customer": true,
        "address_locality": null,
        "initial_contact_id": null,
        "external_id": null,
        "bank_details": null,
        "billing_address_town": null
    },
    {
        "shipping_address_locality": null,
        "import_id": null,
        "primary_contact_id": null,
        "tel": null,
        "address_unit": null,
        "default_approver": 0,
        "company_number": null,
        "no_publicity": null,
        "url": null,
        "shipping_address_street": null,
        "vat_number": null,
        "address_postcode": null,
        "billing_address_country_id": null,
        "address_country": null,
        "id": 3,
        "shipping_address_postcode": null,
        "industries": [],
        "address_street": null,
        "source": null,
        "address_region": null,
        "is_employee": false,
        "default_price_level_id": null,
        "is_individual": false,
        "is_supplier": false,
        "parent_id": null,
        "source_details": null,
        "notes": null,
        "billing_contact_person": null,
        "billing_address_locality": null,
        "is_partner": false,
        "email": null,
        "billing_address_region": null,
        "fax": null,
        "account_type": null,
        "description": null,
        "tags": null,
        "company": {
            "registration_numbers": null,
            "code": "ACM",
            "name": "Acme Corporation",
            "settings": {
                "time_format": "H:i",
                "date_format": "Y-m-d",
                "locale": "en_GB",
                "week_starts": null,
                "non_working_days": null
            },
            "bank_details": null,
            "currency": {
                "code": "GBP",
                "name": "British Pound Sterling",
                "symbol": "\u00a3",
                "html_code": null,
                "id": 1,
                "is_base": true
            },
            "id": 1,
            "currency_code": "GBP",
            "account_id": null
        },
        "billing_address_unit": null,
        "partner_type": null,
        "default_price_level": null,
        "address_town": null,
        "billing_address_postcode": null,
        "shipping_address_town": null,
        "billing_address_street": null,
        "shipping_address_region": null,
        "shipping_address_country_id": null,
        "is_deleted": false,
        "name": "Another account",
        "customer_since": null,
        "mobile": null,
        "shipping_contact_person": null,
        "created": "2016-12-13T11:23:23",
        "shipping_address_unit": null,
        "is_customer": false,
        "address_locality": null,
        "initial_contact_id": null,
        "external_id": null,
        "bank_details": null,
        "billing_address_town": null
    }
]

Filtering

The results for a list of accounts can be filtered. See Filtering. Accounts also support filtering on custom fields. Simply prefix the custom field with custom_fields. and use the standard filtering syntax.

Example:

GET (/api/v2/crm/accounts?custom_fields.field_319__eq=10()

Creating Accounts

POST (/api/v2/crm/accounts()

Required fields:

  • company_id
  • name
  • statuscode 200

    no error

  • statuscode 404

    could not create

Using Curl:

curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts     -H "Content-Type: application/json"     -k -u (login):(password)     -X POST     -d '{"is_customer": true, "name": "My account", "company_id": 1}'

Using PHP:

<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts';
$data = array("is_customer" => True, "name" => u'My account', "company_id" => 1);
$options = array(
'http' => array(
'method'  => 'POST',
'content' => json_encode($data),
'header'=>  "Content-Type: application/json\r\n" .
            "Accept: application/json\r\n" .
            "Authorization: Basic " . base64_encode($credentials)
)
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Using Python:

import json
import requests

data = {u'is_customer': True, u'name': u'My account', u'company_id': 1}

response = requests.post('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts',
                        data=json.dumps(data),
                        headers={'content-type': 'application/json'},
                        auth=('<username>', '<password>'))

print response.json

Example response:

{
    "shipping_address_locality": null,
    "import_id": null,
    "primary_contact_id": null,
    "tel": null,
    "address_unit": null,
    "converted_balance": null,
    "default_approver": 0,
    "company_number": null,
    "no_publicity": null,
    "url": null,
    "shipping_address_street": null,
    "vat_number": null,
    "address_postcode": null,
    "billing_address_country_id": null,
    "address_country": null,
    "id": 4,
    "shipping_address_postcode": null,
    "industries": [],
    "address_street": null,
    "source": null,
    "address_region": null,
    "is_employee": false,
    "default_price_level_id": null,
    "is_individual": false,
    "is_supplier": false,
    "parent_id": null,
    "source_details": null,
    "notes": null,
    "billing_contact_person": null,
    "billing_address_locality": null,
    "is_partner": false,
    "email": null,
    "billing_address_region": null,
    "fax": null,
    "account_type": null,
    "description": null,
    "tags": null,
    "company": {
        "registration_numbers": null,
        "code": "ACM",
        "name": "Acme Corporation",
        "settings": {
            "time_format": "H:i",
            "date_format": "Y-m-d",
            "locale": "en_GB",
            "week_starts": null,
            "non_working_days": null
        },
        "bank_details": null,
        "currency": {
            "code": "GBP",
            "name": "British Pound Sterling",
            "symbol": "\u00a3",
            "html_code": null,
            "id": 1,
            "is_base": true
        },
        "id": 1,
        "currency_code": "GBP",
        "account_id": null
    },
    "billing_address_unit": null,
    "partner_type": null,
    "default_price_level": null,
    "address_town": null,
    "billing_address_postcode": null,
    "shipping_address_town": null,
    "billing_address_street": null,
    "shipping_address_region": null,
    "shipping_address_country_id": null,
    "is_deleted": false,
    "name": "My account",
    "customer_since": null,
    "mobile": null,
    "shipping_contact_person": null,
    "created": "2016-12-13T11:23:23",
    "shipping_address_unit": null,
    "is_customer": true,
    "address_locality": null,
    "initial_contact_id": null,
    "balance": {},
    "external_id": null,
    "bank_details": null,
    "billing_address_town": null
}

Updating Accounts

PUT (/api/v2/crm/accounts/(int: id)

  • statuscode 200

    no error

  • statuscode 404

    does not exist

Using Curl:

curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts/6     -H "Content-Type: application/json"     -k -u (login):(password)     -X PUT     -d '{"name": "My new value for name"}'

Using PHP:

<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts/6';
$data = array("name" => u'My new value for name');
$options = array(
'http' => array(
'method'  => 'PUT',
'content' => json_encode($data),
'header'=>  "Content-Type: application/json\r\n" .
            "Accept: application/json\r\n" .
            "Authorization: Basic " . base64_encode($credentials)
)
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Using Python:

import json
import requests

data = {u'name': u'My new value for name'}

response = requests.put('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts/6',
                        data=json.dumps(data),
                        headers={'content-type': 'application/json'},
                        auth=('<username>', '<password>'))

print response.json

Example response:

{
    "shipping_address_locality": null,
    "import_id": null,
    "primary_contact_id": null,
    "tel": null,
    "address_unit": null,
    "converted_balance": null,
    "default_approver": 0,
    "company_number": null,
    "no_publicity": null,
    "url": null,
    "shipping_address_street": null,
    "vat_number": null,
    "address_postcode": null,
    "billing_address_country_id": null,
    "address_country": null,
    "id": 6,
    "shipping_address_postcode": null,
    "industries": [],
    "address_street": null,
    "source": null,
    "address_region": null,
    "is_employee": false,
    "default_price_level_id": null,
    "is_individual": false,
    "is_supplier": false,
    "parent_id": null,
    "source_details": null,
    "notes": null,
    "billing_contact_person": null,
    "billing_address_locality": null,
    "is_partner": false,
    "email": null,
    "billing_address_region": null,
    "fax": null,
    "account_type": null,
    "description": null,
    "tags": null,
    "company": {
        "registration_numbers": null,
        "code": "ACM",
        "name": "Acme Corporation",
        "settings": {
            "time_format": "H:i",
            "date_format": "Y-m-d",
            "locale": "en_GB",
            "week_starts": null,
            "non_working_days": null
        },
        "bank_details": null,
        "currency": {
            "code": "GBP",
            "name": "British Pound Sterling",
            "symbol": "\u00a3",
            "html_code": null,
            "id": 1,
            "is_base": true
        },
        "id": 1,
        "currency_code": "GBP",
        "account_id": null
    },
    "billing_address_unit": null,
    "partner_type": null,
    "default_price_level": null,
    "address_town": null,
    "billing_address_postcode": null,
    "shipping_address_town": null,
    "billing_address_street": null,
    "shipping_address_region": null,
    "shipping_address_country_id": null,
    "is_deleted": false,
    "name": "My new value for name",
    "customer_since": null,
    "mobile": null,
    "shipping_contact_person": null,
    "created": "2016-12-13T11:23:24",
    "shipping_address_unit": null,
    "is_customer": true,
    "address_locality": null,
    "initial_contact_id": null,
    "balance": {},
    "external_id": null,
    "bank_details": null,
    "billing_address_town": null
}

Deleting Accounts

DELETE (/api/v2/crm/accounts/(int: id)

  • statuscode 200

    deleted entity successfully

  • statuscode 404

    entity not found

Using Curl:

curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts/1     -X DELETE -k -u (login):(password)

Using PHP:

<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts/1';
$options = array(
  'http' => array(
    'method'  => 'DELETE',
    'header'=>  "Accept: application/json\r\n" .
                "Authorization: Basic " . base64_encode($credentials)
    )
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Using Python:

import json
import requests

response = requests.delete('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts/1',
                         auth=('<username>', '<password>'))

print response.json

Example response:

{
    "shipping_address_locality": null,
    "import_id": null,
    "primary_contact_id": null,
    "tel": null,
    "address_unit": null,
    "converted_balance": null,
    "default_approver": 0,
    "company_number": null,
    "no_publicity": null,
    "url": null,
    "shipping_address_street": null,
    "vat_number": null,
    "address_postcode": null,
    "billing_address_country_id": null,
    "address_country": null,
    "id": 1,
    "shipping_address_postcode": null,
    "industries": [],
    "address_street": null,
    "source": null,
    "address_region": null,
    "is_employee": false,
    "default_price_level_id": null,
    "is_individual": false,
    "is_supplier": false,
    "parent_id": null,
    "source_details": null,
    "notes": null,
    "billing_contact_person": null,
    "billing_address_locality": null,
    "is_partner": false,
    "email": null,
    "billing_address_region": null,
    "fax": null,
    "account_type": null,
    "description": null,
    "tags": null,
    "company": {
        "registration_numbers": null,
        "code": "ACM",
        "name": "Acme Corporation",
        "settings": {
            "time_format": "H:i",
            "date_format": "Y-m-d",
            "locale": "en_GB",
            "week_starts": null,
            "non_working_days": null
        },
        "bank_details": null,
        "currency": {
            "code": "GBP",
            "name": "British Pound Sterling",
            "symbol": "\u00a3",
            "html_code": null,
            "id": 1,
            "is_base": true
        },
        "id": 1,
        "currency_code": "GBP",
        "account_id": null
    },
    "billing_address_unit": null,
    "partner_type": null,
    "default_price_level": null,
    "address_town": null,
    "billing_address_postcode": null,
    "shipping_address_town": null,
    "billing_address_street": null,
    "shipping_address_region": null,
    "shipping_address_country_id": null,
    "is_deleted": true,
    "name": "My account",
    "customer_since": null,
    "mobile": null,
    "shipping_contact_person": null,
    "created": "2016-12-13T11:23:23",
    "shipping_address_unit": null,
    "is_customer": true,
    "address_locality": null,
    "initial_contact_id": null,
    "balance": {},
    "external_id": null,
    "bank_details": null,
    "billing_address_town": null
}