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.

NameTypeDescriptionRequiredDefault value
auth_usernameStringAuthentication username.Yes
auth_passwordStringAuthentication password.Yes
nameStringName.Yes
planIntegerID of rate plan customer is on.Yes
emailStringEmail address.Yes
accountStringAccount number for vouchers.NoEmpty string.
address1StringAddress line 1.NoEmpty string.
address2StringAddress line 2.NoEmpty string.
address3StringAddress line 3.NoEmpty string.
address_cityStringAddress city.NoEmpty string.
address_codeStringPost or zip code.NoEmpty string.
address_otherStringAddress other information.NoEmpty string.
address_stateStringAddress state.NoEmpty string.
affiliate_customerIntegerID of affiliate customer. 0 for none.No0
affiliate_percentageIntegerPercentage to give affiliate.No0
affiliate_typeString"revenue", "profit" or empty string for none.NoEmpty string.
auto_topupDecimalRequest auto-topup when balance falls below this amount. Has no effect unless email_low_balance=1.No0.00
balanceDecimalInitial balance.No0.00
bank_account_nameStringBank account name.NoEmpty string.
bank_account_numberStringBank account number.NoEmpty string.
bank_codeStringBank code.NoEmpty string.
bank_nameStringBank name.NoEmpty string.
bill_refStringBilling reference.NoEmpty string.
bill_typeStringBilling type. "callshop", "external", "none", "postpaid", "prepaid", "prepaid_calls", or "prepaid_invoices".NoSystem default.
bulk_callsIntegerMaximum concurrent bulk dialler calls. -1 for default limit. -2 for rate plan setting.No-2
call_maximumDecimalMaximum call spending per day. -1 for no limit. -2 for rate plan setting.No-2
calleridStringDefault callerid. Empty string for none.NoEmpty string.
callerid_in_externalIntegerWhether to send external callerid to telephones. 1 for yes. 0 for no. -2 for rate plan setting.No-2
common_routingIntegerOther customers to check for call routing. 0 for none. Logical 1 for parent, 2 for siblings and 4 for children.No0
conference_callsIntegerMaximum concurrent conference calls. -1 for no limit. -2 for rate plan setting.No-2
contractStringMinimum 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"
cosIntegerID of default class of service. 1 for system COS that allows all calls.No1
countryStringAddress country.NoCountry of parent.
creditDecimalMaximum amount customer may go into negative balance.No0.00
credit_extraDecimalTemporary amount added to credit.No0.00
credit_extra_timegroupIntegerID of time group when extra credit is active. 0 for always.No0
creditcard_expiry_monthIntegerCredit card expiry month from 1 to 12.No0
creditcard_expiry_yearIntegerCredit card expiry year.No0
creditcard_issueIntegerCredit card issue number.No0
creditcard_nameStringCredit card name.NoEmpty string.
creditcard_numberStringCredit card number.NoEmpty string.
creditcard_start_monthIntegerCredit card start month from 1 to 12.No0
creditcard_start_yearIntegerCredit card start year.No0
creditcard_typeStringCredit card type.NoEmpty string.
creditcard_verificationStringCredit card verification number.NoEmpty string.
currencyStringCurrency.NoCurrency of parent.
descriptionStringDescription.NoEmpty string.
dialplanStringDial plan.NoDial plan of parent.
digit_namesStringThe order digit names are in. "forename_surname" or "surname_forename".No"surname_forename"
direct_debit_agreedInteger1 if the customer has agreed to pay by direct debit, 0 if they haven't.No0
directoryInteger1 to include in directory, 0 not to.No1
email_low_balanceInteger1 to send customer an email when balance falls below a threshold, 0 not to.No0
events_urlStringURL to send events to. Empty string for none.NoEmpty string.
faxStringFax number.NoEmpty string.
fax_formatStringThe format faxes are saved in. "pdf" or "tiff".No"pdf"
forenameStringFirst name for residential user. Not used for normal customers.Yes if interface=residential.Empty string.
google_checkout_idStringGoogle Checkout ID. Affects system owner customer and resellers only.NoEmpty string.
google_checkout_keyStringGoogle Checkout key. Affects system owner customer and resellers only.NoEmpty string.
huntgroup_destsIntegerMaximum destinations per hunt group. -1 for no limit. -2 for rate plan setting.No-2
ingroupIntegerID of inbound group to add ported number to. Only used if porting number.Only if porting number.
inmaximumIntegerMaximum inbound calls. -1 for no limit. -2 for rate plan setting.No-2
interfaceStringEmpty string for normal customer, "residential" for residential customer.NoEmpty string.
invoice_prefixStringA prefix to use on invoices to customers. Affects system owner customer and resellers only.NoEmpty string.
invoicesStringWhat to do with invoices. "plan" for rate plan setting, "queue", "customer", "parent", or empty string.No"plan"
invoice_detailStringThe detail to include in invoices. "plan" for rate plan setting, "summary", "transactions", "cdrs", "direction_cdrs", "group_cdrs", "source_cdrs", "transactions_cdrs", "transactions_direction_cdrs", "transactions_group_cdrs", or "transactions_source_cdrs".No"plan"
invoices_dueIntegerThe number of days after creation invoices are due. -1 for never. -2 for rate plan setting.No-2
invoice_formatStringInvoice format. "plan" for rate plan setting, "pdf", or "xml".No"plan"
lockedInteger1 to lock customer from using web interface, 0 not to.No0
locked_telephonyInteger1 to lock customer from using telephony, 0 not to.No0
low_balanceDecimalLow balance threshold.No0.00
maxmsgString or integerThe maximum number of messages per mailbox directory. "plan" for rate plan setting.No"plan"
merchant_passwordStringThe password to send to the merchant gateway. Affects system owner customer and resellers only.NoEmpty string.
merchant_typeStringThe merchant gateway to use. Affects system owner customer and resellers only.NoEmpty string.
merchant_usernameStringThe user name to send to the merchant gateway. Affects system owner customer and resellers only.NoEmpty string.
musicIntegerID of default music. 0 for system default.No0
next_invoiceIntegerThe number of the next invoice to send. Affects system owner customer and resellers only.No1
outmaximumIntegerMaximum outbound calls. -1 for no limit. -2 for rate plan setting.No-2
on_errorString"hangup" to hang up on error, "message" to play a message.No"message"
overmaxInteger1 to allow customer to go over maximum calls. 0 not to. -2 for rate plan setting.No-2
pagegroup_destsIntegerMaximum destinations per page group. -1 for no limit. -2 for rate plan setting.No-2
parentIntegerID of parent customer.NoCustomer of authentication user.
park_timeoutIntegerParking timeout in seconds.No300
payment_typeStringPayment type. "creditcard", "direct_debit", "external", or "none".NoSystem default.
paypalStringPayPal account. Affects system owner customer and resellers only.NoEmpty string.
peer1IntegerID of peer to route all outbound calls to. -2 for the rate plan setting.No-2
prefixStringPrefix.NoEmpty string.
provision_passwordStringProvisioning password.NoEmpty string.
purge_messagesIntegerWhen 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_callsIntegerMaximum concurrent queue calls. -1 for no limit. -2 for rate plan setting.No-2
queue_destsIntegerMaximum destinations per queue. -1 for no limit. -2 for rate plan setting.No-2
record_maximumIntegerMaximum number of seconds of record to keep when fees run. -1 for unlimited. -2 for rate plan setting.No-2
regionIntegerRegion. 0 for none.NoSystem default.
seconds_leftIntegerThe number of included seconds the customer has available.No0
snumberStringNumber to purchase for residential user. Not used for normal customers.Yes if interface=residential.Empty string.
surnameStringlast name for residential user. Not used for normal customers.Yes if interface=residential.Empty string.
tax_numberStringTax number.NoEmpty string.
technical_contactStringTechnical contact email address(es). Separate addresses with spaces.NoEmpty string.
telephoneStringTelephone number.NoEmpty string.
timezoneStringTime zone. Empty string for system default.NoTime zone of parent.
titleStringTitle for residential user. Not used for normal customers.Yes if interface=residential.Empty string.
totalmaximumIntegerMaximum total calls. -1 for no limit. -2 for rate plan setting.No-2
usernameStringWeb user name for residential user. Not used for normal customers.Yes if interface=residential.Empty string.
virtual_logoutInteger1 to log out virtual phones each night, 0 not to.No0
validationInteger1 to validate input then return, 0 for full action.No0

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

Responses

CodeDescription
200Success.
201Input passed validation. Only returned if validation=1.
400Invalid input parameters specified. Check the key and message fields for more details.
401The authentication details provided are invalid.
402Your role does not allow this.
403Your rate plan does not allow this.
500An 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

VersionChanges
3.14bulk_calls, conference_calls, cos, events_url, huntgroup_dests, ingroup, pagegroup_dests, queue_calls, and queue_dests input parameters added.
3.13Function added.