API reference › Finance › Invoices

Create a new invoice

POST /v1/finance/invoices

Scope
finance:write
Roles
admin, scheduler

Creates an invoice. Work items (assignments/shifts) already paid for this client are excluded from services_charges. When duplicating (source_document_id), if the source is paid, amounts are zeroed unless full_copy=true (reverse-and-cancel reissue).

Parameters

None of its own.

Every call also sends Authorization and X-Tenant-ID; see Getting started.

Request body required

25 top-level fields; 9 hold nested fields, listed below.

FieldTypeDescription
override_locksboolean or null

Edit a paid document past its locks. Send on the retry after a save asks.

override_reasonobject (2 nested)
override_reason_textstring or null

max length 1000.

override_deliverystring or null

One of: internal_only, send_updated.

confirmationboolean or null

Confirms the resend prompt a save on a sent document raises.

resend_deliverystring or null

One of: send_updated, internal_only, send_now, save_only.

overpayment_confirmationboolean or null

Accept a payment that exceeds the balance due.

idstring or null

Existing invoice to save. Omit to create.

Example INV-EWDM3W.

client_id requiredobject (2 nested)

The client billed. id is a CLT- user id.

source_document_idstring or null

Invoice being duplicated. If it is paid (status Paid or balance due <= 0), amounts are zeroed unless full_copy=true.

Example INV-ABC123.

full_copyboolean or null

Keep full charges when duplicating a paid invoice (reverse-and-cancel reissue).

Example false.

billable_entities requiredarray of object (2 nested)

Work items billed. Work items already paid for this client are left out of the service charges.

billable_entities_billingarray of object or null (19 nested)
line_itemsarray of object or null (6 nested)

type.id is credit, charges or reimbursement.

summaryobject (9 nested)

Tax type and amount become required when the organization charges tax on invoices.

statusobject (2 nested)

Financial status. id required when saving an existing published invoice.

payment_termsobject (2 nested)

Required when published.

issue_datestring (date) or null

Example 2025-01-15.

due_datestring (date) or null

Required when published; on or after issue_date.

Example 2025-01-30.

notesstring or null

Shown to the client.

max length 2000.

internalNotesstring or null

min length 2, max length 2000.

is_publishedboolean or null

Defaults to true. false saves a draft.

Example true.

documentsarray of object or null (10 nested)
customFieldsobject or null

Custom field values keyed by field id.

externalCustomFieldsobject or null

Values for the external custom fields, keyed by field id.

Nested fields

override_reason 2 fields
FieldTypeDescription
override_reason.idinteger or string

Example 1.

override_reason.labelstring or null

Example Example.

client_id 2 fields
FieldTypeDescription
client_id.idinteger or string

Example 1.

client_id.labelstring or null

Example Example.

billable_entities 2 fields
FieldTypeDescription
billable_entities[].type requiredstring

One of: assignment, shift. Example assignment.

billable_entities[].id requiredstring

Example ASG-YZXCIT.

billable_entities_billing 19 fields
FieldTypeDescription
billable_entities_billing[].id requiredstring

A work item listed in billable_entities.

Example ASG-YZXCIT.

billable_entities_billing[].billing_modestring or null

One of: bill, reference. Example bill.

billable_entities_billing[].bill_serviceboolean or null
billable_entities_billing[].bill_expensesboolean or null

Example true.

billable_entities_billing[].bill_admin_feeboolean or null

Example true.

billable_entities_billing[].adminFeeBreakdownobject or null
billable_entities_billing[].adminFeeBreakdown.feeSourcestring or null

One of: calculated, manual.

billable_entities_billing[].adminFeeBreakdown.clientsarray of object or null
billable_entities_billing[].adminFeeBreakdown.clients[].idstring or null

Client or provider user id.

Example CLT-N3B72G.

billable_entities_billing[].adminFeeBreakdown.clients[].feeSourcestring or null

Providers only.

One of: calculated, manual.

billable_entities_billing[].adminFeeBreakdown.clients[].methodstring or null

One of: flat, percentage.

billable_entities_billing[].adminFeeBreakdown.clients[].valuenumber or null

min 0. Example 5.

billable_entities_billing[].adminFeeBreakdown.clients[].sourcestring or null

Clients only: where the fee was resolved from.

One of: client, client_location, organization, organization_location, tenant, default, none, work_item_ssot, invoice_client_scope, stored_estimate.

billable_entities_billing[].adminFeeBreakdown.providersarray of object or null
billable_entities_billing[].adminFeeBreakdown.providers[].idstring or null

Client or provider user id.

Example CLT-N3B72G.

billable_entities_billing[].adminFeeBreakdown.providers[].feeSourcestring or null

