KintsugiKintsugi
API Lab

Managing Customers

Overview

Customer records in Kintsugi store customer information and enable exemption management. While not required for all integrations, customer records are essential when dealing with tax-exempt customers (nonprofits, resellers, etc.) or when you need to track customer-specific tax information.

When to Create Customer Records

  • Tax-exempt customers: Nonprofits, resellers, or other exempt entities
  • Customer exemptions: When customers have jurisdiction-specific exemptions
  • Customer tracking: When you need to maintain customer tax history

For regular taxable customers, you can pass customer information directly in transaction requests without creating separate customer records.

Workflow

  1. Create a Customer - Create a customer record with address information
  2. Retrieve Customers - Search and retrieve customer records

Step 1: Create a Customer

Create a customer record using the API Lab below with POST /v1/customers.

Example Request

{
  "external_id": "CUST-001",
  "name": "Acme Corporation",
  "email": "contact@acme.com",
  "street_1": "123 Business St",
  "city": "San Francisco",
  "state": "CA",
  "postal_code": "94105",
  "country": "US"
}

Step 2: Retrieve Customers

After creating customers, retrieve them using GET /v1/customers. You can:

  • Search by external_id using the search_query parameter
  • Filter by country and state
  • Paginate through all customers

Authentication

This endpoint requires two headers:

  • x-api-key: Your API key
  • x-organization-id: Your organization ID

Both headers are required for authentication. You can find your API key and organization ID in your Kintsugi dashboard.

Try It Out

API LabSimulated
Runs in a simulated sandbox. Responses are generated from the API schema so you can explore each call safely; they never reach the live API, so the values are illustrative.
1Create customer
POST/v1/customers

Send a customer record. The response returns the new customer, including its id.

2Get customer by id
GET/v1/customers/{customer_id}

Fetch the customer you just created. The id from step 1 fills the path automatically.

Run the previous step to fill the path.

Required Fields

  • external_id: Your internal customer identifier (must be unique within your organization)
  • name: Customer name
  • email: Customer email address

Common Use Cases

Basic Customer Creation

Create a customer with minimal required fields:

{
  "external_id": "CUST-12345",
  "name": "John Doe",
  "street_1": "123 Main St",
  "city": "Seattle",
  "state": "WA",
  "postal_code": "98101",
  "country": "US"
}

Customer with Full Details

Include complete customer information:

{
  "external_id": "CUST-ABC-123",
  "name": "Acme Corporation",
  "email": "contact@acme.com",
  "phone": "555-123-4567",
  "street_1": "123 Business St",
  "street_2": "Suite 100",
  "city": "San Francisco",
  "county": "San Francisco",
  "state": "CA",
  "postal_code": "94105",
  "country": "US",
  "source": "API"
}

Exempt Customer

Create a customer that may be tax-exempt:

{
  "external_id": "CUST-NONPROFIT-001",
  "name": "Nonprofit Organization",
  "email": "info@nonprofit.org",
  "street_1": "456 Charity Ave",
  "city": "Austin",
  "state": "TX",
  "postal_code": "78701",
  "country": "US",
  "status": "ACTIVE"
}

Response Fields

  • id: Kintsugi's unique customer identifier
  • external_id: Your customer identifier
  • name: Customer name
  • email: Customer email
  • status: Customer status (ACTIVE, ARCHIVED)
  • address_status: Address verification status

Next Steps

Related Resources