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
}