CreateClients

This method creates a client record.

Supplementary SWAGGER documentation is available here: https://api.catch-e.com/docs/#/Clients/createClient

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / APIs and check on Clients:Create.

Note: This API is not configured for external use. Contact your Account Manager to discuss access to this API.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

https://api.catch-e.com/fm/clients

Headers

Key

Format

Notes

Mandatory

Audit-User-Id

string

Pass a user_id here to create audit records with this user's details. This can only be done if the authenticated API user has Roles / APIs checked for the permission Audit:UserIdOverride

No

Body (JSON)

Key

Format

Notes

Mandatory

client_code

string

Unique client code

Yes

user_id

string

System user ID for client owner

Yes

user_id_sales

string

System user ID for sales representative

Yes

name

string

Client name

No

client_type

string

Type of client (e.g. fleet, lead)

No

client_id_external

string

External client identifier

No

client_id_parent

string

Parent client ID for hierarchical structures

No

channel_id

string

Channel ID

No

client_industry_id

string

Industry classification ID

No

sic_code

string

Standard Industry Code

No

financial_year_end

string

Financial year end month

No

company_tax_rate

number

Company tax rate

No

address1

string

Address line 1

No

address2

string

Address line 2

No

area

string

Suburb/area

No

state

string

State abbreviation

No

pcode

string

Postcode

No

country_id

string

Country ID

No

phone

string

Phone number

No

mobile

string

Mobile number

No

fax

string

Fax number

No

abn

string

Australian Business Number

No

acn

string

Australian Company Number

No

arbn

string

Australian Registered Body Number

No

business_start_date

date

Business start date (YYYY-MM-DD)

No

contact1_name

string

Contact 1 name

No

contact1_job_title

string

Contact 1 job title

No

contact1_phone

string

Contact 1 phone

No

contact1_email

string

Contact 1 email

No

contact1_note

string

Contact 1 note

No

contact2_name

string

Contact 2 name

No

contact2_job_title

string

Contact 2 job title

No

contact2_phone

string

Contact 2 phone

No

contact2_email

string

Contact 2 email

No

contact2_note

string

Contact 2 note

No

contact3_name

string

Contact 3 name

No

contact3_job_title

string

Contact 3 job title

No

contact3_phone

string

Contact 3 phone

No

contact3_email

string

Contact 3 email

No

contact3_note

string

Contact 3 note

No

contact4_name

string

Contact 4 name

No

contact4_job_title

string

Contact 4 job title

No

contact4_phone

string

Contact 4 phone

No

contact4_email

string

Contact 4 email

No

contact4_note

string

Contact 4 note

No

contact5_name

string

Contact 5 name

No

contact5_job_title

string

Contact 5 job title

No

contact5_phone

string

Contact 5 phone

No

contact5_email

string

Contact 5 email

No

contact5_note

string

Contact 5 note

No

guarantor1_name

string

Guarantor 1 name

No

guarantor1_phone

string

Guarantor 1 phone

No

guarantor2_name

string

Guarantor 2 name

No

guarantor2_phone

string

Guarantor 2 phone

No

guarantor3_name

string

Guarantor 3 name

No

guarantor3_phone

string

Guarantor 3 phone

No

postal_address1

string

Postal address line 1

No

postal_address2

string

Postal address line 2

No

postal_area

string

Postal suburb/area

No

postal_state

string

Postal state

No

postal_pcode

string

Postal postcode

No

postal_country_id

string

Postal country ID

No

supplier_id_insurer

string

Insurer supplier ID

No

supplier_id_broker

string

Insurance broker supplier ID

No

supplier_id_repairer

string

Repairer supplier ID

No

policy_number

string

Insurance policy number

No

billing_interval

string

Billing interval (e.g. monthly)

No

billing_type_flag

string

Billing type (e.g. periodic)

No

billing_terms_id

string

Billing terms ID

No

payment_method

string

Payment method (e.g. eft)

No

bank_bsb

string

Bank BSB number

No

bank_account_number

string

Bank account number

No

bank_account_suffix

string

Bank account suffix (NZ only)

No

report_delivery_type

string

Report delivery type (e.g. email)

No

billing_email_attachment_type

string

Email attachment type (e.g. pdf)

No

purchase_order_no

string

Purchase order number

No

rcti_flag

string

RCTI flag (yes/no)

No

employer_fbt_type

string

FBT type for employer

No

fbt_reporting_flag

string

FBT reporting flag (yes/no)

No

sl_export_flag

string

SL export flag (yes/no)

No

reg_ctp_type

string

Registration CTP type

No

invoice_options

string

Invoice options

No

allow_quoting_flag

string

Allow quoting flag (yes/no)

No

interim_service_flag

string

Interim service flag (yes/no)

No

shared_fleet_flag

