Create a customer

TRA fiscal receipts and customers

As covered on the create a fiscal receipt page, a fiscal receipt or invoice contains:

customer details (required for B2B; optional for B2C walk-in retail)
at least one line item
payment breakdown

In this guide, we'll walk through creating a customer record via POST /customers.

B2C vs. B2B customer identification

The TRA EFDMS recognizes multiple buyer identification schemes:

Scenario	Identification Type	Description
B2B sale	`TAX_IDENTIFICATION_NUMBER`	Buyer's 9-digit TIN is required. Required when the buyer will claim input VAT.
B2C with ID	`NATIONAL_IDENTIFICATION_AUTHORITY`	Citizen's 20-digit NIDA number.
B2C with ID	`PASSPORT`	Passport number for foreign visitors.
B2C with ID	`VOTERS_NUMBER`	Voter ID card number.
B2C with ID	`DRIVING_LICENCE`	Driver's license number.
B2C walk-in	`NO_IDENTIFICATION`	Anonymous / retail cash sales without identity registration.

For detailed formatting rules, see Customer attributes.

Creating a customer

To register a customer via POST /customers, supply the following request body:

{
  "name": "ACME Tanzania Limited",
  "identification_type": "TAX_IDENTIFICATION_NUMBER",
  "identification_number": "123456789",
  "vat_registration_number": "40-123456-E",
  "mobile_number": "+255712345678",
  "email": "[email protected]",
  "return_if_exists": false
}

API response

When successfully created, the API returns a 201 Created status with the customer record:

{
  "id": "customer_01HC3J1VVVM05YCTS61G7V3KC6",
  "name": "ACME Tanzania Limited",
  "identification_type": "TAX_IDENTIFICATION_NUMBER",
  "identification_number": "123456789",
  "vat_registration_number": "40-123456-E",
  "mobile_number": "+255712345678",
  "email": "[email protected]",
  "created_at": "2026-07-14T00:00:00Z",
  "updated_at": "2026-07-14T00:00:00Z"
}

Using `return_if_exists`

When registering customers programmatically from an external CRM or POS, setting "return_if_exists": true instructs DigiTax to return the existing matching customer rather than returning a 409 Conflict error if the identification_number is already registered under your branch.

Walk-in retail customers

For B2C walk-in transactions where no buyer identity is recorded, you can create a generic retail customer with "identification_type": "NO_IDENTIFICATION", or pass a default walk-in customer record to POST /invoices.