Invoices¶

The API allows one or more invoices to created at a time for one or more jobs. A single invoice may cover multiple jobs. Creating an invoicing happens through the following steps:

First the job identifier or job identifiers of the jobs to be invoiced need to be obtained. The API allows access to a listing of uninvoiced jobs in the system (see list-uninvoiced-jobs).
The job identifier(s) can then be used to obtain invoice templates from the server, one for every invoice. An invoice template contains all the information an invoice contains, except for an invoice number and UUID
An actual invoice is created by sending the – possibly amended – invoice templates to the server. Once validated, the server assigns an invoice number and UUID and makes the invoice available for querying.

Once an invoice is created, it may be updated or deleted. No job can be invoiced twice; attempt to do so will be flagged as an error.

Any invoice generated through the web interface can be queried and updated through the API, and vice versa.

An invoice is identified by UUID (for ex. cc848a85d0de4f4885b376f6b7268611) or invoice number (for ex. 00021657). Wherever invoice_ref is mentioned below, it can be either of these.

List Invoices¶

GET /invoice/¶

List of all invoices, optionally filtered by given criteria.

Sample request:

GET /invoice/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json, text/javascript

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "count": 66,
  "items": [
    {
      "createdOn": "2014-08-21T12:33:19+00:00",
      "customer":
        {
          "name": "twiba",
          "uuid": "a2e6e38e55e143d0b8c805dfd64deded"
        },
      "invoiceNumber": "00000012",
      "jobUuids": [],
      "location":
        {
          "uuid": "09d77ff224d240218f8ab2473fff104a"
        },
      "totalAmount": 165.0,
      "uuid": "032c8843e1ae479b995733d5d08519f4",
      "link":
        {
          "rel": "detail",
          "link": "https://api.fieldaware.net/invoice/032c8843e1ae479b995733d5d08519f4"
        }
    },
    {
      "createdOn": "2014-08-29T12:33:19+00:00",
      "customer":
        {
          "name": "Cloudnico",
          "uuid": "27d4b97c4ff04e82868f737f37b8221c"
        },
      "invoiceNumber": "00000022",
      "jobUuids": [],
      "location":
        {
          "uuid": "818ab504b7c24262bee851bffd9e2c16"
        },
      "totalAmount": 85.0,
      "uuid": "099be0f45d094d98b80e8b1a2ab41483",
      "link":
        {
          "rel": "detail",
          "link": "https://api.fieldaware.net/invoice/099be0f45d094d98b80e8b1a2ab41483"
        }
    },
  ],
  "page": 0,
  "pageSize": 3,
  "sortedBy": []
}

Request Headers:

Authorization – Authorization token

Status Codes:

200 OK – no error

Query Parameters:

sortedBy – Available sorting criteria: invoiceNumber, createdOn, location, totalAmount
invoiceNumber – A filtering value for invoiceNumber
createdOn – A filtering value for createdOn
location – A filtering value for location
start – A filtering value on createdOn, defining the start of a date range.
end – A filtering value on createdOn, defining the end of a date range.

Response JSON Object:

count (int) – Total number of invoices
items (array) – Invoices
page (int) – Page number
pageSize (int) – Page size
sortedBy (array) – Params for sorting

Get Invoice Template¶

GET /invoice/template/(jobs)¶

Fetch a template for a new invoice. jobs a comma-separated list of job ID(s) or/and UUID(s) to use for filling the new invoice template.

Sample request:

GET /invoice/template/J54 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json, text/javascript

Query Parameters:

jobs (string) – Single job with JobId = J54

Sample request:

GET /invoice/template/c4994b46a8c7401f9cca79f447e84a6e HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json, text/javascript

Query Parameters:

jobs (string) – Single job with Job UUID = c4994b46a8c7401f9cca79f447e84a6e

Sample request:

GET /invoice/template/J54,J55 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json, text/javascript

Query Parameters:

jobs (string) – Multiple jobs with id = J54 and id = J55

Sample request:

