Administrate

Invoices

Note

The invoices endpoint is part of Version 2.5 (v2.5) of the REST API.

Invoices represent sales in the system.

Fields

Attributes:

  • account_id
  • account_name
  • company_id
  • currency_code
  • date_issued
  • financial_organisation_id
  • id
  • is_contact_notified
  • lifecycle_status
  • number
  • number_of_lines
  • total
  • uri
  • other_ref - a reference to the invoice in an external system

Relations:

  • account - Account
  • company - Company
  • currency - Currency
  • lines - LineItem
  • region - Region

LineItem:

Attributes:

  • id
  • quantity
  • value
  • amount
  • description
  • tax_amount
  • last_modified_timestamp
  • custom_discount_rate
  • date
  • service_date
  • is_taxable

Relations:

  • credit_account - NominalAccount
  • tax_type - TaxType

TaxType

Attributes:

  • id
  • name
  • rate

NominalAccount

Attributes:

  • id
  • name
  • code

Getting Invoices

GET /api/v2.5/finance/invoices/:id
statuscode 200:no error
statuscode 404:does not exist
Using Python:
import json
import requests

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

print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/4 \ 
    -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/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;
Example response:
{
    "account_name": "Acme Corp",
    "number_of_lines": 0,
    "total": 0.0,
    "account_id": 1,
    "other_ref": null,
    "company_id": 1,
    "region": {
        "name": "Scotland",
        "default_tax": null,
        "countries": [],
        "company": {
            "account": {
                "industries": [],
                "num_purchases": 0,
                "name": "Acme Corp",
                "shipping_address_country": null,
                "billing_address_country": null,
                "num_invoices": 1,
                "address_country": null,
                "id": 1
            },
            "name": "Acme Corp",
            "default_tax": null,
            "bank_details": [],
            "timezone": null,
            "incoming_sharing_agreements": [],
            "id": 1
        },
        "locations": [],
        "id": "SCO"
    },
    "date_issued": "2017-10-17T12:38:14Z",
    "lines": [],
    "uri": "/php/viewedit/salesinvoice/4",
    "number": "1",
    "currency": {
        "id": "GBP"
    },
    "account": {
        "is_employee": false,
        "shipping_address_locality": null,
        "address_unit": null,
        "telephone": null,
        "company_number": null,
        "no_publicity": null,
        "shipping_telephone": null,
        "num_invoices": 1,
        "owner": 0,
        "vat_number": null,
        "is_supplier": false,
        "billing_address_country_id": null,
        "address_country": null,
        "id": 1,
        "shipping_address_postcode": null,
        "num_purchases": 0,
        "address_street": null,
        "address_region": null,
        "address_postcode": null,
        "is_venue": false,
        "company_id": null,
        "is_individual": false,
        "source": null,
        "source_details": null,
        "billing_contact_person": null,
        "billing_address_locality": null,
        "is_partner": false,
        "type": null,
        "email": "[email protected]",
        "website": null,
        "custom": {},
        "fax": null,
        "billing_address_unit": null,
        "shipping_address_country": null,
        "billing_telephone": 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,
        "name": "Acme Corp",
        "partner_type": 1,
        "mobile": null,
        "shipping_contact_person": null,
        "address_country_id": null,
        "shipping_address_unit": null,
        "bank_details": null,
        "address_locality": null,
        "billing_address_region": null,
        "shipping_address_street": null,
        "category_id": null,
        "notes": null,
        "billing_address_town": null
    },
    "lifecycle_status": "Draft",
    "is_contact_notified": false,
    "company": {
        "account": {
            "industries": [],
            "num_purchases": 0,
            "name": "Acme Corp",
            "shipping_address_country": null,
            "billing_address_country": null,
            "num_invoices": 1,
            "address_country": null,
            "id": 1
        },
        "name": "Acme Corp",
        "default_tax": null,
        "id": 1,
        "incoming_sharing_agreements": [],
        "bank_details": []
    },
    "id": 4,
    "currency_code": "GBP"
}

Getting more than one Invoice

