Create new invoice

Creates an invoice. You can attach project information, optionally.

Endpoint

POST /integration/invoice

HTTP Request

POST /integration/invoice

Invoice Object

{
    "id": "2eb1acd98a86",
    "invoiceNumber": "INV/00003/2023",
    "customerId": "7ba4877cbf52",
    "invoiceDate": "2023-01-04",
    "dueDate": "2023-01-12",
    "expirationDate": "2023-01-12",
    "subTotal": 1000,
    "totalAmount": 1100,
    "taxAmount": 100,
    "amountDue": 1100,
    "lines": [
        {
            "description": "Item 1",
            "unitAmount": 500,
            "quantity": 2,
            "subTotal": 1000,
            "taxAmount": 100,
            "totalAmount": 1100
        }
    ],
    "quoteRefNumber": "QUOT/0567/2022",
    "quoteId": "cbabdcfecfeb",
    "status": "Placed",
    "sourceModifiedDate": "2023-01-04T09:47:57.477Z",
    "projectDetails": {
      "projectId": "generic_project_id_1",
      "name": "A new huge building",
      "address": "285 Fulton St, New York, NY 10007, United States",
      "contractValue": 50000,
      "sourceModifiedDate": "2023-11-14T15:18:19.576Z",
      "startDate": "2024-05-20T00:00:00.000Z",
      "endDate": "2025-12-31T00:00:00.000Z",
      "jobId": "generic_job_id_1",
      "jobAddress": {
        "address": "285 Fulton St",
        "unitNo": "",
        "state": "NY",
        "zipCode": "10007",
        "city": "New York",
        "lotNumber": "",
        "blockNumber": ""
      },
      "role": "PrimeOrGeneralContractor",
      "primeContractorDetails": {
        "businessName": "Builders",
        "firstName": "John",
        "lastName": "Doe",
        "businessPhoneNumber": "202-555-0583",
        "businessEmail": "[email protected]",
        "businessAddress": "Washington str. 123",
        "state": "California",
        "city": "San Francisco",
        "zipCode": "31702"
      },
      "type": "public",
      "privateProjectDetails": {
        "privateProjectType": "Сommercial",
        "builtFor": {
          "type": "PropertyOwnerNewBuilding",
          "notes": "Test note"
        }
      },
      "publicProjectDetails": {
        "description": "Public description",
        "hasBond": true,
        "isBondRequired": true
      },
      "federalProjectDetails": {
        "hasBond": true
      },
      "individualOwners": [
        {
          "firstName": "John",
          "lastName": "Doe",
          "phone": "202-555-0583",
          "homeAddress": "Washington str. 123",
          "state": "California",
          "city": "San Francisco",
          "zipCode": "31702"
        }
      ],
      "businessOwners": [
        {
          "businessName": "Builders",
          "firstName": "Mary",
          "lastName": "Matheson",
          "businessPhoneNumber": "202-555-0583",
          "businessAddress": "Washington str. 123",
          "state": "California",
          "city": "San Francisco",
          "zipCode": "31702"
        }
      ]
    },
    "salesInfo": [
      {
        "firstName": "string",
        "lastName": "string",
        "emailAddress": "string",
        "cellPhoneNumber": "string"
      }
    ],
    "shippingAddress": {
      "attention": "John Doe",
      "address": "285 Fulton St, New York, NY 10007, US", // fill address or addressModel
      "addressModel": {
        "address": "285 Fulton St",
        "city": "New York",
        "state": "New York",
        "zipCode": "10007",
        "country": "US" // optional
      }
    }
}

Successful response

HTTP 201 Created

{
  "blueTapeId": "63168de0cbee",
  "details": {
    "totalAmount": 1100
  }
}

Erroneous response

HTTP 409 Conflict

{
  "code": "409",
  "reason": "Invoice already exists, invoice number: {invoiceNumber}"
}

Responses

Code	Description
201	Created, successful operation
400	Invalid request
401	Unauthorized
404	Not found
500	Unexpected error

Request parameters

Invoice Object

Name	Description	Required	Type
id	Identifier of the invoice.	true	string
invoiceNumber	Friendly reference for the invoice. If available, this appears in the file name of invoice attachments.	true	string
customerId	Reference to the customer the invoice has been issued to.	true	string
invoiceDate	Date of the invoice as recorded in the accounting service provider.	true	string (date)
dueDate	Date the invoice is due to be paid by.	true	string (date)
expirationDate	Expiration date of the invoice.	true	string (date)
subTotal	Value of the invoice, including discounts and excluding tax.	true	decimal
totalAmount	Amount of the invoice, inclusive of tax.	true	decimal
taxAmount	Any tax applied to the invoice amount.	true	decimal
amountDue	Amount outstanding on the invoice.	true	decimal
lines	An array of invoice lines.	false	array
quoteRefNumber	Reference to the quote.	false	string
quoteId	Reference to the quote.	false	string
status	Status of the invoice.	true	string
sourceModifiedDate	Date the record was last changed in the accounting service provider.	true	string (date)
projectDetails	Details of the attached project.	false	object
salesInfo	Members of sales	false	array

Invoice Line Object

Name	Description	Required	Type
description	Friendly name of the goods or services received.	false	string
unitAmount	Price of each unit of goods or services.	true	decimal
quantity	Number of units of goods or services.	true	integer
subTotal	Amount of the line, inclusive of discounts but exclusive of tax.	true	decimal
taxAmount	Amount of tax for the line.	true	decimal
totalAmount	Total amount of the line, inclusive of discounts and tax.	true	decimal