string

Shared fleet flag (yes/no)

No

etags_managed_flag

string

eTags managed flag (yes/no)

No

novated_leases_flag

string

Novated leases flag (yes/no)

No

client_group_id

string

Client group ID

No

Input Fields (JSON)

{ "client_code": "TEST001", "user_id": "10842", "user_id_sales": "10842", "name": "Test Client", "client_type": "fleet", "address1": "123 Business Street", "address2": "Suite 100", "area": "Keysborough", "state": "VIC", "pcode": "3173", "phone": "03 9999 9999", "abn": "12 345 678 901", "acn": "345 678 901", "contact1_name": "John Smith", "contact1_email": "john@example.com", "contact1_phone": "03 9999 9999", "billing_interval": "monthly", "report_delivery_type": "email", "payment_method": "eft", "allow_quoting_flag": "yes" }

Response Details

Validation Message

Comments

201 Created

A successful response returns all fields in the client record, client defaults, client packaging defaults, and associated records

403 - Forbidden

You do not have permissions for this request

422 - Unprocessable Entity

The syntax of the fields key is not correct. Having spaces in the list of fields is one possible reason

Successful Response Example

The response returns all client fields including client defaults and client packaging defaults. A successful response includes the newly created client(s) with generated client_id and comprehensive nested structures:

{ "_links": { "self": { "href": "https://api.test.catch-e.com/fm/clients" } }, "_embedded": { "fm_clients": [ { "bespoke_field_values": [], "inclusion_client_exclusions": [], "client_defaults": { "client_default_id": "100547", "client_id": "100547", "client_group_flag": "no", "relief_vehicle_flag": "yes", "delivery_fee_funded_flag": "no", "fuel_on_delivery_funded_flag": "no", "supplier_id_financier": null, "policy_owner_type": "driver", "supplier_id_insurer": null, "residual_margin_rate": 0, "residual_margin_rate_commercial": 0, "excess_km_rate": 0, "establishment_fee": 0, "management_fee": 0, "maintenance_program_fee": 0, "novated_commission_rate": 0, "insurance_broker_fee_exempt_flag": "yes", "carbon_emission_offset_flag": "yes", "roadside_assistance_plan_code": "", "accident_management_fee": 0 }, "client_id": "100547", "client_id_external": "0", "client_code": "Test002", "client_id_parent": "0", "name": "Test Client", "channel_id": "0", "client_type": "fleet", "client_industry_id": "0", "client_credit_ratings_id": null, "sic_code": "", "financial_year_end": "June", "company_tax_rate": 0, "user_id": "11244", "user_id_sales": "11244", "address1": "123 Business Street", "address2": "Suite 100", "area": "Keysborough", "state": "VIC", "pcode": "3173", "country_id": null, "phone": "03 9999 9999", "mobile": null, "fax": null, "abn": "12 345 678 901", "acn": "345 678 901", "arbn": null, "corporate_type_id": "0", "business_start_date": "0000-00-00", "contact1_name": "John Smith", "contact1_job_title": "", "contact1_phone": "03 9999 9999", "contact1_email": "john@example.com", "contact1_note": null, "billing_interval": "monthly", "report_delivery_type": "email", "payment_method": "eft", "allow_quoting_flag": "yes", "dirty_flag": "2024-07-01 02:45:50", "_embedded": { "client_packaging_defaults": { "aba_description": "", "aba_self_balancing_flag": "yes", "apca_number": "", "bank_account_enabled_flag": "yes", "bank_account_name": "", "bank_account_name_short": "", "bank_account_number": null, "bank_bsb": null, "client_id": "100547", "client_packaging_default_id": "14728602546281119856", "financial_institution_id": null, "pay_run_processing_state": null, "pay_run_start": 0, "pay_run_start2": 0, "pay_run_start3": 0, "pay_run_weekend_treatment": null, "payroll_fbt": null, "payroll_gst": null, "payroll_itc": null, "payroll_lcc": null, "payroll_post_tax": null, "payroll_pre_tax": null, "report_delivery_type": "email", "report_groups": [], "taxable_sales": "all-items", "_links": { "self": { "href": "https://api.test.catch-e.com/sp/client/packaging-defaults/100547" } } } }, "_links": { "self": { "href": "https://api.test.catch-e.com/fm/clients/100547" } } } ] }, "total_items": 1 }

Creating Multiple Clients

To create multiple Client records you can include multiple datasets in a single request. An example is shown here (displaying only minimum fields in this example):

[ { "client_code": "CLIENTONE", "user_id": "10842", "user_id_sales": "10842" }, { "client_code": "CLIENTTWO", "user_id": "10842", "user_id_sales": "10842" } ]

The response will return all created clients with their newly generated client_id values and all associated client defaults and packaging defaults records.