GET /api/v2.5/finance/invoices
statuscode 200:no error
Using Python:
import json
import requests

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

print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices \ 
    -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices';

$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;
Example response:
[
    {
        "account_name": "Acme Corp",
        "number_of_lines": 0,
        "total": 0.0,
        "account_id": 1,
        "other_ref": null,
        "company_id": 1,
        "region": {
            "name": "Scotland",
            "default_tax": null,
            "countries": [],
            "company": {
                "account": {
                    "industries": [],
                    "num_purchases": 0,
                    "name": "Acme Corp",
                    "shipping_address_country": null,
                    "billing_address_country": null,
                    "num_invoices": 1,
                    "address_country": null,
                    "id": 1
                },
                "name": "Acme Corp",
                "default_tax": null,
                "bank_details": [],
                "timezone": null,
                "incoming_sharing_agreements": [],
                "id": 1
            },
            "locations": [],
            "id": "SCO"
        },
        "date_issued": "2017-10-17T12:38:15Z",
        "lines": [],
        "uri": "/php/viewedit/salesinvoice/12",
        "number": "1",
        "currency": {
            "id": "GBP"
        },
        "account": {
            "is_employee": false,
            "shipping_address_locality": null,
            "address_unit": null,
            "telephone": null,
            "company_number": null,
            "no_publicity": null,
            "shipping_telephone": null,
            "num_invoices": 1,
            "owner": 0,
            "vat_number": null,
            "is_supplier": false,
            "billing_address_country_id": null,
            "address_country": null,
            "id": 1,
            "shipping_address_postcode": null,
            "num_purchases": 0,
            "address_street": null,
            "address_region": null,
            "address_postcode": null,
            "is_venue": false,
            "company_id": null,
            "is_individual": false,
            "source": null,
            "source_details": null,
            "billing_contact_person": null,
            "billing_address_locality": null,
            "is_partner": false,
            "type": null,
            "email": "[email protected]",
            "website": null,
            "custom": {},
            "fax": null,
            "billing_address_unit": null,
            "shipping_address_country": null,
            "billing_telephone": 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,
            "name": "Acme Corp",
            "partner_type": 1,
            "mobile": null,
            "shipping_contact_person": null,
            "address_country_id": null,
            "shipping_address_unit": null,
            "bank_details": null,
            "address_locality": null,
            "billing_address_region": null,
            "shipping_address_street": null,
            "category_id": null,
            "notes": null,
            "billing_address_town": null
        },
        "lifecycle_status": "Draft",
        "is_contact_notified": false,
        "company": {
            "account": {
                "industries": [],
                "num_purchases": 0,
                "name": "Acme Corp",
                "shipping_address_country": null,
                "billing_address_country": null,
                "num_invoices": 1,
                "address_country": null,
                "id": 1
            },
            "name": "Acme Corp",
            "default_tax": null,
            "id": 1,
            "incoming_sharing_agreements": [],
            "bank_details": []
        },
        "id": 12,
        "currency_code": "GBP"
    }
]

Filtering

The results for a list of invoices can be filtered. See Version 2.5 (v2.5) for more details.

Creating an Invoice

POST /api/v2.5/finance/invoices
statuscode 200:no error
statuscode 400:bad request
Using Python:
import json
import requests

data = {'currency': {'id': u'GBP'}, 'account': {'id': 2L}, 'region': {'id': u'SCO'}, 'company': {'id': 1L}}

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

print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices \ 
    -H "Content-Type: application/json" \
    -d '{
    "currency": {
      "id": "GBP"
    }, 
    "account": {
      "id": 2
    }, 
    "region": {
      "id": "SCO"
    }, 
    "company": {
      "id": 1
    }
  }' \ 
    -X POST \ 
    -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices';