Providers only.

One of: calculated, manual.

billable_entities_billing[].adminFeeBreakdown.providers[].methodstring or null

One of: flat, percentage.

billable_entities_billing[].adminFeeBreakdown.providers[].valuenumber or null

min 0. Example 5.

billable_entities_billing[].adminFeeBreakdown.providers[].sourcestring or null

Clients only: where the fee was resolved from.

One of: client, client_location, organization, organization_location, tenant, default, none, work_item_ssot, invoice_client_scope, stored_estimate.

line_items 6 fields
FieldTypeDescription
line_items[].namestring or null

max length 255. Example Parking reimbursement.

line_items[].descriptionstring or null

max length 1000.

line_items[].amount requirednumber

min 0. Example 25.

line_items[].typeobject

The allowed ids depend on the document type.

line_items[].type.idstring

Example charges.

line_items[].type.labelstring or null

Example Additional Charge.

summary 9 fields
FieldTypeDescription
summary.tax_typeobject or null
summary.tax_type.idstring

One of: Fixed, Percentage. Example Percentage.

summary.tax_type.labelstring

Example Percentage.

summary.tax_amountnumber or null

min 0. Example 8.25.

summary.discount_typeobject or null
summary.discount_type.idstring

One of: Fixed, Percentage. Example Fixed.

summary.discount_type.labelstring

Example Fixed.

summary.discount_amountnumber or null

min 0. Example 10.

summary.payments_appliednumber or null

min 0.

status 2 fields
FieldTypeDescription
status.idinteger or string

Example 1.

status.labelstring or null

Example Example.

payment_terms 2 fields
FieldTypeDescription
payment_terms.idinteger or string

Example 1.

payment_terms.labelstring or null

Example Example.

documents 10 fields
FieldTypeDescription
documents[].idinteger or null

Example 12.

documents[].filestring (binary) or null

The uploaded file. Omit when only the categories or tags of an existing document change.

documents[].fileNamestring or null

Example intake-form.pdf.

documents[].categoriesarray of object

Existing categories by id, or new ones by label.

documents[].categories[].idinteger or string

Example 1.

documents[].categories[].labelstring or null

Example Example.

documents[].tagsarray of object

Existing tags by id, or new ones by label.

documents[].tags[].idinteger or string

Example 1.

documents[].tags[].labelstring or null

Example Example.

documents[].isPublicboolean or null

Visible to the client and consumer, not only to staff.

Example false.

Example

JSON
{
  "override_locks": true,
  "override_reason": {
    "id": 1,
    "label": "Example"
  },
  "override_reason_text": "string",
  "override_delivery": "internal_only",
  "confirmation": true,
  "resend_delivery": "send_updated",
  "overpayment_confirmation": true,
  "id": "INV-EWDM3W",
  "client_id": {
    "id": 1,
    "label": "Example"
  },
  "source_document_id": "INV-ABC123",
  "full_copy": false,
  "billable_entities": [
    {
      "type": "assignment",
      "id": "ASG-YZXCIT"
    }
  ],
  "billable_entities_billing": [
    {
      "id": "ASG-YZXCIT",
      "billing_mode": "bill",
      "bill_service": true,
      "bill_expenses": true,
      "bill_admin_fee": true,
      "adminFeeBreakdown": {
        "feeSource": "calculated",
        "clients": [
          {
            "id": "CLT-N3B72G",
            "feeSource": null,
            "method": null,
            "value": 5,
            "source": null
          }
        ],
        "providers": [
          {
            "id": "CLT-N3B72G",
            "feeSource": null,
            "method": null,
            "value": 5,
            "source": null
          }
        ]
      }
    }
  ],
  "line_items": [
    {
      "name": "Parking reimbursement",
      "description": "string",
      "amount": 25,
      "type": {
        "id": "charges",
        "label": "Additional Charge"
      }
    }
  ],
  "summary": {
    "tax_type": {
      "id": "Percentage",
      "label": "Percentage"
    },
    "tax_amount": 8.25,
    "discount_type": {
      "id": "Fixed",
      "label": "Fixed"
    },
    "discount_amount": 10,
    "payments_applied": 0
  },
  "status": {
    "id": 1,
    "label": "Example"
  },
  "payment_terms": {
    "id": 1,
    "label": "Example"
  },
  "issue_date": "2025-01-15",
  "due_date": "2025-01-30",
  "notes": "string",
  "internalNotes": "string",
  "is_published": true,
  "documents": [
    {
      "id": 12,
      "file": "string",
      "fileName": "intake-form.pdf",
      "categories": [
        {
          "id": 1,
          "label": "Example"
        }
      ],
      "tags": [
        {
          "id": 1,
          "label": "Example"
        }
      ],
      "isPublic": false
    }
  ],
  "customFields": {},
  "externalCustomFields": {}
}