GET /invoice/template/c4994b46a8c7401f9cca79f447e84a6e,b630ca4294744cfda6cb4009771fd84e HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json, text/javascript

Query Parameters:

jobs (string) – Multiple jobs with UUIDs = c4994b46a8c7401f9cca79f447e84a6e and b630ca4294744cfda6cb4009771fd84e

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "comment": "",
  "contact": {
    "emailAddress": "sbeatty@hotmail.com",
    "name": "Shawna",
    "surname": "Beatty",
    "telno": null,
    "uuid": "082a0b1f46dc4ac39f33f703910a6b2a"
  },
  "createdOn": "2014-09-08T13:46:32.330493+00:00",
  "currency": "USD",
  "customFields": {},
  "customer": {
    "name": "Blingnet",
    "uuid": "bae4089185c0485d9a2af0ad5d8a199f"
  },
  "internalComment": "\nJob J86: 78h,32min\n",
  "jobs": [
    {
      "asset": {
        "name": "Bauch Pneumatic saw",
        "serialNumber": "466116U",
        "uuid": "76b0813f5ced407c93f374e0fb5088bc"
      },
      "completedOn": "2014-09-08T13:43:32+00:00",
      "customFields": {
        "305cd64d606f4b67927e61badcfe1007": 10.3,
        "e18e4d73d7ce40cca5d93a44f1a01e54": "3eec017fa7604656bbf2fe2850a37c23"
      },
      "jobId": "J86",
      "jobLead": "Damon Murray",
      "lineItems": [
        {
          "cost": 117.83,
          "description": "",
          "note": null,
          "glAccount": null,
          "name": "Install Jenkins conventional callpoint",
          "price": 133.83,
          "quantity": 1,
          "taxes": [],
          "itemType: "Task",
          "entity": {"uuid": "82a4ec838f884c4bbfd90b7042bdafb7"}
        },
        {
          "cost": 57.11,
          "description": "",
          "note": null,
          "glAccount": null,
          "name": "\tHowell Loop sign",
          "price": 93.11,
          "quantity": 2,
          "taxes": [],
          "itemType: "Task",
          "entity": {"uuid": "55f200ae2b8049189b68008666bd4610"}
        },
        {
          "cost": None,
          "description": "A lot of work",
          "note": None,
          "glAccount": null,
          "name": "John's Labor",
          "price": 100.0,
          "quantity": 1.09
          "taxes": [{"rate": 8.25, "agency": "", "name": "Dallas", "glAccount": ""}],
          "itemType": "Labor",
          "entity": None,
        }
      ],
      "location": {
        "country": "United States",
        "locality": "South Burdette",
        "name": "Blingnet Offices",
        "postcode": null,
        "region": "OK",
        "streetName": "6328 Reanna Station Suite 074",
        "uuid": "80b67eca44c941fe9fbec13f2a8d499e"
      },
      "uuid": "3eec017fa7604656bbf2fe2850a37c23"
    }
  ],
  "location": null,
  "totals": {
    "netAmount": 3469.98,
    "netLaborAmount": 0.0,
    "totalAmount": 3469.98,
    "totalTax": 0.0
  }
}

Response JSON Object:

coment (string) – Comment
contact (obj) – Contact
createdOn (string) – Date in ISO format
currency (string) – Currency of the invoice
customFields (obj) – Custom fields
customer (obj) – Customer
internalComment (string) – Internal comment of the invoice
jobs (array) – A list of json objects - invoiced jobs
location (string) – Location
totals (obj) – A dict with calculated totals

Get Invoice Templates¶

GET /invoice/template/?(jobs)¶

Fetch a template for multiple invoices in a single request.

A comma-separated list of job ``ID``(s) or/and ``UUID``(s) to use for filling the new invoice template. The parameter can be specified multiple times to request multiple invoice templates.

Examples:

# single invoice, single job by job id
/invoice/template?jobs=J54
# single invoice, single job by UUID
/invoice/template?jobs=c4994b46a8c7401f9cca79f447e84a6e
# single invoice, multiple jobs by job id
/invoice/template?jobs=J54,J55
# single invoice,  multiple jobs by UUID
/invoice/template?jobs=c4994b46a8c7401f9cca79f447e84a6e,b630ca4294744cfda6cb4009771fd84e
# multiple invoices with 1 and 3 jobs respectively
/invoice/template?jobs=J54&jobs=J55,J56,J57

Sample request:

GET /invoice/template/?jobs=J54 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json, text/javascript

Query Parameters:

jobId (string) – Example JobId = J54

Sample request:

GET /invoice/template/?jobs=c4994b46a8c7401f9cca79f447e84a6e HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json, text/javascript

Query Parameters:

UUID (string) – Example job UUID = c4994b46a8c7401f9cca79f447e84a6e

Sample request:

GET /invoice/template/?jobs=J54,J55 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json, text/javascript

Query Parameters:

jobs (string) – Jobs with ids J54 and J55

Sample request:

GET /invoice/template/?jobs=c4994b46a8c7401f9cca79f447e84a6e,b630ca4294744cfda6cb4009771fd84e HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json, text/javascript

Query Parameters:

jobs (string) – Jobs with UUIDs: c4994b46a8c7401f9cca79f447e84a6e and b630ca4294744cfda6cb4009771fd84e

Sample request:

GET /invoice/template/?jobs=J51&jobs=J55,J56,J57 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json, text/javascript

Query Parameters:

jobs (string) – Jobs with IDs: J51, J55, J56, J57

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "templates": [
    {
      "customer": {
        "name": "iqa",
        "uuid": "d3c45b8f06064c199c6ab43c622aca9a"
      },
      "location": {
        "uuid": "6d6b036dbcdc4e8aafb469a57ec843d6"
      }
      "comment": "",
      "contact": {
        "emailAddress": "xhills@yahoo.com",
        "telno": null,
        "surname": "Hills",
        "uuid": "68e4000d7a434723ac482293d2e205c1",
        "name": "Xavier"
      },
      "jobs": [
        {
          "uuid": "36976156807c426e9bf5cd25ad953e0c",
          "jobId": "J82",
          "location": {
            "uuid": "6d6b036dbcdc4e8aafb469a57ec843d6",
            "locality": "South Gloria",
            "country": "United States",
            "region": "AK",
            "postcode": null,
            "streetName": "8274 Shields Trail Ave.",
            "name": "iqa Headquarters"
          },
          "jobLead": "Marco Cummerata",
          "customFields": {
            "Job Random String": "36976156807c426e9bf5cd25ad953e0c",
            "Discount": 92.8
          },
          "lineItems":
            [
              {
                "cost": 366.78000,
                "name": "Replace Rosenbaum manual lights",
                "glAccount": null,
                "price": 388.78680,
                "quantity": 1,
                "taxes": [],
                "description": "",
                "note": "sockets show heavy wear; may need to be replaced soon",
                "itemType: "Task",
                "entity": {"uuid": "82a4ec838f884c4bbfd90b7042bdafb7"}
              },
              {
                "cost": 857.06000,
                "name": "Remove Mann manual filter",
                "glAccount": null,
                "price": 896.06000,
                "quantity": 1,
                "taxes": [],
                "description": "",
                "note": null,
                "itemType: "Task",
                "entity": {"uuid": "55f200ae2b8049189b68008666bd4610"}
              }
              {
                "cost": None,
                "name": "John's Labor",
                "glAccount": null,
                "price": 100.0,
                "quantity": 1.09
                "taxes": [{"rate": 8.25, "agency": "", "name": "Dallas", "glAccount": ""}],
                "description": "A lot of work",
                "note": None,
                "itemType": "Labor",
                "entity": None,
              }
            ],
          "completedDatetime": null,
          "asset":
            {
              "serialNumber": "102931G",
              "uuid": "6e342da5a09d4fdf8db47268e0ac8a2d",
              "name": "McKenzie Hyper core"
            }
        }
      ],
      "currency": "USD",
      "internalComment": "\nJob J82: 0h,0min\n",
      "createdOn": "2013-08-29T19:06:47.373405+00:00",
      "totals":
        {
          "totalTax": 0.00,
          "netAmount": 2473.07,
          "totalAmount": 2473.07,
          "netLaborAmount": 0.00
        }
    },
    {
      "customer":
        {
          "name": "Plurchi",
          "uuid": "4ba8f84142a242d1ad984b818e1763b1"
        },
      "comment": "",
      "contact":
        {
          "emailAddress": "rwelch@hotmail.com",
          "telno": null,
          "surname": "Welch",
          "uuid": "cb3740e0cdf54099afd1e308364b157a",
          "name": "Rosamond"
        },
      "jobs":
        [
          {
            "uuid": "c6249da48e604394a95f6f669cc8d883",
            "jobId": "J71",
            "location":
              {
                "uuid": "f35df45db4864df1bfbe888a58994137",
                "locality": "Port Arnoldoton",
                "country": "United States",
                "region": "LA",
                "postcode": null,
                "streetName": "326 Jacey Cove ",
                "name": "Plurchi Headquarters"
              },
            "jobLead": "Logan Block",
            "customFields":
              {
                "Job Random String": "c6249da48e604394a95f6f669cc8d883",
                "Discount": 19.200000000000000000000000000000
              },
            "lineItems":
              [
                {
                  "cost": 690.72000,
                  "name": "Remove Hegmann manual callpoint",
                  "glAccount": null,
                  "price": 704.53440,
                  "quantity": 1,
                  "taxes": [],
                  "description": "",
                  "note": null,
                  "itemType: "Task",
                  "entity": {"uuid": "55f200ae2b8049189b68008666bd4610"}
                },
                {
                  "cost": 349.94000,
                  "name": "Remove Hettinger heat filter",
                  "glAccount": null,
                  "price": 395.43220,
                  "quantity": 1,
                  "taxes": [],
                  "description": "",
                  "note": null,
                  "itemType: "Task",
                  "entity": {"uuid": "82a4ec838f884c4bbfd90b7042bdafb7"}
                }
              ],
            "completedDatetime": null,
            "asset":
              {
                "serialNumber": "107470J",
                "uuid": "4005103c2f6045f58f52ea78ee00d6d2",
                "name": "Cruickshank Pneumatic detector"
              }
          }
        ],
      "currency": "USD",
      "internalComment": "\nJob J71: 0h,0min\n",
      "createdOn": "2013-08-29T19:06:47.427706+00:00",
      "totals":
        {
          "totalTax": 0.00,
          "netAmount": 1572.03,
          "totalAmount": 1572.03,
          "netLaborAmount": 0.00
        }
    }
  ],
  "errors":
    [
      {
        "message": "Job(s) are not found: j77",
        "name": "NotFoundError"
      }
    ]
}

Response JSON Object:

templates (array) – A list of templates
errors (array) – A list of errors

Get Invoice¶

GET /invoice/(invoice_ref)¶

Retrieve a given invoice.

Sample request:

GET /invoice/4005103c2f6045f58f52ea78ee00d6xx HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json, text/javascript

Query Parameters:

invoice_ref (string) – Invoice UUID

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "comment": "An Invoice",
  "contact": null,
  "createdOn": "2014-09-06T07:33:19+00:00",
  "currency": "USD",
  "customFields": {},
  "customer": {
    "name": "Cloudnico",
    "uuid": "27d4b97c4ff04e82868f737f37b8221c"
  },