$data = array("currency" => array("id" => "GBP"),
  "account" => array("id" => 2),
  "region" => array("id" => "SCO"),
  "company" => array("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;
Example response:
{
    "account_name": "Tom Inc",
    "number_of_lines": 0,
    "total": 0.0,
    "account_id": 2,
    "other_ref": null,
    "company_id": 1,
    "region": {
        "name": "Scotland",
        "default_tax": null,
        "countries": [],
        "company": {
            "account": {
                "industries": [],
                "num_purchases": 0,
                "name": "Acme Corp",
                "shipping_address_country": null,
                "billing_address_country": null,
                "num_invoices": 0,
                "address_country": null,
                "id": 1
            },
            "name": "Acme Corp",
            "default_tax": null,
            "bank_details": [],
            "timezone": null,
            "incoming_sharing_agreements": [],
            "id": 1
        },
        "locations": [],
        "id": "SCO"
    },
    "date_issued": "2017-10-17T12:38:15Z",
    "lines": [],
    "uri": "/php/viewedit/salesinvoice/13",
    "number": "1",
    "currency": {
        "id": "GBP"
    },
    "account": {
        "is_employee": false,
        "shipping_address_locality": null,
        "address_unit": null,
        "telephone": null,
        "company_number": null,
        "no_publicity": null,
        "shipping_telephone": null,
        "num_invoices": 1,
        "owner": 0,
        "vat_number": null,
        "is_supplier": false,
        "billing_address_country_id": null,
        "address_country": null,
        "id": 2,
        "shipping_address_postcode": null,
        "num_purchases": 0,
        "address_street": null,
        "address_region": null,
        "address_postcode": null,
        "is_venue": false,
        "company_id": null,
        "is_individual": false,
        "source": null,
        "source_details": null,
        "billing_contact_person": null,
        "billing_address_locality": null,
        "is_partner": false,
        "type": null,
        "email": "[email protected]",
        "website": null,
        "custom": {},
        "fax": null,
        "billing_address_unit": null,
        "shipping_address_country": null,
        "billing_telephone": 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,
        "name": "Tom Inc",
        "partner_type": 1,
        "mobile": null,
        "shipping_contact_person": null,
        "address_country_id": null,
        "shipping_address_unit": null,
        "bank_details": null,
        "address_locality": null,
        "billing_address_region": null,
        "shipping_address_street": null,
        "category_id": null,
        "notes": null,
        "billing_address_town": null
    },
    "lifecycle_status": "Draft",
    "is_contact_notified": false,
    "company": {
        "account": {
            "industries": [],
            "num_purchases": 0,
            "name": "Acme Corp",
            "shipping_address_country": null,
            "billing_address_country": null,
            "num_invoices": 0,
            "address_country": null,
            "id": 1
        },
        "name": "Acme Corp",
        "default_tax": null,
        "id": 1,
        "incoming_sharing_agreements": [],
        "bank_details": []
    },
    "id": 13,
    "currency_code": "GBP"
}

Updating an Invoice

PUT /api/v2.5/finance/invoices/:id
statuscode 200:no error
statuscode 400:bad request

Note that finalised invoices do not allow significant updates to the invoice. Submitting an significant update to a finalised invoice will result in a 403 Forbidden error.

Using Python:
import json
import requests

data = {'account': {'id': 3L}}

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

print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/17 \ 
    -H "Content-Type: application/json" \
    -d '{
    "account": {
      "id": 3
    }
  }' \ 
    -X PUT \ 
    -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/17';

$data = array("account" => array("id" => 3));
$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;
Example response:
{
    "account_name": "Tom Inc",
    "number_of_lines": 0,
    "total": 0.0,
    "account_id": 3,
    "other_ref": null,
    "company_id": 1,
    "region": {
        "name": "Scotland",
        "default_tax": null,
        "countries": [],
        "company": {
            "account": {
                "industries": [],
                "num_purchases": 0,
                "name": "Acme Corp",
                "shipping_address_country": null,
                "billing_address_country": null,
                "num_invoices": 0,
                "address_country": null,
                "id": 1
            },
            "name": "Acme Corp",
            "default_tax": null,
            "bank_details": [],
            "timezone": null,
            "incoming_sharing_agreements": [],
            "id": 1
        },
        "locations": [],
        "id": "SCO"
    },
    "date_issued": "2017-10-17T12:38:16Z",
    "lines": [],
    "uri": "/php/viewedit/salesinvoice/14",
    "number": "1",
    "currency": {
        "id": "GBP"
    },
    "account": {
        "is_employee": false,
        "shipping_address_locality": null,
        "address_unit": null,
        "telephone": null,
        "company_number": null,
        "no_publicity": null,
        "shipping_telephone": null,
        "num_invoices": 1,
        "owner": 0,
        "vat_number": null,
        "is_supplier": false,
        "billing_address_country_id": null,
        "address_country": null,
        "id": 3,
        "shipping_address_postcode": null,
        "num_purchases": 0,
        "address_street": null,
        "address_region": null,
        "address_postcode": null,
        "is_venue": false,
        "company_id": null,
        "is_individual": false,
        "source": null,
        "source_details": null,
        "billing_contact_person": null,
        "billing_address_locality": null,
        "is_partner": false,
        "type": null,
        "email": "[email protected]",
        "website": null,
        "custom": {},
        "fax": null,
        "billing_address_unit": null,
        "shipping_address_country": null,
        "billing_telephone": 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,
        "name": "Tom Inc",
        "partner_type": 1,
        "mobile": null,
        "shipping_contact_person": null,
        "address_country_id": null,
        "shipping_address_unit": null,
        "bank_details": null,
        "address_locality": null,
        "billing_address_region": null,
        "shipping_address_street": null,
        "category_id": null,
        "notes": null,
        "billing_address_town": null
    },
    "lifecycle_status": "Draft",
    "is_contact_notified": false,
    "company": {
        "account": {
            "industries": [],
            "num_purchases": 0,
            "name": "Acme Corp",
            "shipping_address_country": null,
            "billing_address_country": null,
            "num_invoices": 0,
            "address_country": null,
            "id": 1
        },
        "name": "Acme Corp",
        "default_tax": null,
        "id": 1,
        "incoming_sharing_agreements": [],
        "bank_details": []
    },
    "id": 14,
    "currency_code": "GBP"
}

Finalising an Invoice

POST /api/v2.5/finance/invoices/finalise/:id
statuscode 200:no error
statuscode 400:bad request
Using Python:
import json
import requests

data = None

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

print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/finalise/3 \ 
    -H "Content-Type: application/json" \
    -d 'null' \ 
    -X POST \ 
    -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/finalise/3';

$data = None;
$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;
Example response:
{
    "lifecycle_status": "Final",
    "document_id": 3
}

Create from Registration

POST /api/v2.5/finance/invoices/create_from_registration/:registration_id
statuscode 200:no error
statuscode 400:bad request

List Payments for an Invoice

GET /api/v2.5/finance/invoices/:id/payments
statuscode 200:no error
Using Python:
import json
import requests

response = requests.get('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/1/payments',
                auth=('<username>', '<password>'))

print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/1/payments \ 
    -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/1/payments';

$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;
Example response:
[
    {
        "currency": "GBP",
        "value": 300.0,
        "id": 2,
        "reference": "1"
    },
    {
        "currency": "GBP",
        "value": 200.0,
        "id": 3,
        "reference": "2"
    }
]

Create a Payment for an Invoice

POST /api/v2.5/finance/invoices/:id/payments
statuscode 200:no error

The value field on the payment is optional. If none is supplied, the value will be automatically set to the outstanding balance of the invoice. If you do supply a value you will be required to provide the currency code and it needs to match the currency on the invoice.

Using Python:
import json
import requests

data = {'payment_type_id': 1L, 'credit_account_code': 2000}

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

print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/2/payments \ 
    -H "Content-Type: application/json" \
    -d '{
    "payment_type_id": 1, 
    "credit_account_code": 2000
  }' \ 
    -X POST \ 
    -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/2/payments';

$data = array("payment_type_id" => 1,
  "credit_account_code" => 2000);
$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;
Example response:
{
    "currency": "GBP",
    "value": 900.0,
    "id": 5,
    "reference": "3"
}

Please note that payments are not able to be created via the API for Companies that are linked to Xero.