> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Bulk Create Customers
> Create multiple customers in a single request
Each customer is processed independently. If some customers fail (e.g., duplicate email or customer key), the others will still be created. Check both `customers_created` and `customers_failed` arrays in the response to handle partial failures.
A maximum of **100 customers** can be created per request. Each customer accepts the same fields as the [single create endpoint](/api-reference/customers/post).
## OpenAPI
````yaml POST /api/v1/customers/bulk-create
openapi: 3.0.1
info:
title: Metrifox API Documentation
version: v1
description: >-
Welcome to Metrifox Platform's API documentation. This comprehensive API
suite enables seamless integration with our platform, providing secure and
efficient access to our services.
servers:
- url: https://{defaultHost}
variables:
defaultHost:
default: api.metrifox.com
security:
- api_key: []
paths:
/api/v1/customers/bulk-create:
post:
tags:
- Customers
summary: Create multiple customers in a single request
description: >
Creates up to 100 customers in a single request. Each customer is
processed independently — if one fails, the rest will still be created.
This is useful for:
- **Data migration**: Moving customers from an external system into
Metrifox
- **Batch onboarding**: Creating a batch of customers at once via API
- **CRM sync**: Programmatically importing customer records
Each customer in the `customers` array accepts the same fields as the
single [Create Customer](/api-reference/customers/post) endpoint.
The response includes both `customers_created` and `customers_failed`
arrays so you can handle partial failures gracefully.
operationId: bulkCreateCustomers
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customers
properties:
customers:
type: array
description: Array of customer objects to create (max 100)
maxItems: 100
items:
$ref: '#/components/schemas/CustomerCreateRequest'
examples:
mixed_customers:
summary: Business and Individual Customers
value:
customers:
- customer_type: BUSINESS
customer_key: acme_corp_001
primary_email: contact@acmecorp.com
legal_name: Acme Corporation
display_name: Acme Corp
currency: USD
timezone: America/New_York
address_line1: 123 Business Ave
city: New York
state: NY
country: United States
zip_code: '10001'
- customer_type: INDIVIDUAL
customer_key: jane_doe_001
primary_email: jane@example.com
first_name: Jane
last_name: Doe
currency: USD
timezone: America/Los_Angeles
- customer_type: BUSINESS
customer_key: globex_001
primary_email: info@globex.com
legal_name: Globex Corporation
display_name: Globex
currency: EUR
responses:
'200':
description: Bulk creation completed (may include partial failures)
content:
application/json:
schema:
type: object
properties:
statusCode:
type: integer
example: 200
message:
type: string
example: Bulk Customer Creation Completed
data:
type: object
properties:
total:
type: integer
description: Total number of customers submitted
successful_count:
type: integer
description: Number of customers created successfully
failed_count:
type: integer
description: Number of customers that failed
customers_created:
type: array
description: Details of successfully created customers
items:
type: object
properties:
index:
type: integer
description: Position in the original request array
customer_key:
type: string
data:
type: object
properties:
id:
type: string
format: uuid
customer_type:
type: string
primary_email:
type: string
display_name:
type: string
nullable: true
customers_failed:
type: array
description: Details of failed customer creations
items:
type: object
properties:
index:
type: integer
description: Position in the original request array
customer_key:
type: string
error:
type: string
description: Error message explaining why creation failed
errors:
type: object
examples:
all_succeeded:
summary: All customers created successfully
value:
statusCode: 200
message: Bulk Customer Creation Completed
meta: {}
data:
total: 3
successful_count: 3
failed_count: 0
customers_created:
- index: 0
customer_key: acme_corp_001
data:
id: 764c80e3-ed59-44a5-ba07-7ee5ba547774
customer_type: BUSINESS
primary_email: contact@acmecorp.com
display_name: Acme Corp
- index: 1
customer_key: jane_doe_001
data:
id: 864c80e3-ed59-44a5-ba07-7ee5ba547775
customer_type: INDIVIDUAL
primary_email: jane@example.com
display_name: Jane Doe
- index: 2
customer_key: globex_001
data:
id: 964c80e3-ed59-44a5-ba07-7ee5ba547776
customer_type: BUSINESS
primary_email: info@globex.com
display_name: Globex
customers_failed: []
errors: {}
partial_failure:
summary: Some customers failed
value:
statusCode: 200
message: Bulk Customer Creation Completed
meta: {}
data:
total: 3
successful_count: 2
failed_count: 1
customers_created:
- index: 0
customer_key: acme_corp_001
data:
id: 764c80e3-ed59-44a5-ba07-7ee5ba547774
customer_type: BUSINESS
primary_email: contact@acmecorp.com
display_name: Acme Corp
- index: 2
customer_key: globex_001
data:
id: 964c80e3-ed59-44a5-ba07-7ee5ba547776
customer_type: BUSINESS
primary_email: info@globex.com
display_name: Globex
customers_failed:
- index: 1
customer_key: jane_doe_001
error: Primary email has already been used
errors: {}
'400':
description: Bad request — empty array or exceeds 100 customer limit
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
empty_array:
summary: No customers provided
value:
statusCode: 400
message: At least one customer is required for bulk creation
errors: {}
limit_exceeded:
summary: Too many customers
value:
statusCode: 400
message: Cannot create more than 100 customers in a single request
errors: {}
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-codeSamples:
- lang: curl
label: cURL
source: |
curl -X POST https://api.metrifox.com/api/v1/customers/bulk-create \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"customers": [
{
"customer_type": "BUSINESS",
"customer_key": "acme_corp_001",
"primary_email": "contact@acmecorp.com",
"legal_name": "Acme Corporation",
"display_name": "Acme Corp"
},
{
"customer_type": "INDIVIDUAL",
"customer_key": "jane_doe_001",
"primary_email": "jane@example.com",
"first_name": "Jane",
"last_name": "Doe"
}
]
}'
- lang: python
label: Python SDK
source: |
from metrifox_sdk import MetrifoxClient
client = MetrifoxClient(api_key="your_api_key")
result = client.customers.bulk_create([
{
"customer_type": "BUSINESS",
"customer_key": "acme_corp_001",
"primary_email": "contact@acmecorp.com",
"legal_name": "Acme Corporation",
"display_name": "Acme Corp"
},
{
"customer_type": "INDIVIDUAL",
"customer_key": "jane_doe_001",
"primary_email": "jane@example.com",
"first_name": "Jane",
"last_name": "Doe"
}
])
- lang: js
label: JavaScript SDK
source: |
import { init } from "metrifox-js";
const metrifoxClient = init({
apiKey: process.env.METRIFOX_API_KEY
});
const result = await metrifoxClient.customers.bulkCreate({
customers: [
{
customer_type: "BUSINESS",
customer_key: "acme_corp_001",
primary_email: "contact@acmecorp.com",
legal_name: "Acme Corporation",
display_name: "Acme Corp"
},
{
customer_type: "INDIVIDUAL",
customer_key: "jane_doe_001",
primary_email: "jane@example.com",
first_name: "Jane",
last_name: "Doe"
}
]
});
- lang: ruby
label: Ruby SDK
source: |
require 'metrifox-sdk'
METRIFOX_SDK = MetrifoxSDK.init({ api_key: "your-api-key" })
result = METRIFOX_SDK.customers.bulk_create({
customers: [
{
customer_type: "BUSINESS",
customer_key: "acme_corp_001",
primary_email: "contact@acmecorp.com",
legal_name: "Acme Corporation",
display_name: "Acme Corp"
},
{
customer_type: "INDIVIDUAL",
customer_key: "jane_doe_001",
primary_email: "jane@example.com",
first_name: "Jane",
last_name: "Doe"
}
]
})
components:
schemas:
CustomerCreateRequest:
type: object
properties:
customer_type:
type: string
enum:
- BUSINESS
- INDIVIDUAL
description: Type of customer
customer_key:
type: string
description: Unique identifier of the customer in your application
primary_email:
type: string
format: email
description: Primary email address for the customer
primary_phone:
type: string
description: Primary phone number for the customer
legal_name:
type: string
description: Legal business name
display_name:
type: string
description: Display name for the business
legal_number:
type: string
description: Legal registration number
tax_identification_number:
type: string
description: Tax identification number
logo_url:
type: string
format: uri
description: URL to company logo
website_url:
type: string
format: uri
description: Company website URL
account_manager:
type: string
description: Assigned account manager
first_name:
type: string
description: First name
middle_name:
type: string
description: Middle name
last_name:
type: string
description: Last name
date_of_birth:
type: string
format: date
description: Date of birth (for individuals)
billing_email:
type: string
format: email
description: Email address for billing communications
timezone:
type: string
description: Preferred timezone
language:
type: string
description: Preferred language for communications
currency:
type: string
description: Preferred currency for billing
tax_status:
type: string
enum:
- TAXABLE
- TAX_EXEMPT
- REVERSE_CHARGE
description: Tax status of the customer
address_line1:
type: string
description: First line of address
address_line2:
type: string
description: Second line of address
city:
type: string
description: City name
state:
type: string
description: State or province
country:
type: string
description: Country name
zip_code:
type: string
description: ZIP or postal code
shipping_address_line1:
type: string
description: First line of shipping address
shipping_address_line2:
type: string
description: Second line of shipping address
shipping_city:
type: string
description: Shipping city name
shipping_state:
type: string
description: Shipping state or province
shipping_country:
type: string
description: Shipping country name
shipping_zip_code:
type: string
description: Shipping ZIP or postal code
billing_configuration:
$ref: '#/components/schemas/BillingConfiguration'
tax_identifications:
type: array
items:
$ref: '#/components/schemas/TaxIdentification'
description: Array of tax identification numbers
contact_people:
type: array
items:
$ref: '#/components/schemas/ContactPerson'
description: List of contact persons for the business
payment_terms:
type: array
items:
$ref: '#/components/schemas/PaymentTerm'
description: Payment terms configuration
metadata:
type: object
additionalProperties: true
description: Custom metadata
email_addresses:
type: array
items:
$ref: '#/components/schemas/EmailAddress'
description: List of additional email addresses
phone_numbers:
type: array
items:
$ref: '#/components/schemas/PhoneNumber'
description: List of additional phone numbers
documents:
type: object
description: Optional documents to attach to the customer
required:
- customer_type
- customer_key
- primary_email
ErrorResponse:
type: object
properties:
message:
type: string
description: Error message
errors:
type: object
additionalProperties: true
description: Detailed error information
BillingConfiguration:
type: object
properties:
preferred_payment_gateway:
type: string
description: Preferred payment gateway
preferred_payment_method:
type: string
description: Preferred payment method
billing_email:
type: string
format: email
description: Email address for billing communications
billing_address:
type: string
description: Billing address
payment_reminder_days:
type: integer
description: Number of days before payment reminder
additionalProperties: true
TaxIdentification:
type: object
properties:
type:
type: string
description: Type of tax identification (e.g., EIN, VAT, GST)
number:
type: string
description: Tax identification number
country:
type: string
description: Country where tax ID is registered
required:
- type
- number
- country
ContactPerson:
type: object
properties:
first_name:
type: string
description: First name of contact person
last_name:
type: string
description: Last name of contact person
email_address:
type: string
format: email
description: Email address of contact person
designation:
type: string
description: Job title or designation
department:
type: string
description: Department name
is_primary:
type: boolean
default: false
description: Whether this is the primary contact person
phone_number:
type: string
description: Phone number for this contact person
required:
- first_name
- last_name
- email_address
PaymentTerm:
type: object
properties:
type:
type: string
description: Type of payment term (e.g., Net 30, Net 15)
value:
type: string
description: Payment term value
required:
- type
- value
EmailAddress:
type: object
properties:
email:
type: string
format: email
description: Email address
is_primary:
type: boolean
default: false
description: Whether this is the primary email address
required:
- email
PhoneNumber:
type: object
properties:
phone_number:
type: string
description: Phone number
country_code:
type: string
description: Country code (e.g., +1, +44)
is_primary:
type: boolean
default: false
description: Whether this is the primary phone number
required:
- phone_number
- country_code
securitySchemes:
api_key:
type: apiKey
name: x-api-key
in: header
````