Quick Start - AR - Dolfin AI

This guide walks through the end-to-end flow of sending an invoice via the Dolfin API. You’ll create a customer, create a product, create an invoice, and send it.

Prerequisites

A Dolfin API key
An organisation already provisioned (see Client Integration)
A valid session token or API key for authentication

All requests below require the x-dolfin-api-key and x-dolfin-organisation-id headers. See Authentication for details.

Overview

Create a customer

Add the customer who will receive the invoice.

Create a product

Define the product or service you’re billing for.

Create an invoice

Build a draft invoice with line items referencing the customer and product.

Send the invoice

Mark the invoice as sent and deliver it to the customer.

Step 1: Create a Customer

curl -X POST https://api.dolfinai.co/v1/customers \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Riverside Construction Ltd",
    "email": "[email protected]",
    "addressLine1": "45 Thames Street",
    "city": "London",
    "postalCode": "SE1 2AQ",
    "country": "GB"
  }'

const customer = await fetch('https://api.dolfinai.co/v1/customers', {
  method: 'POST',
  headers: {
    'x-dolfin-api-key': 'dol_live_abc123',
    'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Riverside Construction Ltd',
    email: '[email protected]',
    addressLine1: '45 Thames Street',
    city: 'London',
    postalCode: 'SE1 2AQ',
    country: 'GB',
  }),
}).then(r => r.json());

Response:

{
  "id": "c3456789-abcd-ef01-2345-6789abcdef01",
  "organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
  "name": "Riverside Construction Ltd",
  "email": "[email protected]",
  "addressLine1": "45 Thames Street",
  "city": "London",
  "postalCode": "SE1 2AQ",
  "country": "GB",
  "createdAt": "2025-01-20T09:00:00Z",
  "updatedAt": "2025-01-20T09:00:00Z"
}

Save the customer id - you’ll need it when creating the invoice.

Step 2: Create a Product

curl -X POST https://api.dolfinai.co/v1/products \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Emergency Boiler Repair",
    "description": "Callout and repair for domestic boiler systems",
    "unitPrice": 150.00,
    "currency": "GBP",
    "type": "Service"
  }'

const product = await fetch('https://api.dolfinai.co/v1/products', {
  method: 'POST',
  headers: {
    'x-dolfin-api-key': 'dol_live_abc123',
    'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Emergency Boiler Repair',
    description: 'Callout and repair for domestic boiler systems',
    unitPrice: 150.00,
    currency: 'GBP',
    type: 'Service',
  }),
}).then(r => r.json());

Response:

{
  "id": "d4567890-abcd-ef01-2345-6789abcdef01",
  "organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
  "name": "Emergency Boiler Repair",
  "description": "Callout and repair for domestic boiler systems",
  "unitPrice": 150.00,
  "currency": "GBP",
  "type": "Service",
  "createdAt": "2025-01-20T09:01:00Z",
  "updatedAt": "2025-01-20T09:01:00Z"
}

Save the product id - you’ll reference it in the invoice line items. The type field accepts Product or Service.

Step 3: Create an Invoice

Create a draft invoice that ties together the customer and product. The lineItems array references the product by its id.

curl -X POST https://api.dolfinai.co/v1/invoices \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "c3456789-abcd-ef01-2345-6789abcdef01",
    "currency": "GBP",
    "dueDate": "2025-02-20T00:00:00Z",
    "memo": "Boiler repair at 12 Oak Lane - January 2025",
    "lineItems": [
      {
        "productId": "d4567890-abcd-ef01-2345-6789abcdef01",
        "quantity": 2
      }
    ]
  }'

const invoice = await fetch('https://api.dolfinai.co/v1/invoices', {
  method: 'POST',
  headers: {
    'x-dolfin-api-key': 'dol_live_abc123',
    'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customerId: 'c3456789-abcd-ef01-2345-6789abcdef01',
    currency: 'GBP',
    dueDate: '2025-02-20T00:00:00Z',
    memo: 'Boiler repair at 12 Oak Lane - January 2025',
    lineItems: [
      {
        productId: 'd4567890-abcd-ef01-2345-6789abcdef01',
        quantity: 2,
      },
    ],
  }),
}).then(r => r.json());

Response:

{
  "id": "e5678901-abcd-ef01-2345-6789abcdef01",
  "organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
  "customerId": "c3456789-abcd-ef01-2345-6789abcdef01",
  "documentNumber": "INV-0001",
  "currency": "GBP",
  "issueDate": "2025-01-20T09:02:00Z",
  "dueDate": "2025-02-20T00:00:00Z",
  "status": "Draft",
  "subTotal": 300.00,
  "taxAmount": 0,
  "totalAmount": 300.00,
  "memo": "Boiler repair at 12 Oak Lane - January 2025",
  "lineItems": [
    {
      "productId": "d4567890-abcd-ef01-2345-6789abcdef01",
      "quantity": 2
    }
  ],
  "createdAt": "2025-01-20T09:02:00Z",
  "updatedAt": "2025-01-20T09:02:00Z"
}

The invoice is created in Draft status. You can add a taxRateId to each line item if you need to apply tax.

Step 4: Send the Invoice

Send the draft invoice to the customer. This marks it as sent and delivers it, this will also set the issue date of the invoice.

curl -X POST https://api.dolfinai.co/v1/invoices/e5678901-abcd-ef01-2345-6789abcdef01/send \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8"

const sentInvoice = await fetch(
  'https://api.dolfinai.co/v1/invoices/e5678901-abcd-ef01-2345-6789abcdef01/send',
  {
    method: 'POST',
    headers: {
      'x-dolfin-api-key': 'dol_live_abc123',
      'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
    },
  }
).then(r => r.json());

Response:

{
  "id": "e5678901-abcd-ef01-2345-6789abcdef01",
  "organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
  "customerId": "c3456789-abcd-ef01-2345-6789abcdef01",
  "documentNumber": "INV-0001",
  "currency": "GBP",
  "issueDate": "2025-01-20T09:02:00Z",
  "dueDate": "2025-02-20T00:00:00Z",
  "status": "Sent",
  "subTotal": 300.00,
  "taxAmount": 0,
  "totalAmount": 300.00,
  "memo": "Boiler repair at 12 Oak Lane - January 2025",
  "createdAt": "2025-01-20T09:02:00Z",
  "updatedAt": "2025-01-20T09:03:00Z"
}

The invoice status changes from Draft to Sent.

Summary

Step	Endpoint	What it does
1	`POST /v1/customers`	Create the customer to bill
2	`POST /v1/products`	Define the product or service
3	`POST /v1/invoices`	Create a draft invoice with line items
4	`POST /v1/invoices/{id}/send`	Send the invoice to the customer

Getting started

Accounts Payable

Accounts Receivable

Quick Start - AR

Prerequisites

Overview

Step 1: Create a Customer

Step 2: Create a Product

Step 3: Create an Invoice

Step 4: Send the Invoice

Summary

Next Steps

API Reference

Client Integration

​Prerequisites

​Overview

​Step 1: Create a Customer

​Step 2: Create a Product

​Step 3: Create an Invoice

​Step 4: Send the Invoice

​Summary

​Next Steps

API Reference

Client Integration

Prerequisites

Overview

Step 1: Create a Customer

Step 2: Create a Product

Step 3: Create an Invoice

Step 4: Send the Invoice

Summary

Next Steps