Project Object

Name	Description	Required	Type
projectId	Identifier for the project.	true	string
name	Project name.	false	string
address	Project address.	false	string
contractValue	The total amount of contracted amount for the project.	false	decimal
sourceModifiedDate	Date the record was last changed in the accounting service provider	false	datetime
startDate	First day on the job.	false	date
endDate	Expected last day on the job.	false	date
jobId	The job id.	false	string
jobAddress	Project address in details.	false	object
address	Street address.	false	string
unitNo	Unit number (if applicable).	false	string
state	State.	false	string
zipCode	ZIP Code.	false	string
city	City.	false	string
lotNumber	Lot number.	false	string
blockNumber	Block number.	false	string
role	Role on this project.	false	string(enum)
primeContractorDetails	Filled if role is one of subcontractor, subcontractor for another subcontractor, material supplier, property developer.	false	object
businessName	The prime contractor's business name.	false	string
firstName	The prime contractor's first name.	false	string
lastName	The prime contractor's last name.	false	string
businessPhoneNumber	The prime contractor's business phone number.	false	string
businessEmail	The prime contractor's business email address.	false	string
businessAddress	The prime contractor's business address.	false	string
state	The prime contractor's business address state.	false	string
city	The prime contractor's business address city.	false	string
zipCode	The prime contractor's business address zipcode.	false	string
type	Project's type	false	string(enum)
privateProjectDetails	Filled if project's type is private.	false	object
privateProjectType	Subtype of private project.	false	string(enum)
builtFor	Built for which purpose.	false	object
type	Type of purpose	false	string(enum)
notes	Filled if type other.	false	string
publicProjectDetails	Filled if project's type is public.	false	object
description	Description of the public project.	false	string
hasBond	Determines, is there a bond for this project.	false	bool
isBondRequired	Is the bond required to carry by the sub-contractor.	false	bool
federalProjectDetails	Filled if project's type is federal.	false	object
hasBond	Determines, is there a bond for this project.	false	bool
propertyIndividualOwners	The property individual owner's details.	false	array
firstName	The property owners's first name.	false	string
lastName	The property owners's last name.	false	string
phoneNumber	The property owners's phone number.	false	string
homeAddress	The property owners's home address.	false	string
state	The property owners's home address state.	false	string
city	The property owners's home address city.	false	string
zipCode	The property owners's home address zipcode.	false	string
propertyBusinessOwners	The property business owner's details.	false	array
businessName	The property owners's business name.	false	string
firstName	The property owners's first name.	false	string
lastName	The property owners's last name.	false	string
businessPhoneNumber	The property owners's business phone number.	false	string
businessEmail	The property owners's business email address.	false	string
businessAddress	The property owners's business address.	false	string
state	The property owners's business address state.	false	string
city	The property owners's business address city.	false	string
zipCode	The property owners's business address zipcode.	false	string

SalesInfo object

Name	Description	Required	Type
firstName	First name of sales member	false	string
lastName	Last name of sales member	false	string
emailAddress	Email address of sales member	false	string
cellPhoneNumber	Mobile phone number of sales member	false	string

ShippingAddress object

Address or AddressModel to be filled.

Name	Description	Required	Type
attention	Attention name	false	string
address	Full shipping address	false	string
addressModel	Shipping address model	false	string

AddressModel object

Name	Description	Required	Type
address	Address	false	string
city	City	false	string
state	State	false	string
zipCode	Zip Code	false	string
country	Country	false	string

Enums

Status

active
inactive

Role

PrimeOrGeneralContractor
SubContractor
SubContractorForAnotherSubContractor
MaterialSupplier
PropertyDeveloper
Owner
Tenant

Type

Private
Public
Federal

PrivateProjectType

Сommercial
Residential

BuiltFor.Type

Spec
PropertyOwnerNewBuilding
PropertyOwnerRenovation
Other

Examples

curl https://api.bluetape.com/genericBthubService/integration/invoice \
  -X POST \
  -H "X-BlueTape-Key: <your-key>" \
  -H "X-Integration-AccountId: <your-account-id>" \
  -H "Content-Type: application/json" \
  -d "@request.json"

import fetch from 'node-fetch';

const invoice = { ... };
const url = 'https://api.bluetape.com/genericBthubService/integration/invoice';
const options = {
  method: 'POST', 
  headers: {
    'X-BlueTape-Key': '<your-key>',
    'X-Integration-AccountId': '<your-account-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(invoice)
};

fetch(url, options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

using Flurl.Http;

var invoice = new Invoice() {
  ...
};

var result = await "https://api.bluetape.com/genericBthubService/integration/invoice"
  .WithHeader("X-BlueTape-Key", "<your-key>")
  .WithHeader("X-Integration-AccountId", "<your-account-id>")
  .WithHeader("Content-Type", "application/json")
  .PostJsonAsync(invoice)
  .ReceiveJson<BlueTapeIntegrationResult>();

import requests

url = "https://api.bluetape.com/genericBthubService/integration/invoice"

headers = {
    "X-BlueTape-Key": "<your-key>",
    "X-Integration-AccountId": "<your-account-id>",
    "Content-Type": "application/json"
}

data = <your-invoice-data>

response = requests.post(url, headers=headers, data=data)

print(response.text)

Endpoint​

HTTP Request​

Successful response​

Erroneous response​

Responses​

Request parameters​

Enums​

Examples​