JSON API » customers » customers/create

Creates a new customer. Normally, this just creates an empty customer, and other */create functions can then be used to create features within the new customer. Alternatively, a residential customer can be created that includes a person, telephone line, and mailbox all in one function call.

Input parameters

Requires authentication and the commerce role privilege.

Name	Type	Description	Required	Default value
auth_username	String	Authentication username.	Yes
auth_password	String	Authentication password.	Yes
name	String	Name.	Yes
plan	Integer	ID of rate plan customer is on.	Yes
email	String	Email address.	Yes
account	String	Account number for vouchers.	No	Empty string.
address1	String	Address line 1.	No	Empty string.
address2	String	Address line 2.	No	Empty string.
address3	String	Address line 3.	No	Empty string.
address_city	String	Address city.	No	Empty string.
address_code	String	Post or zip code.	No	Empty string.
address_other	String	Address other information.	No	Empty string.
address_state	String	Address state.	No	Empty string.
affiliate_customer	Integer	ID of affiliate customer. 0 for none.	No	0
affiliate_percentage	Integer	Percentage to give affiliate.	No	0
affiliate_type	String	"revenue", "profit" or empty string for none.	No	Empty string.
auto_topup	Decimal	Request auto-topup when balance falls below this amount. Has no effect unless email_low_balance=1.	No	0.00
balance	Decimal	Initial balance.	No	0.00
bank_account_name	String	Bank account name.	No	Empty string.
bank_account_number	String	Bank account number.	No	Empty string.
bank_code	String	Bank code.	No	Empty string.
bank_name	String	Bank name.	No	Empty string.
bill_ref	String	Billing reference.	No	Empty string.
bill_type	String	Billing type. "callshop", "external", "none", "postpaid", "prepaid", "prepaid_calls", or "prepaid_invoices".	No	System default.
bulk_calls	Integer	Maximum concurrent bulk dialler calls. -1 for default limit. -2 for rate plan setting.	No	-2
call_maximum	Decimal	Maximum call spending per day. -1 for no limit. -2 for rate plan setting.	No	-2
call_maximum_period	String	Billing period for telephone line maximum call spending. "daily" or "monthly".	No	"daily"
callerid	String	Default callerid. Empty string for none.	No	Empty string.
callerid_in_external	Integer	Whether to send external callerid to telephones. 1 for yes. 0 for no. -2 for rate plan setting.	No	-2
common_routing	Integer	Share features with parent and related customers. 1 for yes. 0 for no.	No	0
conference_calls	Integer	Maximum concurrent conference calls. -1 for no limit. -2 for rate plan setting.	No	-2
contract	String	Minimum contract. "plan" for rate plan setting, "1_month", "3_month", "6_month", "1_year", "18_month", "2_year", "3_year", or empty string for none.	No	"plan"
cos	Integer	ID of default class of service. 1 for system COS that allows all calls.	No	1
country	String	Address country.	No	Country of parent.
credit	Decimal	Maximum amount customer may go into negative balance.	No	0.00
credit_extra	Decimal	Temporary amount added to credit.	No	0.00
credit_extra_timegroup	Integer	ID of time group when extra credit is active. 0 for always.	No	0
creditcard_expiry_month	Integer	Credit card expiry month from 1 to 12.	No	0
creditcard_expiry_year	Integer	Credit card expiry year.	No	0
creditcard_issue	Integer	Credit card issue number.	No	0
creditcard_name	String	Credit card name.	No	Empty string.
creditcard_number	String	Credit card number.	No	Empty string.
creditcard_start_month	Integer	Credit card start month from 1 to 12.	No	0
creditcard_start_year	Integer	Credit card start year.	No	0
creditcard_type	String	Credit card type.	No	Empty string.
creditcard_verification	String	Credit card verification number.	No	Empty string.
currency	String	Currency.	No	Currency of parent.
description	String	Description.	No	Empty string.
dialplan	String	Dial plan.	No	Dial plan of parent.
digit_names	String	The order digit names are in. "forename_surname" or "surname_forename".	No	"surname_forename"
direct_debit_agreed	Integer	1 if the customer has agreed to pay by direct debit, 0 if they haven't.	No	0
directory	Integer	1 to include in directory, 0 not to.	No	1
email_low_balance	Integer	1 to send customer an email when balance falls below a threshold, 0 not to.	No	0
events_url	String	URL to send events to. Empty string for none.	No	Empty string.
fax	String	Fax number.	No	Empty string.
fax_format	String	The format faxes are saved in. "pdf" or "tiff".	No	"pdf"
forename	String	First name for residential user. Not used for normal customers.	Yes if interface=residential.	Empty string.
google_checkout_id	String	Google Checkout ID. Affects system owner customer and resellers only.	No	Empty string.
google_checkout_key	String	Google Checkout key. Affects system owner customer and resellers only.	No	Empty string.
huntgroup_dests	Integer	Maximum destinations per hunt group. -1 for no limit. -2 for rate plan setting.	No	-2
ingroup	Integer	ID of inbound group to add ported number to. Only used if porting number.	Only if porting number.
inmaximum	Integer	Maximum inbound calls. -1 for no limit. -2 for rate plan setting.	No	-2
interface	String	Empty string for normal customer, "residential" for residential customer.	No	Empty string.
invoice_prefix	String	A prefix to use on invoices to customers. Affects system owner customer and resellers only.	No	Empty string.
invoices	String	What to do with invoices. "plan" for rate plan setting, "queue", "customer", "parent", or empty string.	No	"plan"
invoice_detail	String	The detail to include in invoices. "plan" for rate plan setting, "summary", "transactions", "cdrs", "direction_cdrs", "group_cdrs", "source_cdrs", "group_transactions", "group_transactions_cdrs", "group_transactions_direction_cdrs", "group_transactions_group_cdrs", "group_transactions_source_cdrs", "transactions_cdrs", "transactions_direction_cdrs", "transactions_group_cdrs", or "transactions_source_cdrs".	No	"plan"
invoices_due	Integer	The number of days after creation invoices are due. -1 for never. -2 for rate plan setting.	No	-2
invoice_format	String	Invoice format. "plan" for rate plan setting, "pdf", or "xml".	No	"plan"
locked	Integer	1 to lock customer from using web interface, 0 not to.	No	0
locked_telephony	Integer	1 to lock customer from using telephony, 0 not to.	No	0
low_balance	Decimal	Low balance threshold.	No	0.00
maxmsg	String or integer	The maximum number of messages per mailbox directory. "plan" for rate plan setting.	No	"plan"
maxsecs	Integer	Maximum message duration in seconds. "plan" for rate plan setting.	No	"plan"
merchant_password	String	The password to send to the merchant gateway. Affects system owner customer and resellers only.	No	Empty string.
merchant_type	String	The merchant gateway to use. Affects system owner customer and resellers only.	No	Empty string.
merchant_username	String	The user name to send to the merchant gateway. Affects system owner customer and resellers only.	No	Empty string.
music	Integer	ID of default music. 0 for system default.	No	0
next_invoice	Integer	The number of the next invoice to send. Affects system owner customer and resellers only.	No	1
outmaximum	Integer	Maximum outbound calls. -1 for no limit. -2 for rate plan setting.	No	-2
on_error	String	"hangup" to hang up on error, "message" to play a message.	No	"message"
overmax	Integer	1 to allow customer to go over maximum calls. 0 not to. -2 for rate plan setting.	No	-2
pagegroup_dests	Integer	Maximum destinations per page group. -1 for no limit. -2 for rate plan setting.	No	-2
parent	Integer	ID of parent customer.	No	Customer of authentication user.
park_timeout	Integer	Parking timeout in seconds.	No	300
payment_type	String	Payment type. "creditcard", "direct_debit", "external", or "none".	No	System default.
paypal	String	PayPal account. Affects system owner customer and resellers only.	No	Empty string.
peer1	Integer	ID of peer to route all outbound calls to. -2 for the rate plan setting.	No	-2
prefix	String	Prefix.	No	Empty string.
provision_password	String	Provisioning password.	No	Empty string.
purge_messages	Integer	When to purge old voicemails and faxes. "plan" for rate plan setting, "1_day", "1_week", "1_month", "3_months", "6_months", "1_year", or empty string for never.	No	"plan"
queue_calls	Integer	Maximum concurrent queue calls. -1 for no limit. -2 for rate plan setting.	No	-2
queue_dests	Integer	Maximum destinations per queue. -1 for no limit. -2 for rate plan setting.	No	-2
record_maximum	Integer	Maximum number of seconds of record to keep when fees run. -1 for unlimited. -2 for rate plan setting.	No	-2
region	Integer	Region. 0 for none.	No	System default.
seconds_left	Integer	The number of included seconds the customer has available.	No	0
snumber	String	Number to purchase for residential user. Not used for normal customers.	Yes if interface=residential.	Empty string.
source	String	Only allow from this IP address. Empty string for any.	No	Empty string.
surname	String	last name for residential user. Not used for normal customers.	Yes if interface=residential.	Empty string.
tax_number	String	Tax number.	No	Empty string.
technical_contact	String	Technical contact email address(es). Separate addresses with spaces.	No	Empty string.
telephone	String	Telephone number.	No	Empty string.
tickets	Integer	1 to accept tickets from sub-customers, 0 not to.	No	1
timezone	String	Time zone. Empty string for system default.	No	Time zone of parent.
title	String	Title for residential user. Not used for normal customers.	Yes if interface=residential.	Empty string.
totalmaximum	Integer	Maximum total calls. -1 for no limit. -2 for rate plan setting.	No	-2
username	String	Web user name for residential user. Not used for normal customers.	Yes if interface=residential.	Empty string.
virtual_logout	Integer	1 to log out virtual phones each night, 0 not to.	No	0
validation	Integer	1 to validate input then return, 0 for full action.	No	0

If interface=residential is specified, then the forename, surname, title, username, and snumber parameters are required, otherwise they are not used.

The creditcard_verification is not stored in the database.

Responses

Code	Description
200	Success.
201	Input passed validation. Only returned if validation=1.
400	Invalid input parameters specified. Check the key and message fields for more details.
401	The authentication details provided are invalid.
402	Your role does not allow this.
403	Your rate plan does not allow this.
500	An internal error occurred. Check the key and message fields for more details.

Data returned

The ID of the created customer. If interface=residential is specified, the person password, telephone line password, and mailbox PIN are also returned.

Example: With required parameters

http://enswitch.example.com/api/json/customers/create/?auth_username=user;auth_password=password;name=example;plan=123;email=user@example.com

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ], "data":{ "id":123 } }

Change history

Version	Changes
4.2	call_maximum_period input parameter added.
4.1	creditcard_verification no longer written to database. tickets parameter added.
3.15	invoice_detail parameter updated to include grouped transactions. maxsecs and source input parameters added.
3.14	bulk_calls, conference_calls, cos, events_url, huntgroup_dests, ingroup, pagegroup_dests, queue_calls, and queue_dests input parameters added.
3.13	Function added.