"internalComment": null,
"invoiceNumber": "00000013",
"jobs": [
  {
    "lineItems": [
      {
        "cost": 18.0,
        "description": null,
        "note": null,
        "glAccount": null,
        "name": "Replace Sounder [Vantage Sounder]",
        "price": null,
        "quantity": 1,
        "taxes": [],
        "itemType: "Task",
        "entity": {"uuid": "82a4ec838f884c4bbfd90b7042bdafb7"}
      },
      {
        "cost": 24.0,
        "description": null,
        "note": null,
        "glAccount": null,
        "name": "Replace Sounder [Spatial Sounder]",
        "price": null,
        "quantity": 1,
        "taxes": [],
        "itemType: "Task",
        "entity": {"uuid": "55f200ae2b8049189b68008666bd4610"}
      }
    ]
  }
],
"location": {
  "uuid": "82c511452acd4dc7b7027fc7e3c9da3a"
},
"totals": {
  "netAmount": 42.0,
  "netLaborAmount": 0.0,
  "totalAmount": 42.0,
  "totalTax": 0.0
},
  "uuid": "4f371e6397564dcfb41284f23124bf94"
}

Response JSON Object:

comment (string) – Comment
contact (obj) – Contact details (JSON Obj) or null if no contact provided
createdOn (string) – Date the invoice was created (in ISO format)
currency (string) – Currency
customFields (obj) – Custom fields (JSON Obj)
customer (obj) – Customer (JSON Obj)
internalComment (string) – Comment, null or string
invoiceNumber (string) – Invoice number
jobs (array) – A list of Jobs (JSON Obj)
location (obj) – Location UUID
totals (obj) – Calculated totals
uuid (string) – UUID of the invoice

Create Invoice¶

POST /invoice/¶

Create a new invoice.

Sample request:

POST /invoice/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

{
  "createdOn": "datetime obj",
  "comment": "Invoice description",
  "internalComment": "invoice description",
  "customer": {
    "uuid": "uuid of the customer",
  },
  "contact": {
    "uuid": "uuid of the contact",
  },
  "jobs": [
    {
      "uuid": "UUID of the job (string, required)",
      "lineItems": [
        {
          "name": "Name of the invoiced task, product or person (string, required)",
          "description": "Optional description for the invoiced task or product (string)",
          "note": "Optional note (string)",
          "price": "Unit price (number, required)",
          "cost": "Unit cost (number, required)",
          "quantity": "Item quantity, 1.0 if it is a Task, duration in hours if it is labor (number, required)",
          "itemType": "Product",
          "glAccount": "General Ledger account (string)",
          "taxes": [
            {
              "name": "Tax name (string, required)",
              "rate": "Tax rate (number, required)",
            }
          ]
        }
      ]
    }
  ],
  "totals": {
    "netAmount": 0.0,
    "netLaborAmount": 0.0,
    "totalTax": 00.0,
    "totalAmount": 0.0,
  }
}

Request JSON Object:

createdOn (datetime) – When is the invoice created, defaults to now
comment (string) – Invoice description, intended for the contact
customer (obj) – Customer (JSON Obj) is identified by “uuid” (required)
customer.uuid (string) – UUID of the customer
contact (obj) – Contact (JSON Obj) is identified by “uuid”
contact.uuid (string) – UUID of the contact (required if you want to associate a contact with the invoice)
jobs (array) – A list of JSON Obj, One or more invoice groups, one group per invoiced job
jobs.uuid (string) – UUID of the job (required)
jobs.lineItems (array) – One or more line items for the invoiced job
].itemType (string jobs.lineItems[) – One of ‘Labor’, ‘Task’, ‘Product’, ‘Custom’
taxes (array) – Array of up to two taxes (JSON Objects) that apply to this line item
totals (obj) – Several subtotals of the invoice
totals.netAmount (number) – Net price of the invoice (required)
totals.netLabourAmount (number) – Net price of labor of the invoice (required)
totals.totalTax (number) – Total tax of the invoice (required)
totals.totalAmount (number) – Total price of the invoice (required)

Update Invoice¶

PUT /invoice/(invoice_ref)¶

Update a given invoice.

Sample Request:

PUT /invoice/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json

Same as Create Invoice, with all properties being optional.

Sample Response:

HTTP/1.1 204 No Content

Delete Invoice¶

DELETE /invoice/(invoice_ref)¶

Delete a given invoice.

Sample Request:

DELETE /invoice/4005103c2f6045f58f52ea78ee00d6xx HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json

Sample Response:

HTTP/1.1 204 No Content