Example request

Shell
curl -X POST "https://api.fetchfido.ai/v1/finance/invoices" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"override_locks":true,"override_reason":{"id":1,"label":"Example"},"override_reason_text":"string","override_delivery":"internal_only","confirmation":true,"resend_delivery":"send_updated","overpayment_confirmation":true,"id":"INV-EWDM3W","client_id":{"id":1,"label":"Example"},"source_document_id":"INV-ABC123","full_copy":false,"billable_entities":[{"type":"assignment","id":"ASG-YZXCIT"}],"billable_entities_billing":[{"id":"ASG-YZXCIT","billing_mode":"bill","bill_service":true,"bill_expenses":true,"bill_admin_fee":true,"adminFeeBreakdown":{"feeSource":"calculated","clients":[{"id":"CLT-N3B72G","feeSource":null,"method":null,"value":5,"source":null}],"providers":[{"id":"CLT-N3B72G","feeSource":null,"method":null,"value":5,"source":null}]}}],"line_items":[{"name":"Parking reimbursement","description":"string","amount":25,"type":{"id":"charges","label":"Additional Charge"}}],"summary":{"tax_type":{"id":"Percentage","label":"Percentage"},"tax_amount":8.25,"discount_type":{"id":"Fixed","label":"Fixed"},"discount_amount":10,"payments_applied":0},"status":{"id":1,"label":"Example"},"payment_terms":{"id":1,"label":"Example"},"issue_date":"2025-01-15","due_date":"2025-01-30","notes":"string","internalNotes":"string","is_published":true,"documents":[{"id":12,"file":"string","fileName":"intake-form.pdf","categories":[{"id":1,"label":"Example"}],"tags":[{"id":1,"label":"Example"}],"isPublic":false}],"customFields":{},"externalCustomFields":{}}'

Try it

Responses

200 Existing invoice saved (id was sent)

Existing invoice saved (id was sent).

JSON
{
  "success": true,
  "message": "Invoice updated successfully.",
  "data": {
    "id": "INV-EWDM3W"
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Invoice updated successfully..

dataobject
data.idstring

Example INV-EWDM3W.

201 Invoice created successfully

Invoice created successfully

JSON
{
  "success": true,
  "message": "Invoice created successfully.",
  "data": {
    "id": "INV-EWDM3W"
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Invoice created successfully..

dataobject
data.idstring

Example INV-EWDM3W.

401 Not signed in

Missing, invalid or expired API key.

JSON
{
  "success": false,
  "message": "Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for.",
  "errors": null,
  "code": "API_KEY_MISSING"
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for..

errorsany or null

Null on this status.

codestring

Machine-readable reason, for branching on in client code.

One of: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED. Example API_KEY_MISSING.

403 Not allowed

The caller may not save this invoice.

JSON
{
  "success": false,
  "message": "You don't have permission to access this endpoint. This API key is missing the 'finance:write' scope.",
  "errors": null,
  "code": ""
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example You don't have permission to access this endpoint. This API key is missing the 'finance:write' scope..

errorsany or null

Null on this status.

codestring

Always empty on this status.

Example .

422 Validation failed

Validation error. A status change that needs confirmation also comes back as 422, with requires_confirmation=true and data {current_status, target_status, payment_details}; resend with the confirmation fields to proceed.

JSON
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "client_id": [
      "Client is required."
    ]
  }
}
Response fields (3)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Validation failed.

errorsobject
429 Too many requests

Rate limit exceeded. See Retry-After.

JSON
{
  "success": false,
  "message": "You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds.",
  "errors": null,
  "code": "RATE_LIMITED"
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds..

errorsany or null

Null on this status.

codestring

Machine-readable reason, for branching on in client code.

One of: RATE_LIMITED. Example RATE_LIMITED.

500 Server error

Unexpected error

JSON
{
  "success": false,
  "errors": "Invoice creation failed",
  "message": "An unexpected error occurred ? please try again."
}
Response fields (3)
FieldTypeDescription
successboolean

Example false.

errorsstring or null

Null in production. The exception message only when the application runs with debug on.

Example Invoice creation failed.

messagestring

Example An unexpected error occurred ? please try again..

503 The invoice was saved but could not be moved to Sent

The invoice was saved but could not be moved to Sent.

JSON
{
  "success": false,
  "message": "The document could not be set to Sent. Please try again.",
  "errors": null,
  "code": ""
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example The document could not be set to Sent. Please try again..

errorsstring or null

Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.

codestring

Always empty: the server-error response carries no error code.

Example .