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:

  1. 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).

  2. 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

  3. 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:
Status Codes:
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

  • jobs.lineItems[ ].itemType (string) – 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